Skip to content

Latest commit

 

History

History
326 lines (221 loc) · 29.7 KB

TROUBLESHOOTING.md

File metadata and controls

326 lines (221 loc) · 29.7 KB
Raw

Troubleshoot Azure Identity authentication issues

This troubleshooting guide covers failure investigation techniques, common errors for the credential types in the Azure Identity Python client library, and mitigation steps to resolve these errors.

Table of contents

Handle Azure Identity errors

ClientAuthenticationError

Errors arising from authentication can be raised on any service client method that makes a request to the service. This is because the token is requested from the credential on the first call to the service and on any subsequent requests to the service that need to refresh the token.

To distinguish these failures from failures in the service client, Azure Identity raises the ClientAuthenticationError with details describing the source of the error in the error message. Depending on the application, these errors may or may not be recoverable.

from azure.core.exceptions import ClientAuthenticationError
from azure.identity import DefaultAzureCredential
from azure.keyvault.secrets import SecretClient

# Create a secret client using the DefaultAzureCredential
client = SecretClient("https://myvault.vault.azure.net/", DefaultAzureCredential())
try:
    secret = client.get_secret("secret1")
except ClientAuthenticationError as ex:
    print(ex.message)

CredentialUnavailableError

The CredentialUnavailableError is a special error type derived from ClientAuthenticationError. This error type is used to indicate that the credential can't authenticate in the current environment, due to lack of required configuration or setup. This error is also used as a signal to chained credential types, such as DefaultAzureCredential and ChainedTokenCredential, that the chained credential should continue to try other credential types later in the chain.

Permission issues

Calls to service clients resulting in HttpResponseError with a StatusCode of 401 or 403 often indicate the caller doesn't have sufficient permissions for the specified API. Check the service documentation to determine which RBAC roles are needed for the specific request, and ensure the authenticated user or service principal have been granted the appropriate roles on the resource.

Find relevant information in error messages

ClientAuthenticationError is raised when unexpected errors occurred while a credential is authenticating. This can include errors received from requests to the Microsoft Entra STS and often contains information helpful to diagnosis. Consider the following ClientAuthenticationError message.

ClientAuthenticationError Message Example

This error contains several pieces of information:

  • Failing Credential Type: The type of credential that failed to authenticate. This can be helpful when diagnosing issues with chained credential types such as DefaultAzureCredential or ChainedTokenCredential.
  • STS Error Code and Message: The error code and message returned from the Microsoft Entra STS. This can give insight into the specific reason the request failed. For instance in this specific case because the provided client secret is incorrect. More information on STS error codes can be found here.

Logging

This library uses the standard logging library for logging.

Basic information about HTTP sessions (URLs, headers, etc.) is logged at INFO level.

Detailed DEBUG level logging, including request/response bodies and unredacted headers, can be enabled on the client or per-operation with the logging_enable keyword argument.

See full SDK logging documentation with examples here.

Troubleshoot DefaultAzureCredential authentication issues

Error Description Mitigation
CredentialUnavailableError raised with message. "DefaultAzureCredential failed to retrieve a token from the included credentials." All credentials in the DefaultAzureCredential chain failed to retrieve a token, each raising a CredentialUnavailableError themselves
ClientAuthenticationError raised from the client with a status code of 401 or 403 Authentication succeeded but the authorizing Azure service responded with a 401 (Authenticate), or 403 (Forbidden) status code. This can often be caused by the DefaultAzureCredential authenticating an account other than the intended one.
  • Enable logging to determine which credential in the chain returned the authenticating token.
  • In the case a credential other than the expected is returning a token, bypass this by either signing out of the corresponding development tool, or excluding the credential with an exclude_xxx_credential keyword argument when creating DefaultAzureCredential.
  • Consult the troubleshooting guide for multi-tenant authentication issues if an error is encountered stating the current credential is not configured to acquire tokens for a tenant.

Troubleshoot EnvironmentCredential authentication issues

CredentialUnavailableError

