Connect-XdrByCredential
SYNOPSIS
Authenticates to Microsoft Defender XDR using username, password, and optional TOTP MFA.
SYNTAX
Interactive (Default)
Connect-XdrByCredential [-TotpSecret <String>] [-MfaMethod <String>] [-TenantId <String>] [-UserAgent <String>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
Credential
Connect-XdrByCredential [-Credential <PSCredential>] [-TotpSecret <String>] [-MfaMethod <String>]
[-TenantId <String>] [-UserAgent <String>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
Explicit
Connect-XdrByCredential [-Username <String>] [-Password <SecureString>] [-TotpSecret <String>]
[-MfaMethod <String>] [-TenantId <String>] [-UserAgent <String>] [-ProgressAction <ActionPreference>]
[<CommonParameters>]
DESCRIPTION
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: 1. Submit credentials to Entra ID web login endpoints 2. Handle MFA via SAS (Server Authentication State) endpoints 3. Extract ESTSAUTH cookie from the completed login 4. 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.
EXAMPLES
EXAMPLE 1
Connect-XdrByCredential
Prompts interactively for username and password, then authenticates. If MFA is required, push notification or SMS prompt will be used.
EXAMPLE 2
Connect-XdrByCredential -TotpSecret "JBSWY3DPEHPK3PXP"
Prompts interactively for username and password, then handles MFA automatically via TOTP.
EXAMPLE 3
Connect-XdrByCredential -Credential (Get-Credential) -TotpSecret "JBSWY3DPEHPK3PXP"
Uses the Get-Credential dialog for username/password, then auto-completes TOTP MFA.
EXAMPLE 4
$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.
EXAMPLE 5
Connect-XdrByCredential -Credential (Get-Credential) -TotpSecret "JBSWY3DPEHPK3PXP" -TenantId "8612f621-73ca-4c12-973c-0da732bc44c2"
Authenticates and connects to a specific XDR tenant.
PARAMETERS
-Credential
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.
Type: PSCredential
Parameter Sets: Credential
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Username
The user principal name (e.g., admin@contoso.com). Not needed if -Credential is used.
Type: String
Parameter Sets: Explicit
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Password
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
Type: SecureString
Parameter Sets: Explicit
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-TotpSecret
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.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-MfaMethod
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.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
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.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: None
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: Named
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.