azure.identity package

Credentials for Azure SDK clients.

exception azure.identity.AuthenticationRequiredError(scopes: Iterable[str], message: Optional[str] = None, error_details: Optional[str] = None, **kwargs: Any)[source]

Interactive authentication is required to acquire a token.

raise_with_traceback()
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
property error_details

Additional authentication error details from Azure Active Directory

property scopes

Scopes requested during the failed authentication

exception azure.identity.CredentialUnavailableError(message=None, response=None, **kwargs)[source]

The credential did not attempt to authenticate because required data or state is unavailable.

raise_with_traceback()
with_traceback()

Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

args
class azure.identity.AuthenticationRecord(tenant_id: str, client_id: str, authority: str, home_account_id: str, username: str)[source]

A record which can initialize DeviceCodeCredential or InteractiveBrowserCredential

classmethod deserialize(data: str) → azure.identity._auth_record.AuthenticationRecord[source]

Deserialize a record.

Parameters

data (str) – a serialized record

serialize() → str[source]

Serialize the record.

Return type

str

property authority
property client_id
property home_account_id
property tenant_id
property username

The authenticated user’s username

class azure.identity.AuthorizationCodeCredential(tenant_id: str, client_id: str, authorization_code: str, redirect_uri: str, **kwargs: Any)[source]

Authenticates by redeeming an authorization code previously obtained from Azure Active Directory.

See https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow for more information about the authentication flow.

Parameters

  • tenant_id (str) – ID of the application’s Azure Active Directory tenant. Also called its ‘directory’ ID.

  • client_id (str) – the application’s client ID

  • authorization_code (str) – the authorization code from the user’s log-in

  • redirect_uri (str) – The application’s redirect URI. Must match the URI used to request the authorization code.

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • client_secret (str) – One of the application’s client secrets. Required only for web apps and web APIs.

get_token(*scopes: str, **kwargs: Any) → AccessToken[source]

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

The first time this method is called, the credential will redeem its authorization code. On subsequent calls the credential will return a cached access token or redeem a refresh token, if it acquired a refresh token upon redeeming the authorization code.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises

ClientAuthenticationError – authentication failed. The error’s message attribute gives a reason. Any error response from Azure Active Directory is available as the error’s response attribute.

class azure.identity.AzureAuthorityHosts[source]
AZURE_CHINA = 'login.chinacloudapi.cn'
AZURE_GERMANY = 'login.microsoftonline.de'
AZURE_GOVERNMENT = 'login.microsoftonline.us'
AZURE_PUBLIC_CLOUD = 'login.microsoftonline.com'
class azure.identity.AzureCliCredential[source]

Authenticates by requesting a token from the Azure CLI.

This requires previously logging in to Azure via “az login”, and will use the CLI’s currently logged in identity.

get_token(*scopes: str, **kwargs: Any) → AccessToken[source]

Request an access token for scopes.

This method is called automatically by Azure SDK clients. Applications calling this method directly must also handle token caching because this credential doesn’t cache the tokens it acquires.

Parameters

scopes (str) – desired scope for the access token. This credential allows only one scope per request.

Return type

azure.core.credentials.AccessToken

Raises
class azure.identity.CertificateCredential(tenant_id: str, client_id: str, certificate_path: str, **kwargs: Any)[source]

Authenticates as a service principal using a certificate.

Parameters

  • tenant_id (str) – ID of the service principal’s tenant. Also called its ‘directory’ ID.

  • client_id (str) – the service principal’s client ID

  • certificate_path (str) – path to a PEM-encoded certificate file including the private key.

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • password (str or bytes) – The certificate’s password. If a unicode string, it will be encoded as UTF-8. If the certificate requires a different encoding, pass appropriately encoded bytes instead.

  • send_certificate (bool) – if True, the credential will send public certificate material with token requests. This is required to use Subject Name/Issuer (SNI) authentication. Defaults to False.

  • enable_persistent_cache (bool) – if True, the credential will store tokens in a persistent cache. Defaults to False.

  • allow_unencrypted_cache (bool) – if True, the credential will fall back to a plaintext cache when encryption is unavailable. Default to False. Has no effect when enable_persistent_cache is False.

get_token(*scopes: str, **kwargs: Any) → AccessToken

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises
class azure.identity.ChainedTokenCredential(*credentials: TokenCredential)[source]

A sequence of credentials that is itself a credential.

Its get_token() method calls get_token on each credential in the sequence, in order, returning the first valid token received.

Parameters

credentials (azure.core.credentials.TokenCredential) – credential instances to form the chain

get_token(*scopes: str, **kwargs: Any) → AccessToken[source]

