POWERSHELL COMMAND
Connect-XdrByCredential
Authenticates to Microsoft Defender XDR using username, password, and optional TOTP MFA.
Performs a full Entra ID web login flow programmatically (no browser required), handling password submission and MFA challenges, then establishes an authenticated session to the Defender XDR portal.
Supported MFA methods:
- PhoneAppOTP: Authenticator app TOTP code (computed automatically from -TotpSecret)
- PhoneAppNotification: Push notification (polls for user approval, displays number match)
- OneWaySMS: SMS code (prompts user to enter code from phone)
The authentication chain is:
- Submit credentials to Entra ID web login endpoints
- Handle MFA via SAS (Server Authentication State) endpoints
- Extract ESTSAUTH cookie from the completed login
- Pass ESTSAUTH cookie to Connect-XdrByEstsCookie to get sccauth + XSRF-TOKEN
Note: This method may be blocked by Conditional Access policies that require device compliance or a specific client application. It will work with MFA-only policies.
Syntax
Connect-XdrByCredential [-TotpSecret <string>] [-MfaMethod <string>] [-TenantId <string>] [-UserAgent <string>] [<CommonParameters>]
Connect-XdrByCredential [-Credential <pscredential>] [-TotpSecret <string>] [-MfaMethod <string>] [-TenantId <string>] [-UserAgent <string>] [<CommonParameters>]
Connect-XdrByCredential [-Username <string>] [-Password <securestring>] [-TotpSecret <string>] [-MfaMethod <string>] [-TenantId <string>] [-UserAgent <string>] [<CommonParameters>]
Parameters
-Credential
| Property | Value |
|---|---|
| Type | PSCredential |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
A PSCredential object containing username and password. When provided, -Username and -Password are ignored. If no parameters are provided at all, you will be prompted interactively for credentials.
-Username
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
The user principal name (e.g., admin@contoso.com). Not needed if -Credential is used.
-Password
| Property | Value |
|---|---|
| Type | SecureString |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
The password as a SecureString. Not needed if -Credential is used. If you have a plain string, convert it: $pw = ConvertTo-SecureString “MyPassword” -AsPlainText -Force
-TotpSecret
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Base32-encoded TOTP secret for automatic MFA code generation. This is the secret from the QR code when setting up Microsoft Authenticator (otpauth://totp/…?secret=JBSWY3DPEHPK3PXP). If not provided and MFA is required, the function will attempt push notification or prompt for a code.
-MfaMethod
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
Preferred MFA method. Valid values: PhoneAppOTP, PhoneAppNotification, OneWaySMS. If not specified, the function auto-selects PhoneAppOTP only when -TotpSecret is provided and that method is actually offered. When multiple supported inline methods are available, you are prompted to choose.
-TenantId
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | Not documented |
The Defender XDR tenant ID to connect to. If not provided, the default tenant is used.
-UserAgent
| Property | Value |
|---|---|
| Type | String |
| Required | No |
| Position | named |
| Pipeline input | No |
| Default | (Get-XdrDefaultUserAgent) |
User-Agent string for HTTP requests. Defaults to a browser-compatible Edge user agent.
Examples
Connect-XdrByCredential
Prompts interactively for username and password, then authenticates. If MFA is required, push notification or SMS prompt will be used.
Connect-XdrByCredential -TotpSecret "JBSWY3DPEHPK3PXP"
Prompts interactively for username and password, then handles MFA automatically via TOTP.
Connect-XdrByCredential -Credential (Get-Credential) -TotpSecret "JBSWY3DPEHPK3PXP"
Uses the Get-Credential dialog for username/password, then auto-completes TOTP MFA.
$pw = ConvertTo-SecureString "MyPassword" -AsPlainText -Force
Connect-XdrByCredential -Username "admin@contoso.com" -Password $pw -TotpSecret "JBSWY3DPEHPK3PXP"
Fully non-interactive: all credentials and MFA passed as parameters.
Connect-XdrByCredential -Credential (Get-Credential) -TotpSecret "JBSWY3DPEHPK3PXP" -TenantId "8612f621-73ca-4c12-973c-0da732bc44c2"
Authenticates and connects to a specific XDR tenant.