



  

ADAL Python documentation

 [ADAL Python](index.html#document-index) 

 latest

 

[ADAL Python](index.html#document-index)

* [Docs](index.html#document-index) »

* ADAL Python documentation

* [Edit on GitHub](https://github.com/AzureAD/azure-activedirectory-library-for-python/blob/one-pager/docs/source/index.rst)

---

Welcome to ADAL Python’s documentation![¶](#welcome-to-adal-python-s-documentation "Permalink to this headline")

================================================================================================================

You can find high level conceptual documentations in the project

[wiki](https://github.com/AzureAD/azure-activedirectory-library-for-python/wiki)

and

[workable samples inside the project code base](https://github.com/AzureAD/azure-activedirectory-library-for-python/tree/dev/sample)

The documentation hosted here is for API Reference.

AuthenticationContext[¶](#authenticationcontext "Permalink to this headline")

=============================================================================

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='1.0'*, *timeout=None*, *enable\_pii=False*)[¶](#adal.AuthenticationContext "Permalink to this definition")

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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URL that identifies a token authority.

* **validate\_authority** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.6)")) – (optional) Turns authority validation 

on or off. This parameter default to true.

* **cache** ([*TokenCache*](#adal.TokenCache "adal.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 are now encouraged to set it as None explicitly,

which means the underlying API version will be automatically chosen.

In next major release, this default value will be changed to 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.

 |

`__init__`(*authority*, *validate\_authority=None*, *cache=None*, *api\_version='1.0'*, *timeout=None*, *enable\_pii=False*)[¶](#adal.AuthenticationContext.__init__ "Permalink to this definition")

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*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URL that identifies a token authority.

* **validate\_authority** ([*bool*](https://docs.python.org/3/library/functions.html#bool "(in Python v3.6)")) – (optional) Turns authority validation 

on or off. This parameter default to true.

* **cache** ([*TokenCache*](#adal.TokenCache "adal.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 are now encouraged to set it as None explicitly,

which means the underlying API version will be automatically chosen.

In next major release, this default value will be changed to 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.

 |

`acquire_token`(*resource*, *user\_id*, *client\_id*)[¶](#adal.AuthenticationContext.acquire_token "Permalink to this definition")

Gets a token for a given resource via cached tokens.

| Parameters: | * **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the

token is valid.

* **user\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The username of the user on behalf this application

is authenticating.

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – 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*)[¶](#adal.AuthenticationContext.acquire_token_with_authorization_code "Permalink to this definition")

Gets a token for a given resource via auhtorization code for a

server app.

| Parameters: | * **authorization\_code** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – An authorization code returned from a

client.

* **redirect\_uri** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – the redirect uri that was used in the

authorize call.

* **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the

token is valid.

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The OAuth client id of the calling application.

* **client\_secret** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The OAuth client secret of the calling

application.

 |

| Returns: | dict with several keys, include “accessToken” and

“refreshToken”. |

`acquire_token_with_client_certificate`(*resource*, *client\_id*, *certificate*, *thumbprint*)[¶](#adal.AuthenticationContext.acquire_token_with_client_certificate "Permalink to this definition")

Gets a token for a given resource via certificate credentials

| Parameters: | * **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the

token is valid.

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The OAuth client id of the calling application.

* **certificate** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A PEM encoded certificate private key.

* **thumbprint** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – hex encoded thumbprint of the certificate.

 |

| Returns: | dict with several keys, include “accessToken”. |

`acquire_token_with_client_credentials`(*resource*, *client\_id*, *client\_secret*)[¶](#adal.AuthenticationContext.acquire_token_with_client_credentials "Permalink to this definition")

Gets a token for a given resource via client credentials.

| Parameters: | * **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the 

token is valid.

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The OAuth client id of the calling application.

* **client\_secret** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – 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*)[¶](#adal.AuthenticationContext.acquire_token_with_device_code "Permalink to this definition")

Gets a new access token using via a device code.

| Parameters: | * **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the

token is valid.

* **user\_code\_info** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.6)")) – The code info from the invocation of

“acquire\_user\_code”

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – 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*)[¶](#adal.AuthenticationContext.acquire_token_with_refresh_token "Permalink to this definition")

Gets a token for a given resource via refresh tokens

| Parameters: | * **refresh\_token** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A refresh token returned in a tokne response

from a previous invocation of acquireToken.

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The OAuth client id of the calling application.

* **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the

token is valid.

* **client\_secret** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – (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*)[¶](#adal.AuthenticationContext.acquire_token_with_username_password "Permalink to this definition")

Gets a token for a given resource via user credentails.

| Parameters: | * **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the 

token is valid.

* **username** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The username of the user on behalf this

application is authenticating.

* **password** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The password of the user named in the username

parameter.

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – 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*)[¶](#adal.AuthenticationContext.acquire_user_code "Permalink to this definition")

Gets the user code info which contains user\_code, device\_code for

authenticating user on device.

| Parameters: | * **resource** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – A URI that identifies the resource for which the 

device\_code and user\_code is valid for.

* **client\_id** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – The OAuth client id of the calling application.

* **language** ([*str*](https://docs.python.org/3/library/stdtypes.html#str "(in Python v3.6)")) – 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*)[¶](#adal.AuthenticationContext.cancel_request_to_get_token_with_device_code "Permalink to this definition")

Cancels the polling request to get token with device code.

| Parameters: | **user\_code\_info** ([*dict*](https://docs.python.org/3/library/stdtypes.html#dict "(in Python v3.6)")) – The code info from the invocation of

“acquire\_user\_code” |

| Returns: | None |

TokenCache[¶](#tokencache "Permalink to this headline")

=======================================================

One of the parameter accepted by AuthenticationContext is the TokenCache.

*class* `adal.``TokenCache`(*state=None*)[¶](#adal.TokenCache "Permalink to this definition")

`add`(*entries*)[¶](#adal.TokenCache.add "Permalink to this definition")

`deserialize`(*state*)[¶](#adal.TokenCache.deserialize "Permalink to this definition")

`find`(*query*)[¶](#adal.TokenCache.find "Permalink to this definition")

`read_items`()[¶](#adal.TokenCache.read_items "Permalink to this definition")

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

`remove`(*entries*)[¶](#adal.TokenCache.remove "Permalink to this definition")

`serialize`()[¶](#adal.TokenCache.serialize "Permalink to this definition")

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

AdalError[¶](#adalerror "Permalink to this headline")

=====================================================

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

*class* `adal.``AdalError`(*error\_msg*, *error\_response=None*)[¶](#adal.AdalError "Permalink to this definition")

