Skip to main content

Apply-IdentityOverlay

Apply-IdentityOverlay (shipped in octo-tools/modules/Apply-IdentityOverlay.psm1) declaratively applies a YAML overlay file to the blueprint-managed Identity clients on the active octo-cli context's tenant. It fans octo-cli -c ApplyClientOverlay across every client listed in the file, dedupes against existing URIs server-side, and tags new entries with Source = "overlay:<name>" so they survive blueprint re-applies.

For the conceptual background — when to use overlays, the Source tag taxonomy, family vs overlay, and how the lifecycle interacts with the blueprint apply — see Clients and API Scopes → URI Sources and Lifecycle.

Prerequisites​

  • PowerShell 7+.
  • powershell-yaml module: Install-Module -Name powershell-yaml -Scope CurrentUser.
  • octo-cli on PATH.
  • An active octo-cli context with valid auth tokens (run Invoke-OctoCliLoginLocal or equivalent first).

Parameters​

ParameterRequiredDefaultPurpose
-OverlayFileno$Global:ROOTPATH/octo-tools/overlays/identity-local-dev.yamlPath to the overlay YAML. Pass an absolute path or a different file to apply a non-default overlay.
-OverlayNamenofrom the file's overlayName fieldOverride the overlay name (becomes the overlay:<name> source tag suffix). Useful when applying a one-off overlay from the shared file under a different marker.
-DryRunnooffParse + validate the overlay file, print the octo-cli invocations that would run, do not call out. Sanity check before applying.
-OctoClinoocto-cliPath / name of the octo-cli executable. Resolved from PATH by default.

Examples​

Apply the default local-dev overlay​

Apply-IdentityOverlay

Reads octo-tools/overlays/identity-local-dev.yaml (relative to $Global:ROOTPATH) and applies the local-dev URI set to every client in the file. Run this once after a fresh tenant restore so OIDC roundtrips succeed against the locally-running services.

Dry-run​

Apply-IdentityOverlay -DryRun

Prints the exact octo-cli invocations the cmdlet would run, one per client, without calling out. Run this after editing the overlay file to verify the shape parses and the URI lists CSV correctly.

Personal overlay marked under its own name​

Apply-IdentityOverlay -OverlayFile ~/dev/gerald-laptop.yaml -OverlayName gerald-laptop

Applies a personal overlay file from outside the repo, marked under its own overlay name. The --clean filter in DumpTenant will strip these entries by overlay name (overlay:gerald-laptop) without touching the shared local-dev entries (overlay:local-dev).

Force a non-default overlay name on the shared file​

Apply-IdentityOverlay -OverlayName local-dev-experimental

Applies the canonical local-dev file but tags every entry as overlay:local-dev-experimental instead. Useful when experimenting with overlay changes you do not want mixed with the production local-dev state.

Behaviour and idempotency​

  • One failed client does not abort the batch. If octo-cli returns a non-zero exit code for one client, the cmdlet logs a warning and continues with the remaining clients. The final $LASTEXITCODE is set to 1 if any client failed.
  • Re-runs are no-op. The server dedupes incoming URIs against the existing list contents (any source) and skips when nothing new is added — no DB write, no cache invalidation. Safe to include in every Start-Octo invocation.
  • Whitespace-only URIs are filtered. Both the cmdlet's per-client URI count check and the server's meaningfulCount check trim entries; a redirectUris: list of [" ", ""] is treated as empty and the cmdlet skips the client (it would otherwise hit a 400 on the server).
  • Server-side validation: the overlay name must match ^[A-Za-z0-9._-]+$; the cmdlet checks this client-side before the first octo-cli invocation.

Output​

Per client, one of:

[octo-data-refinery-studio] applying overlay...
[overlay 'local-dev' on 'octo-data-refinery-studio'] applied: RedirectUris=2 added / 0 skipped, PostLogoutRedirectUris=1 added / 0 skipped, AllowedCorsOrigins=1 added / 0 skipped

On re-run, the same client emits 0 added / N skipped counts, signalling the no-op path.

Start-Octo integration​

Apply-IdentityOverlay runs standalone today. Auto-invoke from Start-Octo after the Identity /healthz/ready check (with a -SkipOverlay opt-out on Start-Octo) is a follow-up change. Until then, run the cmdlet manually after Start-Octo shows Identity is up.

See also​