Request a token from each chained credential, in order, returning the first token received.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Raises

ClientAuthenticationError – no credential in the chain provided a token

class azure.identity.ClientSecretCredential(tenant_id: str, client_id: str, client_secret: str, **kwargs: Any)[source]

Authenticates as a service principal using a client ID and client secret.

Parameters

  • tenant_id (str) – ID of the service principal’s tenant. Also called its ‘directory’ ID.

  • client_id (str) – the service principal’s client ID

  • client_secret (str) – one of the service principal’s client secrets

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • enable_persistent_cache (bool) – if True, the credential will store tokens in a persistent cache. Defaults to False.

  • allow_unencrypted_cache (bool) – if True, the credential will fall back to a plaintext cache when encryption is unavailable. Default to False. Has no effect when enable_persistent_cache is False.

get_token(*scopes: str, **kwargs: Any) → AccessToken

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises
class azure.identity.DefaultAzureCredential(**kwargs: Any)[source]

A default credential capable of handling most Azure SDK authentication scenarios.

The identity it uses depends on the environment. When an access token is needed, it requests one using these identities in turn, stopping when one provides a token:

  1. A service principal configured by environment variables. See EnvironmentCredential for more details.

  2. An Azure managed identity. See ManagedIdentityCredential for more details.

  3. On Windows only: a user who has signed in with a Microsoft application, such as Visual Studio. If multiple identities are in the cache, then the value of the environment variable AZURE_USERNAME is used to select which identity to use. See SharedTokenCacheCredential for more details.

  4. The user currently signed in to Visual Studio Code.

  5. The identity currently logged in to the Azure CLI.

This default behavior is configurable with keyword arguments.

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds. Managed identities ignore this because they reside in a single cloud.

  • exclude_cli_credential (bool) – Whether to exclude the Azure CLI from the credential. Defaults to False.

  • exclude_environment_credential (bool) – Whether to exclude a service principal configured by environment variables from the credential. Defaults to False.

  • exclude_managed_identity_credential (bool) – Whether to exclude managed identity from the credential. Defaults to False.

  • exclude_visual_studio_code_credential (bool) – Whether to exclude stored credential from VS Code. Defaults to False.

  • exclude_shared_token_cache_credential (bool) – Whether to exclude the shared token cache. Defaults to False.

  • exclude_interactive_browser_credential (bool) – Whether to exclude interactive browser authentication (see InteractiveBrowserCredential). Defaults to True.

  • interactive_browser_tenant_id (str) – Tenant ID to use when authenticating a user through InteractiveBrowserCredential. Defaults to the value of environment variable AZURE_TENANT_ID, if any. If unspecified, users will authenticate in their home tenants.

  • managed_identity_client_id (str) – The client ID of a user-assigned managed identity. Defaults to the value of the environment variable AZURE_CLIENT_ID, if any. If not specified, a system-assigned identity will be used.

  • shared_cache_username (str) – Preferred username for SharedTokenCacheCredential. Defaults to the value of environment variable AZURE_USERNAME, if any.

  • shared_cache_tenant_id (str) – Preferred tenant for SharedTokenCacheCredential. Defaults to the value of environment variable AZURE_TENANT_ID, if any.

  • visual_studio_code_tenant_id (str) – Tenant ID to use when authenticating with VisualStudioCodeCredential.

get_token(*scopes: str, **kwargs: Any) → AccessToken[source]

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Raises

ClientAuthenticationError – authentication failed. The exception has a message attribute listing each authentication attempt and its error message.

class azure.identity.DeviceCodeCredential(client_id: str, **kwargs: Any)[source]

Authenticates users through the device code flow.

When get_token() is called, this credential acquires a verification URL and code from Azure Active Directory. A user must browse to the URL, enter the code, and authenticate with Azure Active Directory. If the user authenticates successfully, the credential receives an access token.

For more information about the device code flow, see Azure Active Directory documentation: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-device-code

Parameters

client_id (str) – the application’s ID

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • tenant_id (str) – an Azure Active Directory tenant ID. Defaults to the ‘organizations’ tenant, which can authenticate work or school accounts. Required for single-tenant applications.

  • timeout (int) – seconds to wait for the user to authenticate. Defaults to the validity period of the device code as set by Azure Active Directory, which also prevails when timeout is longer.

  • prompt_callback (Callable[str, str, datetime]) –

    A callback enabling control of how authentication instructions are presented. Must accept arguments (verification_uri, user_code, expires_on):

    • verification_uri (str) the URL the user must visit

    • user_code (str) the code the user must enter there

    • expires_on (datetime.datetime) the UTC time at which the code will expire

    If this argument isn’t provided, the credential will print instructions to stdout.

  • authentication_record (AuthenticationRecord) – AuthenticationRecord returned by authenticate()

  • disable_automatic_authentication (bool) – if True, get_token() will raise AuthenticationRequiredError when user interaction is required to acquire a token. Defaults to False.

  • enable_persistent_cache (bool) – if True, the credential will store tokens in a persistent cache shared by other user credentials. Defaults to False.

  • allow_unencrypted_cache (bool) – if True, the credential will fall back to a plaintext cache on platforms where encryption is unavailable. Default to False. Has no effect when enable_persistent_cache is False.

