POWERSHELL COMMAND
Connect-XdrBySoftwarePasskey
Authenticates to Microsoft Defender XDR using a software passkey.
Performs passkey (FIDO2/WebAuthn) authentication against Microsoft Entra ID using a credential stored in a JSON file, then establishes an authenticated session to the Defender XDR portal.
Two passkey types are supported, auto-detected from the credential file:
Local passkey — the JSON file contains a privateKey field (PEM-encoded EC private key). No additional parameters are needed.
Azure Key Vault passkey — the JSON file contains a keyVault object (vaultName, keyName). The private key never leaves the HSM. A Key Vault access token is obtained automatically by trying (in order):
- Az module: Get-AzAccessToken (if Az.Accounts is loaded and you are signed in)
- Azure CLI: az account get-access-token (if az is on PATH and you are signed in)
- IMDS managed identity: system-assigned (default) or user-assigned (-KeyVaultClientId)
Requires PowerShell 7.0 or later for ECDsa PEM key support.
Syntax
Connect-XdrBySoftwarePasskey [-KeyFilePath] <string> [[-TenantId] <string>] [[-KeyVaultTenantId] <string>] [[-KeyVaultClientId] <string>] [[-KeyVaultApiVersion] <string>] [[-UserAgent] <string>] [<CommonParameters>]
Parameters
-KeyFilePath
| Property | Value |
|---|---|
| Type | String |
| Required | Yes |
| Position | 1 |
| Pipeline input | No |
| Default | Not documented |
Path to a JSON credential file. For local passkeys, the file must contain: credentialId, privateKey, relyingParty, url, userHandle, username
For Key Vault passkeys, the file must contain: credentialId, keyVault.vaultName, keyVault.keyName, relyingParty, url, userHandle, username
-TenantId
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | 2 |
| Pipeline input | No |
| Default | Not documented |
The Defender XDR tenant ID to connect to. If not provided, the default tenant is used. This is passed to Connect-XdrByEstsCookie and does not affect Key Vault authentication.
-KeyVaultTenantId
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | 3 |
| Pipeline input | No |
| Default | Not documented |
Azure AD tenant ID used when scoping the Key Vault access token. Applicable when using Az module or Azure CLI for Key Vault authentication. Not required when using IMDS managed identity.
-KeyVaultClientId
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | 4 |
| Pipeline input | No |
| Default | Not documented |
Client ID of a user-assigned managed identity for Key Vault access via IMDS. When not provided and IMDS is used, the system-assigned managed identity is used.
-KeyVaultApiVersion
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | 5 |
| Pipeline input | No |
| Default | 7.4 |
Azure Key Vault REST API version to use for the Sign operation. Defaults to ‘7.4’.
-UserAgent
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | 6 |
| Pipeline input | No |
| Default | (Get-XdrDefaultUserAgent) |
User-Agent string for HTTP requests. Defaults to a browser-compatible Edge user agent.
Examples
Connect-XdrBySoftwarePasskey -KeyFilePath ".github\secadmin.passkey"
Authenticates using a local passkey stored in a JSON file.
Connect-XdrBySoftwarePasskey -KeyFilePath ".\kv-passkey.json" -TenantId "8612f621-73ca-4c12-973c-0da732bc44c2"
Authenticates using an Azure Key Vault passkey and connects to a specific XDR tenant. Key Vault access is obtained automatically via Az module or Azure CLI.
Connect-AzAccount
Connect-XdrBySoftwarePasskey -KeyFilePath ".\kv-passkey.json" -KeyVaultTenantId "8612f621-73ca-4c12-973c-0da732bc44c2"
Signs in to Azure first, then authenticates with a Key Vault passkey scoped to that tenant.
Connect-XdrBySoftwarePasskey -KeyFilePath ".\kv-passkey.json" -KeyVaultClientId "12345678-abcd-efgh-ijkl-123456789012"
Authenticates using a Key Vault passkey with a user-assigned managed identity (IMDS). For use from Azure resources (VMs, Azure Functions, etc.).