Welcome to ADAL Python’s documentation!

You can find high level conceptual documentations in the project wiki and workable samples inside the project code base

The documentation hosted here is for API Reference.

AuthenticationContext

The majority of ADAL Python functionalities are provided via the main class named AuthenticationContext.

class adal.AuthenticationContext(authority, validate_authority=None, cache=None, api_version=None, timeout=None, enable_pii=False, verify_ssl=None, proxies=None)

Retrieves authentication tokens from Azure Active Directory.

For usages, check out the “sample” folder at:
https://github.com/AzureAD/azure-activedirectory-library-for-python

Creates a new AuthenticationContext object.

By default the authority will be checked against a list of known Azure Active Directory authorities. If the authority is not recognized as one of these well known authorities then token acquisition will fail. This behavior can be turned off via the validate_authority parameter below.

Parameters:
  • authority (str) – A URL that identifies a token authority. It should be of the format https://login.microsoftonline.com/your_tenant
  • validate_authority (bool) – (optional) Turns authority validation on or off. This parameter default to true.
  • cache (TokenCache) – (optional) Sets the token cache used by this AuthenticationContext instance. If this parameter is not set, then a default is used. Cache instances is only used by that instance of the AuthenticationContext and are not shared unless it has been manually passed during the construction of other AuthenticationContexts.
  • api_version – (optional) Specifies API version using on the wire. Historically it has a hardcoded default value as “1.0”. Developers have been encouraged to set it as None explicitly, which means the underlying API version will be automatically chosen. Starting from ADAL Python 1.0, this default value becomes None.
  • timeout – (optional) requests timeout. How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) <timeouts> tuple.
  • enable_pii – (optional) Unless this is set to True, there will be no Personally Identifiable Information (PII) written in log.
  • verify_ssl – (optional) requests verify. Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use. If this value is not provided, and ADAL_PYTHON_SSL_NO_VERIFY env varaible is set, behavior is equivalent to verify_ssl=False.
  • proxies – (optional) requests proxies. Dictionary mapping protocol to the URL of the proxy. See http://docs.python-requests.org/en/master/user/advanced/#proxies for details.
__init__(authority, validate_authority=None, cache=None, api_version=None, timeout=None, enable_pii=False, verify_ssl=None, proxies=None)

Creates a new AuthenticationContext object.

By default the authority will be checked against a list of known Azure Active Directory authorities. If the authority is not recognized as one of these well known authorities then token acquisition will fail. This behavior can be turned off via the validate_authority parameter below.

Parameters:
  • authority (str) – A URL that identifies a token authority. It should be of the format https://login.microsoftonline.com/your_tenant
  • validate_authority (bool) – (optional) Turns authority validation on or off. This parameter default to true.
  • cache (TokenCache) – (optional) Sets the token cache used by this AuthenticationContext instance. If this parameter is not set, then a default is used. Cache instances is only used by that instance of the AuthenticationContext and are not shared unless it has been manually passed during the construction of other AuthenticationContexts.
  • api_version – (optional) Specifies API version using on the wire. Historically it has a hardcoded default value as “1.0”. Developers have been encouraged to set it as None explicitly, which means the underlying API version will be automatically chosen. Starting from ADAL Python 1.0, this default value becomes None.
  • timeout – (optional) requests timeout. How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) <timeouts> tuple.
  • enable_pii – (optional) Unless this is set to True, there will be no Personally Identifiable Information (PII) written in log.
  • verify_ssl – (optional) requests verify. Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use. If this value is not provided, and ADAL_PYTHON_SSL_NO_VERIFY env varaible is set, behavior is equivalent to verify_ssl=False.
  • proxies – (optional) requests proxies. Dictionary mapping protocol to the URL of the proxy. See http://docs.python-requests.org/en/master/user/advanced/#proxies for details.
acquire_token(resource, user_id, client_id)

Gets a token for a given resource via cached tokens.

Parameters:
  • resource (str) – A URI that identifies the resource for which the token is valid.
  • user_id (str) – The username of the user on behalf this application is authenticating.
  • client_id (str) – The OAuth client id of the calling application.
Returns:

dic with several keys, include “accessToken” and “refreshToken”.