authenticate(**kwargs: Any) → AuthenticationRecord

Interactively authenticate a user.

Keyword Arguments

scopes (Iterable[str]) – scopes to request during authentication, such as those provided by AuthenticationRequiredError.scopes(). If provided, successful authentication will cache an access token for these scopes.

Return type

AuthenticationRecord

Raises

ClientAuthenticationError – authentication failed. The error’s message attribute gives a reason.

get_token(*scopes: str, **kwargs: Any) → AccessToken

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises
class azure.identity.EnvironmentCredential(**kwargs: Mapping[str, Any])[source]

A credential configured by environment variables.

This credential is capable of authenticating as a service principal using a client secret or a certificate, or as a user with a username and password. Configuration is attempted in this order, using these environment variables:

Service principal with secret:

  • AZURE_TENANT_ID: ID of the service principal’s tenant. Also called its ‘directory’ ID.

  • AZURE_CLIENT_ID: the service principal’s client ID

  • AZURE_CLIENT_SECRET: one of the service principal’s client secrets

Service principal with certificate:

  • AZURE_TENANT_ID: ID of the service principal’s tenant. Also called its ‘directory’ ID.

  • AZURE_CLIENT_ID: the service principal’s client ID

  • AZURE_CLIENT_CERTIFICATE_PATH: path to a PEM-encoded certificate file including the private key. The certificate must not be password-protected.

User with username and password:

  • AZURE_CLIENT_ID: the application’s client ID

  • AZURE_USERNAME: a username (usually an email address)

  • AZURE_PASSWORD: that user’s password

  • AZURE_TENANT_ID: (optional) ID of the service principal’s tenant. Also called its ‘directory’ ID. If not provided, defaults to the ‘organizations’ tenant, which supports only Azure Active Directory work or school accounts.

get_token(*scopes: str, **kwargs: Any) → AccessToken[source]

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises

CredentialUnavailableError – environment variable configuration is incomplete

class azure.identity.InteractiveBrowserCredential(**kwargs: Any)[source]

Opens a browser to interactively authenticate a user.

get_token() opens a browser to a login URL provided by Azure Active Directory and authenticates a user there with the authorization code flow. Azure Active Directory documentation describes this flow in more detail: https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • tenant_id (str) – an Azure Active Directory tenant ID. Defaults to the ‘organizations’ tenant, which can authenticate work or school accounts.

  • client_id (str) – Client ID of the Azure Active Directory application users will sign in to. If unspecified, the Azure CLI’s ID will be used.

  • redirect_uri (str) – a redirect URI for the application identified by client_id as configured in Azure Active Directory, for example “http://localhost:8400”. This is only required when passing a value for client_id, and must match a redirect URI in the application’s registration. The credential must be able to bind a socket to this URI.

  • authentication_record (AuthenticationRecord) – AuthenticationRecord returned by authenticate()

  • disable_automatic_authentication (bool) – if True, get_token() will raise AuthenticationRequiredError when user interaction is required to acquire a token. Defaults to False.

  • enable_persistent_cache (bool) – if True, the credential will store tokens in a persistent cache shared by other user credentials. Defaults to False.

  • allow_unencrypted_cache (bool) – if True, the credential will fall back to a plaintext cache on platforms where encryption is unavailable. Default to False. Has no effect when enable_persistent_cache is False.

  • timeout (int) – seconds to wait for the user to complete authentication. Defaults to 300 (5 minutes).

authenticate(**kwargs: Any) → AuthenticationRecord

Interactively authenticate a user.

Keyword Arguments

scopes (Iterable[str]) – scopes to request during authentication, such as those provided by AuthenticationRequiredError.scopes(). If provided, successful authentication will cache an access token for these scopes.

Return type

AuthenticationRecord

Raises

ClientAuthenticationError – authentication failed. The error’s message attribute gives a reason.

get_token(*scopes: str, **kwargs: Any) → AccessToken

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises
class azure.identity.KnownAuthorities[source]

Alias of AzureAuthorityHosts