Error Message Description Mitigation
Environment variables aren't fully configured. A valid combination of environment variables wasn't set. Ensure the appropriate environment variables are set prior to application startup for the intended authentication method.

  • To authenticate a service principal using a client secret, ensure the variables AZURE_CLIENT_ID, AZURE_TENANT_ID and AZURE_CLIENT_SECRET are properly set.
  • To authenticate a service principal using a certificate, ensure the variables AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_CERTIFICATE_PATH, and optionally AZURE_CLIENT_CERTIFICATE_PASSWORD are properly set.
  • To authenticate a user using a password, ensure the variables AZURE_USERNAME and AZURE_PASSWORD are properly set.

    Troubleshoot ClientSecretCredential authentication issues

    ClientAuthenticationError

    Error Code Issue Mitigation
    AADSTS7000215 An invalid client secret was provided. Ensure the client_secret provided when constructing the credential is valid. If unsure, create a new client secret using the Azure portal. Details on creating a new client secret can be found here.
    AADSTS7000222 An expired client secret was provided. Create a new client secret using the Azure portal. Details on creating a new client secret can be found here.
    AADSTS700016 The specified application wasn't found in the specified tenant. Ensure the specified clientId and tenantId are correct for your application registration. For multi-tenant apps, ensure the application has been added to the desired tenant by a tenant admin. To add a new application in the desired tenant, follow the instructions here.

    Troubleshoot CertificateCredential authentication issues

    ClientAuthenticationError

    Error Code Description Mitigation
    AADSTS700027 Client assertion contains an invalid signature. Ensure the specified certificate has been uploaded to the Microsoft Entra application registration. Instructions for uploading certificates to the application registration can be found here.
    AADSTS700016 The specified application wasn't found in the specified tenant. Ensure the specified client_id and tenant_id are correct for your application registration. For multi-tenant apps, ensure the application has been added to the desired tenant by a tenant admin. To add a new application in the desired tenant, follow the instructions here.

    Troubleshoot ClientAssertionCredential authentication issues

    ClientAuthenticationError

    Error Code Description Mitigation
    AADSTS700021 Client assertion application identifier doesn't match 'client_id' parameter. Review the documentation at https://learn.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials. Ensure the JWT assertion created has the correct values specified for the sub and issuer value of the payload, both of these should have the value be equal to clientId. Refer documentation for client assertion format.
    AADSTS700023 Client assertion audience claim does not match Realm issuer. Review the documentation at https://learn.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials. Ensure the audience aud field in the JWT assertion created has the correct value for the audience specified in the payload. This should be set to https://login.microsoftonline.com/{tenantId}/v2.
    AADSTS50027 JWT token is invalid or malformed. Ensure the JWT assertion token is in the valid format. Refer to the documentation for client assertion format.

    Troubleshoot UsernamePasswordCredential authentication issues

    ClientAuthenticationError

    Error Code Issue Mitigation
    AADSTS50126 The provided username or password is invalid Ensure the username and password provided when constructing the credential are valid.

    Troubleshoot ManagedIdentityCredential authentication issues

    The ManagedIdentityCredential is designed to work on a variety of Azure hosts that provide managed identity. Configuring the managed identity and troubleshooting failures varies from hosts. The below table lists the Azure hosts that can be assigned a managed identity, and are supported by the ManagedIdentityCredential.

    Host Environment
    Azure App Service and Azure Functions Configuration Troubleshooting
    Azure Arc Configuration
    Azure Kubernetes Service Configuration Troubleshooting
    Azure Service Fabric Configuration
    Azure Virtual Machines and Scale Sets Configuration Troubleshooting

    Azure Virtual Machine managed identity

    CredentialUnavailableError

    Error Message Description Mitigation
    The requested identity hasn't been assigned to this resource. The IMDS endpoint responded with a status code of 400, indicating the requested identity isn't assigned to the VM. If using a user assigned identity, ensure the specified client_id is correct.

    If using a system assigned identity, make sure it has been enabled properly. Instructions to enable the system assigned identity on an Azure VM can be found here.
    The request failed due to a gateway error. The request to the IMDS endpoint failed due to a gateway error, 502 or 504 status code. Calls via proxy or gateway aren't supported by IMDS. Disable proxies or gateways running on the VM for calls to the IMDS endpoint http://169.254.169.254/
    No response received from the managed identity endpoint. No response was received for the request to IMDS or the request timed out.
    • Ensure managed identity has been properly configured on the VM. Instructions for configuring the manged identity can be found here.
    • Verify the IMDS endpoint is reachable on the VM, see below for instructions.
    Multiple attempts failed to obtain a token from the managed identity endpoint. Retries to retrieve a token from the IMDS endpoint have been exhausted.
    • Refer to inner exception messages for more details on specific failures. If the data has been truncated, more detail can be obtained by collecting logs.
    • Ensure managed identity has been properly configured on the VM. Instructions for configuring the manged identity can be found here.
    • Verify the IMDS endpoint is reachable on the VM, see below for instructions.

    Verify IMDS is available on the VM

    If you have access to the VM, you can verify the managed identity endpoint is available via the command line using curl.

    curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"

    Note that output of this command will contain a valid access token, and SHOULD NOT BE SHARED to avoid compromising account security.

    Azure App Service and Azure Functions managed identity

    CredentialUnavailableError

    Error Message Description Mitigation
    ManagedIdentityCredential authentication unavailable. The environment variables configured by the App Services host weren't present.
    • Ensure the managed identity has been properly configured on the App Service. Instructions for configuring the managed identity can be found here.
    • Verify the App Service environment is properly configured and the managed identity endpoint is available. See below for instructions.

    Verify the App Service managed identity endpoint is available

    If you have access to SSH into the App Service, you can verify managed identity is available in the environment. First ensure the environment variables IDENTITY_ENDPOINT and IDENTITY_HEADER have been set in the environment. Then you can verify the managed identity endpoint is available using curl.

    curl 'http://169.254.169.254/metadata/identity/oauth2/token?resource=https://management.core.windows.net&api-version=2018-02-01' -H "Metadata: true"

    Note that the output of this command will contain a valid access token, and SHOULD NOT BE SHARED to avoid compromising account security.

    Azure Kubernetes Service managed identity

    Pod identity for Kubernetes

    CredentialUnavailableError

    Error Message Description Mitigation
    No managed identity endpoint found The application attempted to authenticate before an identity was assigned to its pod Verify the pod is labeled correctly. This also occurs when a correctly labeled pod authenticates before the identity is ready. To prevent initialization races, configure NMI to set the Retry-After header in its responses (see Pod Identity documentation).

    Troubleshoot VisualStudioCodeCredential authentication issues

    It's a known issue that VisualStudioCodeCredential doesn't work with Azure Account extension versions newer than 0.9.11. A long-term fix to this problem is in progress. In the meantime, consider authenticating via the Azure CLI.

    CredentialUnavailableError

    Error Message Description Mitigation
    Failed To Read VS Code Credentials

    OR

    Authenticate via Azure Tools plugin in VS Code    		 No Azure account information was found in the VS Code configuration.
    • Ensure the Azure Account plugin is properly installed
    • Use View > Command Palette to execute the Azure: Sign In command. This command opens a browser window and displays a page that allows you to sign in to Azure.
    • If you already had the Azure Account extension installed and had logged in to your account, try logging out and logging in again as that will repopulate the cache and potentially mitigate the error you're getting.
    MSAL Interaction Required Error The VisualStudioCodeCredential was able to read the cached credentials from the cache but the cached token is likely expired. Log into the Azure Account extension via View > Command Palette to execute the Azure: Sign In command in the VS Code IDE.
    ADFS tenant not supported ADFS tenants are not currently supported by Visual Stuido Azure Service Authentication. Use credentials from a supported cloud when authenticating with Visual Studio. The supported clouds are:

    Troubleshoot AzureCliCredential authentication issues

    CredentialUnavailableError

    Error Message Description Mitigation
    Azure CLI not installed The Azure CLI isn't installed or couldn't be found.
    • Ensure the Azure CLI is properly installed. Installation instructions can be found here.
    • Validate the installation location has been added to the PATH environment variable.
    Please run 'az login' to set up account No account is currently logged into the Azure CLI, or the login has expired.
    • Log into the Azure CLI using the az login command. More information on authentication in the Azure CLI can be found here.
    • Validate that the Azure CLI can obtain tokens. See below for instructions.

    Verify the Azure CLI can obtain tokens

    You can manually verify that the Azure CLI is properly authenticated, and can obtain tokens. First use the account command to verify the account which is currently logged in to the Azure CLI.

    az account show

    Once you've verified the Azure CLI is using correct account, you can validate that it's able to obtain tokens for this account.

    az account get-access-token --output json --resource https://management.core.windows.net

    Note that output of this command will contain a valid access token, and SHOULD NOT BE SHARED to avoid compromising account security.

    Troubleshoot AzureDeveloperCliCredential authentication issues

    CredentialUnavailableError

    Error Message Description Mitigation
    Azure Developer CLI could not be found The Azure Developer CLI isn't installed or couldn't be found.
    • Ensure the Azure Developer CLI is properly installed. Installation instructions can be found here.
    • Validate the installation location has been added to the PATH environment variable.
    Please run 'azd auth login' to set up account No account is currently logged into the Azure Developer CLI, or the login has expired.
    • Log into the Azure Developer CLI using the azd auth login command.
    • Validate that the Azure Developer CLI can obtain tokens. See below for instructions.

    Verify the Azure Developer CLI can obtain tokens

    You can manually verify that the Azure Developer CLI is properly authenticated, and can obtain tokens. First use the config command to verify the account which is currently logged in to the Azure Developer CLI.

    azd config list

    Once you've verified the Azure Developer CLI is using correct account, you can validate that it's able to obtain tokens for this account.

    azd auth token --output json --scope https://management.core.windows.net/.default

    Note that output of this command will contain a valid access token, and SHOULD NOT BE SHARED to avoid compromising account security.

    Troubleshoot AzurePowerShellCredential authentication issues

    CredentialUnavailableError

    Error Message Description Mitigation
    PowerShell isn't installed. No local installation of PowerShell was found. Ensure that PowerShell is properly installed on the machine. Instructions for installing PowerShell can be found here.
    Az.Account module >= 2.2.0 isn't installed. The Az.Account module needed for authentication in Azure PowerShell isn't installed. Install the latest Az.Account module. Installation instructions can be found here.
    Please run 'Connect-AzAccount' to set up account. No account is currently logged into Azure PowerShell.
    • Login to Azure PowerShell using the Connect-AzAccount command. More instructions for authenticating Azure PowerShell can be found here
    • Validate that Azure PowerShell can obtain tokens. See below for instructions.

    Verify Azure PowerShell can obtain tokens

    You can manually verify that Azure PowerShell is properly authenticated, and can obtain tokens. First use the Get-AzContext command to verify the account which is currently logged in to the Azure CLI.

    PS C:\> Get-AzContext

