functions/core/New-MgaAccessToken.ps1
|
function New-MgaAccessToken { <# .SYNOPSIS Creates an access token for contacting the specified application endpoint .DESCRIPTION Creates an access token for contacting the specified application endpoint .PARAMETER MailboxName The email address of the mailbox to access .PARAMETER Credential The credentials to use to authenticate the request. Using this avoids the need to visually interact with the logon screen. Only works for accounts that have once logged in visually, but can be used from any machine. .PARAMETER ClientId The ID of the client to connect with. This is the ID of the registered application. .PARAMETER RedirectUrl Some weird vodoo. Leave it as it is, unless you know better .PARAMETER ShowLoginWindow Force to show login window with account selection again. .PARAMETER Register Registers the token, so all subsequent calls to Exchange Online reuse it by default. .PARAMETER PassThru Outputs the token to the console, even when the register switch is set .PARAMETER IdentityPlatformVersion Specifies the endpoint version of the logon platform (Microsoft identity platform) where to connect for logon. Use 2.0 if you want to login with a Microsoft Account. For more information goto https://docs.microsoft.com/en-us/azure/active-directory/develop/about-microsoft-identity-platform .PARAMETER Tenant The entry point to sign into. The allowed values are common, organizations, consumers. .PARAMETER Permission Only applies if IdentityPlatformVersion version 2.0 is used. Specify the requested permission in the token. .PARAMETER ResourceUri The App ID URI of the target web API (secured resource). It may be https://graph.microsoft.com .EXAMPLE PS C:\> New-MgaAccessToken -Register For best usage and convinience, mostly, this is what you want to use. Requires an interactive session with a user handling the web UI. For addition the aquired token will be registered in the module as default value to use with all the commands. .EXAMPLE PS C:\> $token = New-MgaAccessToken Requires an interactive session with a user handling the web UI. .EXAMPLE PS C:\> $token = New-MgaAccessToken -Credential $cred Generates a token with the credentials specified in $cred. This is not supported for personal accounts (Micrsoft Accounts). .EXAMPLE PS C:\> New-MgaAccessToken -Register -ShowLoginWindow -ClientId '4a6acbac-d325-47a3-b59b-d2e9e05a37c1' -RedirectUrl 'urn:ietf:wg:oauth:2.0:oob' -IdentityPlatformVersion '2.0' Requires an interactive session with a user handling the web UI. Always prompt for account selection windows. Connecting against Azure Application with ID '4a6acbac-d325-47a3-b59b-d2e9e05a37c1'. Specifies RedirectUrl 'urn:ietf:wg:oauth:2.0:oob' (default value for interactive apps). Use Authentication Plattform 1.0, which only allows AzureAD business accounts to logon. #> [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSAvoidUsingConvertToSecureStringWithPlainText", "")] [Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSUseShouldProcessForStateChangingFunctions", "")] [CmdletBinding(DefaultParameterSetName = "LoginWithWebForm")] [Alias('Connect-MgaGraph')] param ( [Parameter(ParameterSetName = 'LoginWithCredentialObject')] [PSCredential] $Credential, [System.Guid] $ClientId = (Get-PSFConfigValue -FullName MSGraph.Tenant.Application.ClientID -NotNull), [string] $RedirectUrl = (Get-PSFConfigValue -FullName MSGraph.Tenant.Application.RedirectUrl -Fallback "urn:ietf:wg:oauth:2.0:oob"), [Parameter(ParameterSetName = 'LoginWithWebForm')] [Alias('Force')] [switch] $ShowLoginWindow, [ValidateSet('1.0', '2.0')] [string] $IdentityPlatformVersion = (Get-PSFConfigValue -FullName MSGraph.Tenant.Authentiation.IdentityPlatformVersion -Fallback '2.0'), [String[]] $Permission, [String] $ResourceUri = (Get-PSFConfigValue -FullName MSGraph.Tenant.ApiConnection -Fallback 'https://graph.microsoft.com'), [ValidateSet('common', 'organizations', 'consumers')] [String] $Tenant = 'common', [switch] $Register, [switch] $PassThru ) begin { $baselineTimestamp = [datetime]"1970-01-01Z00:00:00" $endpointBaseUri = (Get-PSFConfigValue -FullName MSGraph.Tenant.Authentiation.Endpoint -Fallback 'https://login.microsoftonline.com') if ($IdentityPlatformVersion -like '1.0' -and $Permission) { Write-PSFMessage -Level Warning -Message "Individual pemissions are not supported in combination with IdentityPlatformVersion 1.0. Specified Permission ($([String]::Join(", ", $Permission))) in parameter will be ignored" -Tag "ParameterSetHandling" $Permission = "" } } process { #region variable definitions switch ($IdentityPlatformVersion) { '1.0' { $endpointUri = "$($endpointBaseUri)/$($Tenant)/oauth2" } '2.0' { if ($Credential -and ($Tenant -notlike "organizations")) { $endpointUri = "$($endpointBaseUri)/organizations/oauth2/V2.0" } else { $endpointUri = "$($endpointBaseUri)/$($Tenant)/oauth2/V2.0" } } } $endpointUriAuthorize = "$($endpointUri)/authorize" $endpointUriToken = "$($endpointUri)/token" Write-PSFMessage -Level Verbose -Message "Start authentication against endpoint $($endpointUri). (Identity platform version $($IdentityPlatformVersion))" -Tag "Authorization" Write-PSFMessage -Level VeryVerbose -Message "Try to get token for usage of application ClientID: $($ClientId) to interact with ResourceAPI: $($ResourceUri)" -Tag "Authorization" if ($IdentityPlatformVersion -like '2.0') { [array]$scopes = "offline_access", "openid" # offline_access to get refreshtoken foreach ($permissionItem in $Permission) { $scopes = $scopes + "$($resourceUri)/$($permissionItem)" } $scope = [string]::Join(" ", $scopes) Remove-Variable -Name scopes -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false Write-PSFMessage -Level VeryVerbose -Message "Using scope: $($scope)" -Tag "Authorization" } #endregion variable definitions #region Request an authorization code (login procedure) if (-not $Credential) { # build authorization string with web form # Info https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code#request-an-authorization-code Write-PSFMessage -Level Verbose -Message "Authentication is done by code. Query authentication from login form." -Tag "Authorization" $queryHash = [ordered]@{ client_id = "$($ClientId)" response_type = "code" redirect_uri = [System.Web.HttpUtility]::UrlEncode($redirectUrl) } switch ($IdentityPlatformVersion) { '1.0' { $queryHash.Add("resource", [System.Web.HttpUtility]::UrlEncode($resourceUri)) # optional, but recommended if ($ShowLoginWindow) { $queryHash.Add("prompt", "select_account") } } '2.0' { $queryHash.Add("scope", [uri]::EscapeDataString($scope)) if ($ShowLoginWindow) { $queryHash.Add("prompt", "login") } } } # Show login windows (web form) [string]$url = $endpointUriAuthorize + (Convert-UriQueryFromHash $queryHash) $phase1auth = Show-OAuthWindow -Url $url if (-not $phase1auth.code) { $msg = "Authentication failed. Unable to obtain AccessToken.`n$($phase1auth.error_description)" if ($phase1auth.error) { $msg = $phase1auth.error.ToUpperInvariant() + " - " + $msg } Stop-PSFFunction -Message $msg -Tag "Authorization" -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg)) } Remove-Variable -Name url -Force -WhatIf:$false -Confirm:$false -Verbose:$false -Debug:$false # build authorization string with authentication code from web form auth $tokenQueryHash = [ordered]@{ client_id = "$($ClientId)" grant_type = "authorization_code" code = "$($phase1auth.code)" redirect_uri = "$($redirectUrl)" } switch ($IdentityPlatformVersion) { '1.0' { $tokenQueryHash.Add("resource", [System.Web.HttpUtility]::UrlEncode($resourceUri)) } '2.0' { $tokenQueryHash.Add("scope", [uri]::EscapeDataString($scope)) } } $authorizationPostRequest = Convert-UriQueryFromHash $tokenQueryHash -NoQuestionmark } else { # build authorization string with plain text credentials # Info https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-oauth2-client-creds-grant-flow#request-an-access-token Write-PSFMessage -Level Verbose -Message "Authentication is done by specified credentials. (No TwoFactor-Authentication supported!)" -Tag "Authorization" $tokenQueryHash = [ordered]@{ grant_type = "password" username = $Credential.UserName password = $Credential.GetNetworkCredential().password client_id = $ClientId } switch ($IdentityPlatformVersion) { '1.0' { $tokenQueryHash.Add("resource", [System.Web.HttpUtility]::UrlEncode($resourceUri)) } '2.0' { $tokenQueryHash.Add("scope", [uri]::EscapeDataString($scope)) } } $authorizationPostRequest = Convert-UriQueryFromHash $tokenQueryHash -NoQuestionmark } #endregion Request an authorization code (login procedure) #region Request an access token $content = New-Object -TypeName "System.Net.Http.StringContent" -ArgumentList ($authorizationPostRequest, [System.Text.Encoding]::UTF8, "application/x-www-form-urlencoded") $httpClient = New-HttpClient $clientResult = $httpClient.PostAsync([Uri]($endpointUriToken), $content) if ($clientResult.Result.StatusCode -eq [System.Net.HttpStatusCode]"OK") { Write-PSFMessage -Level Verbose -Message "AccessToken granted. $($clientResult.Result.StatusCode.value__) ($($clientResult.Result.StatusCode)) $($clientResult.Result.ReasonPhrase)" -Tag "Authorization" } else { $httpClient.CancelPendingRequests() $msg = "Request for AccessToken failed. $($clientResult.Result.StatusCode.value__) ($($clientResult.Result.StatusCode)) $($clientResult.Result.ReasonPhrase) `n$($jsonResponse.error_description)" Stop-PSFFunction -Message $msg -Tag "Authorization" -EnableException $true -Exception ([System.Management.Automation.RuntimeException]::new($msg)) } #endregion Request an access token #region Build output object $jsonResponse = ConvertFrom-Json -InputObject $clientResult.Result.Content.ReadAsStringAsync().Result -ErrorAction Ignore $resultObject = New-Object -TypeName MSGraph.Core.AzureAccessToken -Property @{ IdentityPlatformVersion = $IdentityPlatformVersion TokenType = $jsonResponse.token_type AccessToken = $null RefreshToken = $null IDToken = $null Credential = $Credential ClientId = $ClientId Resource = $resourceUri AppRedirectUrl = $RedirectUrl } switch ($IdentityPlatformVersion) { '1.0' { $resultObject.Scope = $jsonResponse.scope -split " " $resultObject.ValidUntilUtc = $baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToUniversalTime() $resultObject.ValidFromUtc = $baselineTimestamp.AddSeconds($jsonResponse.not_before).ToUniversalTime() $resultObject.ValidUntil = $baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToLocalTime().AddHours( [int]$baselineTimestamp.AddSeconds($jsonResponse.expires_on).ToLocalTime().IsDaylightSavingTime() ) $resultObject.ValidFrom = $baselineTimestamp.AddSeconds($jsonResponse.not_before).ToLocalTime().AddHours( [int]$baselineTimestamp.AddSeconds($jsonResponse.not_before).ToLocalTime().IsDaylightSavingTime() ) } '2.0' { $resultObject.Scope = $jsonResponse.scope.Replace("$ResourceUri/", '') -split " " $resultObject.ValidUntilUtc = (Get-Date).AddSeconds($jsonResponse.expires_in).ToUniversalTime() $resultObject.ValidFromUtc = (Get-Date).ToUniversalTime() $resultObject.ValidUntil = (Get-Date).AddSeconds($jsonResponse.expires_in).ToLocalTime() $resultObject.ValidFrom = (Get-Date).ToLocalTime() } } # Insert token data into output object. done as secure string to prevent text output of tokens if ($jsonResponse.psobject.Properties.name -contains "refresh_token") { $resultObject.RefreshToken = ($jsonResponse.refresh_token | ConvertTo-SecureString -AsPlainText -Force) } if ($jsonResponse.psobject.Properties.name -contains "id_token") { $resultObject.IDToken = ($jsonResponse.id_token | ConvertTo-SecureString -AsPlainText -Force) $resultObject.AccessTokenInfo = ConvertFrom-JWTtoken -Token $jsonResponse.id_token } if ($jsonResponse.psobject.Properties.name -contains "access_token") { $resultObject.AccessToken = ($jsonResponse.access_token | ConvertTo-SecureString -AsPlainText -Force) if ($jsonResponse.access_token.Contains(".") -and $jsonResponse.access_token.StartsWith("eyJ")) { $resultObject.AccessTokenInfo = ConvertFrom-JWTtoken -Token $jsonResponse.access_token } } # Getting validity period out of AccessToken information if ($resultObject.AccessTokenInfo -and ($resultObject.AccessTokenInfo.TenantID.ToString() -notlike "9188040d-6c67-4c5b-b112-36a304b66dad") ) { $resultObject.ValidUntilUtc = $resultObject.AccessTokenInfo.ExpirationTime.ToUniversalTime() $resultObject.ValidFromUtc = $resultObject.AccessTokenInfo.NotBefore.ToUniversalTime() $resultObject.ValidUntil = $resultObject.AccessTokenInfo.ExpirationTime.ToLocalTime().AddHours( [int]$resultObject.AccessTokenInfo.ExpirationTime.ToLocalTime().IsDaylightSavingTime() ) $resultObject.ValidFrom = $resultObject.AccessTokenInfo.NotBefore.ToLocalTime().AddHours( [int]$resultObject.AccessTokenInfo.NotBefore.ToLocalTime().IsDaylightSavingTime() ) } #endregion Build output object #region Output the object # Checking if token is valid # ToDo implement "validating token information" -> https://docs.microsoft.com/en-us/azure/active-directory/develop/access-tokens#validating-tokens if ($resultObject.IsValid) { if ($Register) { $script:msgraph_Token = $resultObject if ($PassThru) { $resultObject } } else { $resultObject } } else { Stop-PSFFunction -Message "Token failure. Acquired token is not valid" -EnableException $true -Tag "Authorization" } #endregion Output the object } end {} } |