Skip to main content

Azure PowerShell integration

Topaz exposes a custom Azure cloud environment that the Az PowerShell module can register and authenticate against, letting you run *-Az* cmdlets locally without touching real Azure resources. This guide walks through the full setup end-to-end.

Prerequisites​

  • PowerShell 7+ (pwsh --version to verify)
  • Az module installed (Install-Module -Name Az -Force -Scope CurrentUser -Repository PSGallery)
  • Topaz installed and the host running (see Getting started)

Step 1 — Trust the certificate​

Az PowerShell uses the .NET HttpClient stack, which on most platforms respects the OS certificate store. If the Topaz certificate is already trusted at the OS level (for example, you ran topaz start and accepted the certificate prompt), Az PowerShell will work without additional configuration.

If you see The SSL connection could not be established errors, run the configuration script from the Topaz repository:

# From the Topaz repo root — requires sudo for the System keychain
pwsh ./install/configure-azure-powershell-cert.ps1

The script adds the Topaz certificate to the macOS System keychain via security add-trusted-cert.

The script is idempotent — safe to run multiple times.

Step 2 — Start the emulator​

topaz start \
  --default-subscription 00000000-0000-0000-0000-000000000001 \
  --log-level Information

--default-subscription creates the subscription automatically so you don't need a separate command later.

Keep the emulator running in the background for the remaining steps.

Step 3 — Register the Topaz cloud environment and authenticate​

Run the configuration script. It registers Topaz as a named Az environment and authenticates using the built-in admin account:

pwsh ./install/configure-azure-powershell-env.ps1

Expected output:

Registering Az environment 'Topaz'...
Environment registered.
Authenticating as 'topazadmin@topaz.local.dev'...
Connected to Topaz successfully.

What the script does​

The script calls Add-AzEnvironment once to register all Topaz endpoint URLs, then authenticates using Connect-AzAccount with the Resource Owner Password Credentials (ROPC) grant — the same grant that az login --username uses:

Add-AzEnvironment `
    -Name                                     "Topaz" `
    -ResourceManagerUrl                       "https://topaz.local.dev:8899" `
    -ActiveDirectoryAuthority                 "https://topaz.local.dev:8899/" `
    -ActiveDirectoryServiceEndpointResourceId "https://topaz.local.dev:8899" `
    -GraphEndpointResourceId                  "https://topaz.local.dev:8899" `
    -GraphUrl                                 "https://topaz.local.dev:8899" `
    -StorageEndpointSuffix                    "storage.topaz.local.dev" `
    -AzureKeyVaultDnsSuffix                   "vault.topaz.local.dev" `
    -AzureKeyVaultServiceEndpointResourceId   "https://topaz.local.dev:8899"

$cred = New-Object PSCredential("topazadmin@topaz.local.dev",
    (ConvertTo-SecureString "admin" -AsPlainText -Force))

Connect-AzAccount `
    -Environment "Topaz" `
    -Credential  $cred `
    -TenantId    "50717675-3E5E-4A1E-8CB5-C62D8BE8CA48"

Manual — custom user account​

If you created your own user in Topaz, substitute their UPN and password:

$cred = New-Object PSCredential("<upn>@topaz.local.dev",
    (ConvertTo-SecureString "<password>" -AsPlainText -Force))

Connect-AzAccount `
    -Environment "Topaz" `
    -Credential  $cred `
    -TenantId    "50717675-3E5E-4A1E-8CB5-C62D8BE8CA48"
Context autosave and keyring

On Linux, Az PowerShell can attempt to persist tokens via the OS keyring daemon (libsecret). In environments without a keyring (containers, CI, WSL without a desktop session) this causes Connect-AzAccount to hang indefinitely.

Disable autosave before connecting:

Disable-AzContextAutosave | Out-Null

This only affects the current session — tokens are kept in memory and lost when PowerShell exits. If you need the context across multiple processes in the same session (for example, in a test harness), use Save-AzContext / Import-AzContext to persist to and restore from a file explicitly.

Step 4 — Verify and use​

Confirm the Az module is talking to Topaz:

Get-AzSubscription
Get-AzContext

Now use Az cmdlets as normal. For example:

New-AzResourceGroup -Name "rg-local" -Location "westeurope"
Get-AzResourceGroup
Remove-AzResourceGroup -Name "rg-local" -Force

Switching back to real Azure​

Set-AzContext -Environment AzureCloud
Connect-AzAccount

Resources created in Topaz are unaffected — they remain available the next time you switch back and start the emulator.

Troubleshooting​

SymptomCauseFix
The SSL connection could not be establishedTopaz cert not trustedRun configure-azure-powershell-cert.ps1
Connect-AzAccount hangs indefinitelyKeyring daemon absent (Linux / container)Run Disable-AzContextAutosave | Out-Null before connecting
AuthenticationFailedExceptionWrong UPN or passwordEnsure the UPN includes the full domain: user@topaz.local.dev
Get-AzResourceGroup returns nothingWrong environment activeRun (Get-AzContext).Environment.Name — should be Topaz
Subscription not found after loginNo subscription createdAdd --default-subscription to topaz start
InvalidOperation: the provided credentials...MSAL hitting real AAD for instance discoveryEnsure -TenantId matches Topaz's tenant (50717675-3E5E-4A1E-8CB5-C62D8BE8CA48)
Star on GitHub