internal/functions/authentication/Connect-ServiceIdentity.ps1

function Connect-ServiceIdentity {
    <#
    .SYNOPSIS
        Connect as the current Managed Identity.

    .DESCRIPTION
        Connect as the current Managed Identity.
        Only works from within an Azure environment with a managed identity:

        + App Service, Azure Functions, Azure Automation runbooks and Container Apps: the platform sets
          IDENTITY_ENDPOINT and IDENTITY_HEADER; the token comes from that endpoint, with the header (a secret of the
          platform) as X-IDENTITY-HEADER.
        + Azure VM and VM scale set: no such variables are set; the token comes from the instance metadata service
          (IMDS) at 169.254.169.254, with the header Metadata: true. A probe of at most 2 seconds checks first that the
          service answers, so outside Azure the sign-in fails fast instead of waiting. IMDS answers 404 while the
          identity is still being assigned, 410 while it is updating and 429 or 5xx when it is busy: those are retried
          after 1, 2, 4, 8 and 16 seconds, within 90 seconds in all, as Microsoft advises.

        Azure Arc (IDENTITY_ENDPOINT with IMDS_ENDPOINT, a challenge file instead of a header) is not supported.
        Each token request waits at most 30 seconds for its answer. The environment of the process is read, never
        written: the earlier version set IDENTITY_ENDPOINT on a VM and then still required IDENTITY_HEADER, which a
        VM never has - so it never worked there, and left the variables behind for every later command.

        Ported from PSExchangeOnline (review finding M6, 2026-10-20).

    .PARAMETER Resource
        The resource to get a token for.

    .PARAMETER IdentityID
        ID of the User-Managed Identity to connect as.

    .PARAMETER IdentityType
        Type of the User-Managed Identity.

    .PARAMETER Cmdlet
        The $PSCmdlet of the calling command.
        If specified, errors are triggered in the caller's context.

    .EXAMPLE
        PS C:\> Connect-ServiceIdentity -Resource 'https://vault.azure.net'

        Connect as the current managed identity, retrieving a token for the Azure Key Vault.

    .LINK
        https://learn.microsoft.com/en-us/azure/app-service/overview-managed-identity

    .LINK
        https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/how-to-use-vm-token
    #>

    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]
        $Resource,

        [AllowEmptyString()]
        [AllowNull()]
        [string]
        $IdentityID,

        [AllowEmptyString()]
        [AllowNull()]
        [string]
        $IdentityType,

        $Cmdlet = $PSCmdlet
    )
    process {
        if ($env:IDENTITY_ENDPOINT -and $env:IDENTITY_HEADER) {
            # App Service / Azure Functions
            [string] $apiVersion = $env:IDENTITY_API_VERSION
            if (-not $apiVersion) { $apiVersion = '2019-08-01' }
            [string] $url = '{0}?resource={1}&api-version={2}' -f $env:IDENTITY_ENDPOINT, [uri]::EscapeDataString($Resource), $apiVersion
            $labels = @{ ClientID = 'client_id'; ResourceID = 'mi_res_id'; PrincipalID = 'principal_id' }
            $headers = @{ 'X-IDENTITY-HEADER' = $env:IDENTITY_HEADER }
            $noProxy = $false
        }
        else {
            # Azure VM: the instance metadata service. A short wait: outside Azure nothing answers on that address, and
            # the probe must not hang the sign-in.
            try {
                $vmMetadata = Invoke-RestMethod -Method GET -Headers @{ Metadata = 'true' } -NoProxy -TimeoutSec $script:_InstanceMetadataProbeSeconds -Uri "$script:_InstanceMetadataUrl/metadata/instance?api-version=2021-02-01" -ErrorAction Stop
            }
            catch { $vmMetadata = $null }
            if ($vmMetadata.compute.azEnvironment -notlike '*Azure*') {
                Invoke-TerminatingException -Cmdlet $Cmdlet -Message (Get-PSFLocalizedString -Module 'PSMicrosoftEntraID' -Name 'Identity.ManagedIdentity.NotFound') -Category ConnectionError
            }
            [string] $url = '{0}/metadata/identity/oauth2/token?api-version=2018-02-01&resource={1}' -f $script:_InstanceMetadataUrl, [uri]::EscapeDataString($Resource)
            $labels = @{ ClientID = 'client_id'; ResourceID = 'msi_res_id'; PrincipalID = 'object_id' }
            $headers = @{ Metadata = 'true' }
            $noProxy = $true
        }
        if ($IdentityID) {
            [string] $label = $labels[$IdentityType]
            if (-not $label) { $label = $labels.ClientID }
            $url = '{0}&{1}={2}' -f $url, $label, [uri]::EscapeDataString($IdentityID)
        }

        # Only IMDS is retried (Microsoft's guidance for it); the App Service endpoint answers or fails at once.
        [int[]] $waits = if ($noProxy) { 1, 2, 4, 8, 16 } else { @() }
        $elapsed = [System.Diagnostics.Stopwatch]::StartNew()
        [int] $attempt = 0
        while ($true) {
            try {
                Write-PSFMessage -Level Verbose -String 'Identity.ManagedIdentity.Request' -StringValues (Get-EntraLogUri -Uri $url)
                $authResponse = Invoke-RestMethod -Method GET -Uri $url -Headers $headers -NoProxy:$noProxy -TimeoutSec 30 -ErrorAction Stop
                break
            }
            catch {
                [int] $status = 0
                if ($_.Exception.Response -and $_.Exception.Response.StatusCode) { $status = [int]$_.Exception.Response.StatusCode }
                [bool] $retry = ($status -in @(404, 410, 429) -or $status -ge 500) -and $attempt -lt $waits.Count
                if ($retry -and ($elapsed.Elapsed.TotalSeconds + $waits[$attempt]) -gt 90) { $retry = $false }
                if (-not $retry) {
                    Invoke-TerminatingException -Cmdlet $Cmdlet -Message ((Get-PSFLocalizedString -Module 'PSMicrosoftEntraID' -Name 'Identity.ManagedIdentity.Failed') -f $_.Exception.Message) -ErrorRecord $_
                }
                Write-PSFMessage -Level Verbose -String 'Identity.ManagedIdentity.Retry' -StringValues $status, $waits[$attempt]
                Start-Sleep -Seconds $waits[$attempt]
                $attempt++
            }
        }

        Read-AuthResponse -AuthResponse $authResponse
    }
}