internal/functions/authentication/Connect-ServiceDeviceCode.ps1
|
function Connect-ServiceDeviceCode { <# .SYNOPSIS Connects to Azure AD using the Device Code authentication workflow. .DESCRIPTION Connects to Azure AD using the Device Code authentication workflow. Polls the token endpoint as RFC 8628 (section 3.5) asks: every 'interval' seconds (5 when the answer names none), five seconds more after each slow_down, on through authorization_pending, and until the code expires (expires_in). A declined sign-in (access_denied) or an expired code ends it with an error that says so. The message with the user code is shown on the host (Write-PSFMessage -Level Important); the device code itself is never shown or logged. Ported from PSExchangeOnline (review 2026-10-20). .PARAMETER Resource The resource owning the api permissions / scopes requested. .PARAMETER ClientID The ID of the registered app used with this authentication request. .PARAMETER TenantID The ID of the tenant connected to with this authentication request. .PARAMETER Scopes The scopes to request. Automatically scoped to the service specified via Service Url. Defaults to ".Default" .PARAMETER NoReconnect Disables automatic reconnection. By default, this module will automatically try to reaquire a new token before the old one expires. .PARAMETER AuthenticationUrl The url used for the authentication requests to retrieve tokens. .EXAMPLE PS C:\> Connect-ServiceDeviceCode -Resource 'https://graph.microsoft.com' -ClientID '<ClientID>' -TenantID '<TenantID>' -AuthenticationUrl 'https://login.microsoftonline.com' Connects to the specified tenant using the specified client, prompting the user to authorize via Device Code workflow. #> [CmdletBinding()] param ( [Parameter(Mandatory = $true)] [string] $Resource, [Parameter(Mandatory = $true)] [string] $ClientID, [Parameter(Mandatory = $true)] [string] $TenantID, [AllowEmptyCollection()] [string[]] $Scopes, [switch] $NoReconnect, [Parameter(Mandatory = $true)] [string] $AuthenticationUrl ) if (-not $Scopes) { $Scopes = @('.default') } $actualScopes = $Scopes | Resolve-ScopeName -Resource $Resource if (-not $NoReconnect) { $actualScopes = @($actualScopes) + 'offline_access' } try { $initialResponse = Invoke-RestMethod -Method POST -Uri "$AuthenticationUrl/$TenantID/oauth2/v2.0/devicecode" -Body @{ client_id = $ClientID scope = $actualScopes -join " " } -ErrorAction Stop } catch { $PSCmdlet.ThrowTerminatingError($_) } # Level Important is shown on the host: the user has to read the code to sign in. Write-PSFMessage -Level Important -String 'Identity.DeviceCode.Prompt' -StringValues $initialResponse.message $paramRetrieve = @{ Uri = "$AuthenticationUrl/$TenantID/oauth2/v2.0/token" Method = 'POST' Body = @{ grant_type = "urn:ietf:params:oauth:grant-type:device_code" client_id = $ClientID device_code = $initialResponse.device_code } # A redirect would resend the device code to the host it names. MaximumRedirection = 0 ErrorAction = 'Stop' } # RFC 8628 3.2: 'interval' is optional and defaults to 5 seconds; 'expires_in' is required (15 minutes if missing). [int] $interval = 5 if (([int] $initialResponse.interval) -gt 0) { $interval = [int] $initialResponse.interval } [int] $expiresIn = 900 if (([int] $initialResponse.expires_in) -gt 0) { $expiresIn = [int] $initialResponse.expires_in } $limit = (Get-Date).AddSeconds($expiresIn) $authResponse = $null # Labelled: 'continue' inside a switch would only end the switch. :poll while ($true) { # A poll that would start after the code expired cannot succeed. if ((Get-Date).AddSeconds($interval) -gt $limit) { Invoke-TerminatingException -Cmdlet $PSCmdlet -Message ((Get-PSFLocalizedString -Module 'PSMicrosoftEntraID' -Name 'Identity.DeviceCode.Expired') -f $expiresIn) -Category AuthenticationError } Start-Sleep -Seconds $interval try { $authResponse = Invoke-RestMethod @paramRetrieve } catch { $failure = $_ [string] $errorCode = '' try { $errorCode = ($failure.ErrorDetails.Message | ConvertFrom-Json -ErrorAction Stop).error } catch { $errorCode = '' } switch ($errorCode) { 'authorization_pending' { continue poll } 'slow_down' { # RFC 8628 3.5: this and every later poll waits five seconds more. $interval += 5 Write-PSFMessage -Level Verbose -String 'Identity.DeviceCode.SlowDown' -StringValues $interval continue poll } 'expired_token' { Invoke-TerminatingException -Cmdlet $PSCmdlet -Message ((Get-PSFLocalizedString -Module 'PSMicrosoftEntraID' -Name 'Identity.DeviceCode.Expired') -f $expiresIn) -Category AuthenticationError } 'access_denied' { Invoke-TerminatingException -Cmdlet $PSCmdlet -Message (Get-PSFLocalizedString -Module 'PSMicrosoftEntraID' -Name 'Identity.DeviceCode.Denied') -Category PermissionDenied } } $PSCmdlet.ThrowTerminatingError($failure) } if ($authResponse) { break poll } } Read-AuthResponse -AuthResponse $authResponse } |