Name                                     Account             SubscriptionName    Environment         TenantId
----                                     -------             ----------------    -----------         --------
Subscription1 (xxxxxxxx-xxxx-xxxx-xxx... test@outlook.com    Subscription1       AzureCloud          xxxxxxxx-x...

    Once you've verified Azure PowerShell is using the correct account, you can validate that it's able to obtain tokens for this account.

    Get-AzAccessToken -ResourceUrl "https://management.core.windows.net"

    Note that output of this command will contain a valid access token, and SHOULD NOT BE SHARED to avoid compromising account security.

    Troubleshoot WorkloadIdentityCredential authentication issues

    CredentialUnavailableError

    Error Message Description Mitigation
    WorkloadIdentityCredential authentication unavailable. The workload options are not fully configured The WorkloadIdentityCredential requires client_id, tenant_id and token_file_path to authenticate with Microsoft Entra ID.
    • If using DefaultAzureCredential then:
      • Ensure client ID is specified via the workload_identity_client_id keyword argument or the AZURE_CLIENT_ID env variable.
      • Ensure tenant ID is specified via the AZURE_TENANT_ID env variable.
      • Ensure token file path is specified via AZURE_FEDERATED_TOKEN_FILE env variable.
      • Ensure authority host is specified via AZURE_AUTHORITY_HOST env variable.
    • If using WorkloadIdentityCredential then:
      • Ensure tenant ID is specified via the tenant_id keyword argument or the AZURE_TENANT_ID env variable.
      • Ensure client ID is specified via the client_id keyword argument or the AZURE_CLIENT_ID env variable.
      • Ensure token file path is specified via the token_file_path keyword argument or the AZURE_FEDERATED_TOKEN_FILE environment variable.
    • Consult the product troubleshooting guide for other issues.

    Troubleshoot multi-tenant authentication issues

    ClientAuthenticationError

    Error Message Description Mitigation
    The current credential is not configured to acquire tokens for tenant

    The application must configure the credential to allow token acquisition from the requested tenant.

    		 Make one of the following changes in your app:
    • Add the requested tenant ID to additionally_allowed_tenants on the credential options.
    • Add * to additionally_allowed_tenants to allow token acquisition for any tenant.

    This exception was added as part of a breaking change to multi-tenant authentication in version 1.11.0. Users experiencing this error after upgrading can find details on the change and migration in BREAKING_CHANGES.md.

    Troubleshoot Web Account Manager (WAM) brokered authentication issues

    Error Message Description Mitigation
    AADSTS50011 The application is missing the expected redirect URI. Ensure that one of redirect URIs registered for the Microsoft Entra application matches the following URI pattern: ms-appx-web://Microsoft.AAD.BrokerPlugin/{client_id}

    Unable to log in with Microsoft account (MSA) on Windows

    When using InteractiveBrowserBrokerCredential via the azure-identity-broker package on Windows, only Microsoft Entra accounts are listed by default:

    MSA Microsoft Entra only

    If you choose "Use another account", and type in an MSA outlook.com account, it fails:

    Fail on use another account

    When constructing the credential, you can set the enable_msa_passthrough keyword argument to True, and MSA outlook.com accounts that are logged in to Windows are automatically listed:

    Enable MSA

    You may also log in another MSA account by selecting "Microsoft account":

    Microsoft account

    Get additional help

    Additional information on ways to reach out for support can be found in the SUPPORT.md at the root of the repo.