Modules/AzureDevOpsDsc.Common/Resources/Functions/Public/New-AzDoAuthenticationProvider.ps1

<#
.SYNOPSIS
Creates a new Azure DevOps authentication provider.
 
.DESCRIPTION
The New-AzDoAuthenticationProvider function configures authentication for Azure DevOps DSC.
It supports multiple authentication methods: Personal Access Token, Managed Identity,
Service Principal with Client Secret, Service Principal with Certificate, Azure CLI, and
Workload Identity Federation (file-based, GitHub Actions OIDC, or a manually-supplied token).
 
.PARAMETER OrganizationName
Specifies the name of the Azure DevOps organization.
 
.PARAMETER SecureStringPersonalAccessToken
The Personal Access Token as a SecureString. This is the default parameter set. There is no
plain-text parameter: a secret typed on the command line lands in shell history, transcripts and
process listings. Use Read-Host -AsSecureString, or ConvertTo-SecureString on a value read from an
environment variable or a secret store.
 
.PARAMETER SecureStringClientSecret
The service principal client secret as a SecureString. There is no plain-text parameter, for the
same reason.
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -SecureStringPersonalAccessToken (Read-Host -Prompt 'PAT' -AsSecureString)
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -useManagedIdentity
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -TenantId "..." -ClientId "..." -SecureStringClientSecret $secureSecret
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -TenantId "..." -ClientId "..." -CertificateThumbprint "..."
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -useAzureCLI
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -TenantId "..." -ClientId "..." -FederatedTokenFile "/var/run/secrets/azure/tokens/azure-identity-token"
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -TenantId "..." -ClientId "..." -useGitHubActionsOIDC
 
.EXAMPLE
New-AzDoAuthenticationProvider -OrganizationName "Contoso" -TenantId "..." -ClientId "..." -FederatedToken $secureJwt
#>

