Share via

DeviceCodeCredential Class

  • Reference

Authenticates users through the device code flow.

When get_token is called, this credential acquires a verification URL and code from Microsoft Entra ID. A user must browse to the URL, enter the code, and authenticate with Microsoft Entra ID. If the user authenticates successfully, the credential receives an access token.

This credential is primarily useful for authenticating a user in an environment without a web browser, such as an SSH session. If a web browser is available, InteractiveBrowserCredential is more convenient because it automatically opens a browser to the login page.

Inheritance
azure.identity._internal.interactive.InteractiveCredential
DeviceCodeCredential

Constructor

DeviceCodeCredential(client_id: str = '04b07795-8ddb-461a-bbee-02f9e1bf7b46', *, timeout: int | None = None, prompt_callback: Callable[[str, str, datetime], None] | None = None, **kwargs: Any)

Parameters

Name Description
client_id
str

Client ID of the Microsoft Entra application that users will sign into. It is recommended that developers register their applications and assign appropriate roles. For more information, visit https://aka.ms/azsdk/identity/AppRegistrationAndRoleAssignment. If not specified, users will authenticate to an Azure development application, which is not recommended for production scenarios.

Default value: 04b07795-8ddb-461a-bbee-02f9e1bf7b46

Keyword-Only Parameters

Name Description
authority
str

Authority of a Microsoft Entra 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

a Microsoft Entra 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 Microsoft Entra ID, 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.
cache_persistence_options
TokenCachePersistenceOptions

configuration for persistent token caching. If unspecified, the credential will cache tokens in memory.
disable_instance_discovery
bool

Determines whether or not instance discovery is performed when attempting to authenticate. Setting this to true will completely disable both instance discovery and authority validation. This functionality is intended for use in scenarios where the metadata endpoint cannot be reached, such as in private clouds or Azure Stack. The process of instance discovery entails retrieving authority metadata from https://login.microsoft.com/ to validate the authority. By setting this to True, the validation of the authority is disabled. As a result, it is crucial to ensure that the configured authority host is valid and trustworthy.
enable_support_logging
bool

Enables additional support logging in the underlying MSAL library. This logging potentially contains personally identifiable information and is intended to be used only for troubleshooting purposes.

Examples

Create a DeviceCodeCredential.


   from azure.identity import DeviceCodeCredential

   credential = DeviceCodeCredential()

Methods

authenticate

Interactively authenticate a user. This method will always generate a challenge to the user.
close
get_token

Request an access token for scopes.

This method is called automatically by Azure SDK clients.
get_token_info

Request an access token for scopes.

This is an alternative to get_token to enable certain scenarios that require additional properties on the token. This method is called automatically by Azure SDK clients.

authenticate

Interactively authenticate a user. This method will always generate a challenge to the user.

authenticate(*, scopes: Iterable[str] | None = None, claims: str | None = None, **kwargs: Any) -> AuthenticationRecord

Keyword-Only Parameters

Name Description
scopes
Iterable[str]

scopes to request during authentication, such as those provided by scopes. If provided, successful authentication will cache an access token for these scopes.
claims
str

additional claims required in the token, such as those provided by claims

Returns

Type Description
AuthenticationRecord

Exceptions

Type Description
ClientAuthenticationError

authentication failed. The error's message attribute gives a reason.

close 

close() -> None

Keyword-Only Parameters

Name Description
scopes
Iterable[str]

scopes to request during authentication, such as those provided by scopes. If provided, successful authentication will cache an access token for these scopes.
claims
str

additional claims required in the token, such as those provided by claims

Exceptions

Type Description
ClientAuthenticationError

authentication failed. The error's message attribute gives a reason.

get_token

Request an access token for scopes.

This method is called automatically by Azure SDK clients.

get_token(*scopes: str, claims: str | None = None, tenant_id: str | None = None, enable_cae: bool = False, **kwargs: Any) -> AccessToken

Parameters

Name Description
scopes
Required
str

desired scopes for the access token. This method requires at least one scope. For more information about scopes, see https://zcusa.951200.xyz/entra/identity-platform/scopes-oidc.

Keyword-Only Parameters

Name Description
claims
str

additional claims required in the token, such as those returned in a resource provider's claims challenge following an authorization failure
tenant_id
str

optional tenant to include in the token request.
enable_cae
bool

indicates whether to enable Continuous Access Evaluation (CAE) for the requested token. Defaults to False.

Returns

Type Description
AccessToken

An access token with the desired scopes.

Exceptions

Type Description
CredentialUnavailableError

the credential is unable to attempt authentication because it lacks required data, state, or platform support
ClientAuthenticationError

authentication failed. The error's message attribute gives a reason.
AuthenticationRequiredError

user interaction is necessary to acquire a token, and the credential is configured not to begin this automatically. Call
authenticate

to begin interactive authentication.

get_token_info

Request an access token for scopes.

This is an alternative to get_token to enable certain scenarios that require additional properties on the token. This method is called automatically by Azure SDK clients.

get_token_info(*scopes: str, options: TokenRequestOptions | None = None) -> AccessTokenInfo

Parameters

Name Description
scopes
Required
str

desired scopes for the access token. This method requires at least one scope. For more information about scopes, see https://zcusa.951200.xyz/entra/identity-platform/scopes-oidc.

Keyword-Only Parameters

Name Description
options
TokenRequestOptions

A dictionary of options for the token request. Unknown options will be ignored. Optional.

Returns

Type Description
<xref:AccessTokenInfo>

An AccessTokenInfo instance containing information about the token.

Exceptions

Type Description
CredentialUnavailableError

the credential is unable to attempt authentication because it lacks required data, state, or platform support
ClientAuthenticationError

authentication failed. The error's message attribute gives a reason.
AuthenticationRequiredError

user interaction is necessary to acquire a token, and the credential is configured not to begin this automatically. Call
authenticate

to begin interactive authentication.