Connect-XdrBySoftwarePasskey
SYNOPSIS
Authenticates to Microsoft Defender XDR using a software passkey.
SYNTAX
Connect-XdrBySoftwarePasskey [-KeyFilePath] <String> [[-TenantId] <String>] [[-KeyVaultTenantId] <String>]
[[-KeyVaultClientId] <String>] [[-KeyVaultApiVersion] <String>] [[-UserAgent] <String>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
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): 1. Az module: Get-AzAccessToken (if Az.Accounts is loaded and you are signed in) 2. Azure CLI: az account get-access-token (if az is on PATH and you are signed in) 3. IMDS managed identity: system-assigned (default) or user-assigned (-KeyVaultClientId)
Requires PowerShell 7.0 or later for ECDsa PEM key support.
EXAMPLES
EXAMPLE 1
Connect-XdrBySoftwarePasskey -KeyFilePath ".github\secadmin.passkey"
Authenticates using a local passkey stored in a JSON file.
EXAMPLE 2
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.
EXAMPLE 3
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.
EXAMPLE 4
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.).
PARAMETERS
-KeyFilePath
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
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-TenantId
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.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-KeyVaultTenantId
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.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-KeyVaultClientId
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.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-KeyVaultApiVersion
Azure Key Vault REST API version to use for the Sign operation. Defaults to '7.4'.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 5
Default value: 7.4
Accept pipeline input: False
Accept wildcard characters: False
-UserAgent
User-Agent string for HTTP requests. Defaults to a browser-compatible Edge user agent.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 6
Default value: (Get-XdrDefaultUserAgent)
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction
The ProgressAction parameter is a common parameter, not a cmdlet parameter. For more information, see about_CommonParameters.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.