acquire_token_with_authorization_code(authorization_code, redirect_uri, resource, client_id, client_secret=None, code_verifier=None)

Gets a token for a given resource via auhtorization code for a server app.

Parameters:
  • authorization_code (str) – An authorization code returned from a client.
  • redirect_uri (str) – the redirect uri that was used in the authorize call.
  • resource (str) – A URI that identifies the resource for which the token is valid.
  • client_id (str) – The OAuth client id of the calling application.
  • client_secret (str) – (only for confidential clients)The OAuth client secret of the calling application. This parameter if not set, defaults to None
  • code_verifier (str) – (optional)The code verifier that was used to obtain authorization code if PKCE was used in the authorization code grant request.(usually used by public clients) This parameter if not set, defaults to None
Returns:

dict with several keys, include “accessToken” and “refreshToken”.

acquire_token_with_client_certificate(resource, client_id, certificate, thumbprint, public_certificate=None)

Gets a token for a given resource via certificate credentials

Parameters:
  • resource (str) – A URI that identifies the resource for which the token is valid.
  • client_id (str) – The OAuth client id of the calling application.
  • certificate (str) – A PEM encoded certificate private key.
  • thumbprint (str) – hex encoded thumbprint of the certificate.
  • public_certificate(optional) – if not None, it will be sent to the service for subject name and issuer based authentication, which is to support cert auto rolls. The value must match the certificate private key parameter.
Returns:

dict with several keys, include “accessToken”.

acquire_token_with_client_credentials(resource, client_id, client_secret)

Gets a token for a given resource via client credentials.

Parameters:
  • resource (str) – A URI that identifies the resource for which the token is valid.
  • client_id (str) – The OAuth client id of the calling application.
  • client_secret (str) – The OAuth client secret of the calling application.
Returns:

dict with several keys, include “accessToken”.

acquire_token_with_device_code(resource, user_code_info, client_id)

Gets a new access token using via a device code.

Parameters:
  • resource (str) – A URI that identifies the resource for which the token is valid.
  • user_code_info (dict) – The code info from the invocation of “acquire_user_code”
  • client_id (str) – The OAuth client id of the calling application.
Returns:

dict with several keys, include “accessToken” and “refreshToken”.

acquire_token_with_refresh_token(refresh_token, client_id, resource, client_secret=None)

Gets a token for a given resource via refresh tokens

Parameters:
  • refresh_token (str) – A refresh token returned in a tokne response from a previous invocation of acquireToken.
  • client_id (str) – The OAuth client id of the calling application.
  • resource (str) – A URI that identifies the resource for which the token is valid.
  • client_secret (str) – (optional)The OAuth client secret of the calling application.
Returns:

dict with several keys, include “accessToken” and “refreshToken”.

acquire_token_with_username_password(resource, username, password, client_id)

Gets a token for a given resource via user credentails.

Parameters:
  • resource (str) – A URI that identifies the resource for which the token is valid.
  • username (str) – The username of the user on behalf this application is authenticating.
  • password (str) – The password of the user named in the username parameter.
  • client_id (str) – The OAuth client id of the calling application.
Returns:

dict with several keys, include “accessToken” and “refreshToken”.

acquire_user_code(resource, client_id, language=None)

Gets the user code info which contains user_code, device_code for authenticating user on device.

Parameters:
  • resource (str) – A URI that identifies the resource for which the device_code and user_code is valid for.
  • client_id (str) – The OAuth client id of the calling application.
  • language (str) – The language code specifying how the message should be localized to.
Returns:

dict contains code and uri for users to login through browser.

cancel_request_to_get_token_with_device_code(user_code_info)

Cancels the polling request to get token with device code.

Parameters:user_code_info (dict) – The code info from the invocation of “acquire_user_code”
Returns:None

TokenCache

One of the parameter accepted by AuthenticationContext is the TokenCache.

class adal.TokenCache(state=None)
add(entries)
deserialize(state)
find(query)
read_items()

output list of tuples in (key, authentication-result)

remove(entries)
serialize()

If you need to subclass it, you need to refer to its source code for the detail.

AdalError

When errors are detected by ADAL Python, it will raise this exception.

class adal.AdalError(error_msg, error_response=None)