Function New-AzDoAuthenticationProvider
{
    [CmdletBinding(DefaultParameterSetName = 'SecureStringPersonalAccessToken')]
    param (
        # Organization Name
        [Parameter(Mandatory = $true, ParameterSetName = 'SecureStringPersonalAccessToken')]
        [Parameter(Mandatory = $true, ParameterSetName = 'ManagedIdentity')]
        [Parameter(Mandatory = $true, ParameterSetName = 'SecureStringServicePrincipal')]
        [Parameter(Mandatory = $true, ParameterSetName = 'Certificate')]
        [Parameter(Mandatory = $true, ParameterSetName = 'CertificateFile')]
        [Parameter(Mandatory = $true, ParameterSetName = 'AzureCLI')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationFile')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationGitHubActions')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationToken')]
        [Alias('OrgName')]
        [String]
        $OrganizationName,


        # SecureString Personal Access Token
        [Parameter(Mandatory = $true, ParameterSetName = 'SecureStringPersonalAccessToken')]
        [Alias('SecureStringPAT')]
        [SecureString]
        $SecureStringPersonalAccessToken,

        # Use Managed Identity
        [Parameter(ParameterSetName = 'ManagedIdentity')]
        [Switch]
        $useManagedIdentity,

        # Service Principal parameters
        [Parameter(Mandatory = $true, ParameterSetName = 'SecureStringServicePrincipal')]
        [Parameter(Mandatory = $true, ParameterSetName = 'Certificate')]
        [Parameter(Mandatory = $true, ParameterSetName = 'CertificateFile')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationFile')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationGitHubActions')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationToken')]
        [String]
        $TenantId,

        [Parameter(Mandatory = $true, ParameterSetName = 'SecureStringServicePrincipal')]
        [Parameter(Mandatory = $true, ParameterSetName = 'Certificate')]
        [Parameter(Mandatory = $true, ParameterSetName = 'CertificateFile')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationFile')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationGitHubActions')]
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationToken')]
        [String]
        $ClientId,


        [Parameter(Mandatory = $true, ParameterSetName = 'SecureStringServicePrincipal')]
        [SecureString]
        $SecureStringClientSecret,

        # Certificate parameters (Windows cert store thumbprint)
        [Parameter(Mandatory = $true, ParameterSetName = 'Certificate')]
        [String]
        $CertificateThumbprint,

        # Certificate parameters (PFX file, cross-platform)
        [Parameter(Mandatory = $true, ParameterSetName = 'CertificateFile')]
        [String]
        $CertificatePath,

        [Parameter(Mandatory = $true, ParameterSetName = 'CertificateFile')]
        [SecureString]
        $CertificatePassword,

        # Use Azure CLI credentials
        [Parameter(ParameterSetName = 'AzureCLI')]
        [Switch]
        $useAzureCLI,

        # Workload Identity Federation - file-based federated token (e.g. AKS/Kubernetes workload identity)
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationFile')]
        [String]
        $FederatedTokenFile,

        # Workload Identity Federation - acquire the federated token from GitHub Actions' OIDC endpoint
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationGitHubActions')]
        [Switch]
        $useGitHubActionsOIDC,

        [Parameter(ParameterSetName = 'WorkloadIdentityFederationGitHubActions')]
        [String]
        $GitHubActionsAudience = 'api://AzureADTokenExchange',

        # Workload Identity Federation - a federated token already obtained by the caller
        [Parameter(Mandatory = $true, ParameterSetName = 'WorkloadIdentityFederationToken')]
        [SecureString]
        $FederatedToken,

        # Don't verify the Token
        [Parameter(ParameterSetName = 'ManagedIdentity')]
        [Parameter(ParameterSetName = 'SecureStringServicePrincipal')]
        [Parameter(ParameterSetName = 'Certificate')]
        [Parameter(ParameterSetName = 'CertificateFile')]
        [Parameter(ParameterSetName = 'AzureCLI')]
        [Parameter(ParameterSetName = 'WorkloadIdentityFederationFile')]
        [Parameter(ParameterSetName = 'WorkloadIdentityFederationGitHubActions')]
        [Parameter(ParameterSetName = 'WorkloadIdentityFederationToken')]
        [Switch]
        $NoVerify,

        # Do not export the Token (used by DSC resources that inherit from base class)
        [Parameter(ParameterSetName = 'SecureStringPersonalAccessToken')]
        [Parameter(ParameterSetName = 'ManagedIdentity')]
        [Parameter(ParameterSetName = 'SecureStringServicePrincipal')]
        [Parameter(ParameterSetName = 'Certificate')]
        [Parameter(ParameterSetName = 'CertificateFile')]
        [Parameter(ParameterSetName = 'AzureCLI')]
        [Parameter(ParameterSetName = 'WorkloadIdentityFederationFile')]
        [Parameter(ParameterSetName = 'WorkloadIdentityFederationGitHubActions')]
        [Parameter(ParameterSetName = 'WorkloadIdentityFederationToken')]
        [Switch]
        $isResource

    )

    # Test if $ENV:AZDODSC_CACHE_DIRECTORY is set. If not, throw an error.
    if ($null -eq $ENV:AZDODSC_CACHE_DIRECTORY)
    {
        Throw "[New-AzDoAuthenticationProvider] The Environment Variable 'AZDODSC_CACHE_DIRECTORY' is not set. Please set the Environment Variable 'AZDODSC_CACHE_DIRECTORY' to the Cache Directory."
    }

    # The organization name becomes part of every request URI, and the tenant id part of the token
    # endpoint URI. Neither is free text: refuse anything that could change which host or path a
    # credential is sent to (a slash, '@', '?', '#', whitespace) instead of building a URI from it.
    if ($OrganizationName -notmatch '^[A-Za-z0-9](?:[A-Za-z0-9-]{0,48}[A-Za-z0-9])?$')
    {
        Throw "[New-AzDoAuthenticationProvider] '$OrganizationName' is not a valid Azure DevOps organization name. A name is 1 to 50 letters, digits or hyphens and starts and ends with a letter or digit - pass the name only, not a URL."
    }
    if ($PSBoundParameters.ContainsKey('TenantId') -and ($TenantId -notmatch '^[A-Za-z0-9](?:[A-Za-z0-9.-]{0,252}[A-Za-z0-9])?$'))
    {
        Throw "[New-AzDoAuthenticationProvider] '$TenantId' is not a valid tenant id. Pass the tenant GUID or a verified domain name (for example contoso.onmicrosoft.com)."
    }

    # Set the Global Variables
    $Global:DSCAZDO_OrganizationName = $OrganizationName
    $Global:DSCAZDO_AuthenticationToken = $null

    #
    # If the parameterset is ManagedIdentity
    if ($PSCmdlet.ParameterSetName -eq 'ManagedIdentity')
    {

        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a new Azure Managed Identity with OrganizationName $OrganizationName."

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzManagedIdentityToken -OrganizationName $OrganizationName
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzManagedIdentityToken -OrganizationName $OrganizationName -Verify
        }

    }
    # If the parameterset is SecureStringPersonalAccessToken
    elseif ($PSCmdlet.ParameterSetName -eq 'SecureStringPersonalAccessToken')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a new Personal Access Token with OrganizationName $OrganizationName."
        $Global:DSCAZDO_AuthenticationToken = Set-AzPersonalAccessToken -SecureStringPersonalAccessToken $SecureStringPersonalAccessToken -OrganizationName $OrganizationName
    }
    # If the parameterset is SecureStringServicePrincipal
    elseif ($PSCmdlet.ParameterSetName -eq 'SecureStringServicePrincipal')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a Service Principal token (SecureString) with OrganizationName $OrganizationName."

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzServicePrincipalToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -SecureStringClientSecret $SecureStringClientSecret
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzServicePrincipalToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -SecureStringClientSecret $SecureStringClientSecret -Verify
        }
    }
    # If the parameterset is Certificate (thumbprint)
    elseif ($PSCmdlet.ParameterSetName -eq 'Certificate')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a Certificate token (thumbprint) with OrganizationName $OrganizationName."

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzServicePrincipalCertificateToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -CertificateThumbprint $CertificateThumbprint
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzServicePrincipalCertificateToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -CertificateThumbprint $CertificateThumbprint -Verify
        }
    }
    # If the parameterset is CertificateFile (PFX path)
    elseif ($PSCmdlet.ParameterSetName -eq 'CertificateFile')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a Certificate token (PFX file) with OrganizationName $OrganizationName."

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzServicePrincipalCertificateToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -CertificatePath $CertificatePath -CertificatePassword $CertificatePassword
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzServicePrincipalCertificateToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -CertificatePath $CertificatePath -CertificatePassword $CertificatePassword -Verify
        }
    }
    # If the parameterset is AzureCLI
    elseif ($PSCmdlet.ParameterSetName -eq 'AzureCLI')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating an Azure CLI token with OrganizationName $OrganizationName."

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzCliToken -OrganizationName $OrganizationName
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzCliToken -OrganizationName $OrganizationName -Verify
        }
    }
    # If the parameterset is WorkloadIdentityFederationFile
    elseif ($PSCmdlet.ParameterSetName -eq 'WorkloadIdentityFederationFile')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a Workload Identity Federation token (file) with OrganizationName $OrganizationName."

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzWorkloadIdentityFederationToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -FederatedTokenFile $FederatedTokenFile
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzWorkloadIdentityFederationToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -FederatedTokenFile $FederatedTokenFile -Verify
        }
    }
    # If the parameterset is WorkloadIdentityFederationGitHubActions
    elseif ($PSCmdlet.ParameterSetName -eq 'WorkloadIdentityFederationGitHubActions')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a Workload Identity Federation token (GitHub Actions OIDC) with OrganizationName $OrganizationName."

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzWorkloadIdentityFederationToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -GitHubActions -GitHubActionsAudience $GitHubActionsAudience
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzWorkloadIdentityFederationToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -GitHubActions -GitHubActionsAudience $GitHubActionsAudience -Verify
        }
    }
    # If the parameterset is WorkloadIdentityFederationToken
    elseif ($PSCmdlet.ParameterSetName -eq 'WorkloadIdentityFederationToken')
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] Creating a Workload Identity Federation token (manually-supplied) with OrganizationName $OrganizationName."

        $BSTR                = [System.Runtime.InteropServices.Marshal]::SecureStringToBSTR($FederatedToken)
        $plainFederatedToken = if ($isLinux) {
            [System.Runtime.InteropServices.Marshal]::PtrToStringUni($BSTR)
        } else {
            [System.Runtime.InteropServices.Marshal]::PtrToStringAuto($BSTR)
        }
        [System.Runtime.InteropServices.Marshal]::ZeroFreeBSTR($BSTR)

        if ($NoVerify)
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzWorkloadIdentityFederationToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -FederatedToken $plainFederatedToken
        }
        else
        {
            $Global:DSCAZDO_AuthenticationToken = Get-AzWorkloadIdentityFederationToken -OrganizationName $OrganizationName -TenantId $TenantId -ClientId $ClientId -FederatedToken $plainFederatedToken -Verify
        }
    }

    # Export the Token information to the Cache Directory
    if ($isResource.IsPresent)
    {
        Write-Verbose "[New-AzDoAuthenticationProvider] isResource is set. The Token will not be exported."
        return
    }


    # Initialize the Cache
    Get-AzDoCacheObjects | ForEach-Object {
        Initialize-CacheObject -CacheType $_
    }

    # Iterate through Each of the Caching Commands and initalize the Cache.
    Get-Command "AzDoAPI_*" | Where-Object Source -eq 'AzureDevOpsDsc.Common' | ForEach-Object {
        . $_.Name -OrganizationName $AzureDevopsOrganizationName
    }

    # Export the Token to the Cache Directory

    # Create an Object Containing the Organization Name.
    $moduleSettingsPath = Join-Path -Path $ENV:AZDODSC_CACHE_DIRECTORY -ChildPath "ModuleSettings.clixml"
    Write-Verbose "[New-AzDoAuthenticationProvider] Exporting the Module Settings to $moduleSettingsPath."

    $objectSettings = [PSCustomObject]@{
        OrganizationName = (Get-AzDoOrganizationName)
        # A copy for the file, without the access token wherever sign-in can get a new one.
        Token = ConvertTo-AzDoStoredToken -Token $Global:DSCAZDO_AuthenticationToken
        SecurityDescriptorTypes = Join-Path -Path $ENV:AZDODSC_CACHE_DIRECTORY -ChildPath "SecurityDescriptors.clixml"
    }

    # Export-Clixml only protects a SecureString with DPAPI on Windows. Elsewhere the credential is
    # written in a recoverable form, so the file permissions set below are all that protects it.
    if (-not (Test-AzDoIsWindows))
    {
        Write-Warning "[New-AzDoAuthenticationProvider] On this platform '$moduleSettingsPath' stores the credential in a recoverable form that is protected only by file permissions, which the module sets to owner-only. Keep AZDODSC_CACHE_DIRECTORY on a private path and run DSC as the same account that ran New-AzDoAuthenticationProvider."
    }

    # Restrict the cache directory first (so anything created under it inherits), then create the
    # settings file empty and restrict it before the credential is written into it. Writing first
    # and restricting afterwards left the credential readable with the default permissions for a
    # moment on every run.
    # -Required: if either cannot be restricted this throws, and the credential is not written.
    if (-not (Test-Path -LiteralPath $ENV:AZDODSC_CACHE_DIRECTORY))
    {
        $null = New-Item -Path $ENV:AZDODSC_CACHE_DIRECTORY -ItemType Directory -Force
    }
    Protect-AzDoCachePath -Path $ENV:AZDODSC_CACHE_DIRECTORY -Required
    if (-not (Test-Path -LiteralPath $moduleSettingsPath))
    {
        $null = New-Item -Path $moduleSettingsPath -ItemType File -Force
    }
    Protect-AzDoCachePath -Path $moduleSettingsPath -Required

    # Export the Object to the Cache Directory
    $objectSettings | Export-Clixml -LiteralPath $moduleSettingsPath -Depth 5

}