AZURE_CHINA = 'login.chinacloudapi.cn'
AZURE_GERMANY = 'login.microsoftonline.de'
AZURE_GOVERNMENT = 'login.microsoftonline.us'
AZURE_PUBLIC_CLOUD = 'login.microsoftonline.com'
class azure.identity.ManagedIdentityCredential(**kwargs: Any)[source]

Authenticates with an Azure managed identity in any hosting environment which supports managed identities.

This credential defaults to using a system-assigned identity. To configure a user-assigned identity, use one of the keyword arguments.

Keyword Arguments

  • client_id (str) – a user-assigned identity’s client ID. This is supported in all hosting environments.

  • identity_config (Mapping[str, str]) – a mapping {parameter_name: value} specifying a user-assigned identity by its object or resource ID, for example {"object_id": "..."}. Check the documentation for your hosting environment to learn what values it expects.

get_token(*scopes: str, **kwargs: Any) → AccessToken[source]

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scope for the access token. This credential allows only one scope per request.

Return type

azure.core.credentials.AccessToken

Raises

CredentialUnavailableError – managed identity isn’t available in the hosting environment

class azure.identity.SharedTokenCacheCredential(username: Optional[str] = None, **kwargs: Any)[source]

Authenticates using tokens in the local cache shared between Microsoft applications.

Parameters

username (str) – Username (typically an email address) of the user to authenticate as. This is used when the local cache contains tokens for multiple identities.

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • tenant_id (str) – an Azure Active Directory tenant ID. Used to select an account when the cache contains tokens for multiple identities.

  • authentication_record (AuthenticationRecord) – an authentication record returned by a user credential such as DeviceCodeCredential or InteractiveBrowserCredential

  • allow_unencrypted_cache (bool) – if True, the credential will fall back to a plaintext cache when encryption is unavailable. Defaults to False.

get_token(*scopes, **kwargs)[source]

Get an access token for scopes from the shared cache.

If no access token is cached, attempt to acquire one using a cached refresh token.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises
static supported() → bool

Whether the shared token cache is supported on the current platform.

Return type

bool

class azure.identity.UsernamePasswordCredential(client_id: str, username: str, password: str, **kwargs: Any)[source]

Authenticates a user with a username and password.

In general, Microsoft doesn’t recommend this kind of authentication, because it’s less secure than other authentication flows.

Authentication with this credential is not interactive, so it is not compatible with any form of multi-factor authentication or consent prompting. The application must already have consent from the user or a directory admin.

This credential can only authenticate work and school accounts; Microsoft accounts are not supported. See this document for more information about account types: https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/sign-up-organization

Parameters

  • client_id (str) – the application’s client ID

  • username (str) – the user’s username (usually an email address)

  • password (str) – the user’s password

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • tenant_id (str) – tenant ID or a domain associated with a tenant. If not provided, defaults to the ‘organizations’ tenant, which supports only Azure Active Directory work or school accounts.

  • enable_persistent_cache (bool) – if True, the credential will store tokens in a persistent cache shared by other user credentials. Defaults to False.

  • allow_unencrypted_cache (bool) – if True, the credential will fall back to a plaintext cache on platforms where encryption is unavailable. Default to False. Has no effect when enable_persistent_cache is False.

authenticate(**kwargs: Any) → AuthenticationRecord

Interactively authenticate a user.

Keyword Arguments

scopes (Iterable[str]) – scopes to request during authentication, such as those provided by AuthenticationRequiredError.scopes(). If provided, successful authentication will cache an access token for these scopes.

Return type

AuthenticationRecord

Raises

ClientAuthenticationError – authentication failed. The error’s message attribute gives a reason.

get_token(*scopes: str, **kwargs: Any) → AccessToken

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises
class azure.identity.VisualStudioCodeCredential(**kwargs: Any)[source]

Authenticates as the Azure user signed in to Visual Studio Code.

Keyword Arguments

  • authority (str) – Authority of an Azure Active Directory endpoint, for example ‘login.microsoftonline.com’, the authority for Azure Public Cloud (which is the default). AzureAuthorityHosts defines authorities for other clouds.

  • tenant_id (str) – ID of the tenant the credential should authenticate in. Defaults to the “organizations” tenant, which supports only Azure Active Directory work or school accounts.

get_token(*scopes: str, **kwargs: Any) → AccessToken[source]

Request an access token for scopes as the user currently signed in to Visual Studio Code.

This method is called automatically by Azure SDK clients.

Parameters

scopes (str) – desired scopes for the access token. This method requires at least one scope.

Return type

azure.core.credentials.AccessToken

Raises

CredentialUnavailableError – the credential cannot retrieve user details from Visual Studio Code