Feedback Edit

ClientApplication Class

  • Reference
Inheritance
builtins.object
ClientApplication

Constructor

ClientApplication(client_id, client_credential=None, authority=None, validate_authority=True, token_cache=None, http_client=None, verify=True, proxies=None, timeout=None, client_claims=None, app_name=None, app_version=None, client_capabilities=None, azure_region=None, exclude_scopes=None, http_cache=None)

Parameters

client_id
client_credential
default value: None
authority
default value: None
validate_authority
default value: True
token_cache
default value: None
http_client
default value: None
verify
default value: True
proxies
default value: None
timeout
default value: None
client_claims
default value: None
app_name
default value: None
app_version
default value: None
client_capabilities
default value: None
azure_region
default value: None
exclude_scopes
default value: None
http_cache
default value: None

Methods

acquire_token_by_auth_code_flow

Validate the auth response being redirected back, and obtain tokens.

It automatically provides nonce protection.
acquire_token_by_authorization_code

The second half of the Authorization Code Grant.
acquire_token_by_refresh_token

Acquire token(s) based on a refresh token (RT) obtained from elsewhere.

You use this method only when you have old RTs from elsewhere, and now you want to migrate them into MSAL. Calling this method results in new tokens automatically storing into MSAL.

You do NOT need to use this method if you are already using MSAL. MSAL maintains RT automatically inside its token cache, and an access token can be retrieved when you call acquire_token_silent.
acquire_token_by_username_password

Gets a token for a given resource via user credentials.

See this page for constraints of Username Password Flow. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication
acquire_token_silent

Acquire an access token for given account, without user interaction.

It is done either by finding a valid access token from cache, or by finding a valid refresh token from cache and then automatically use it to redeem a new access token.

This method will combine the cache empty and refresh error into one return value, None. If your app does not care about the exact token refresh error during token cache look-up, then this method is easier and recommended.

Internally, this method calls acquire_token_silent_with_error.
acquire_token_silent_with_error

Acquire an access token for given account, without user interaction.

It is done either by finding a valid access token from cache, or by finding a valid refresh token from cache and then automatically use it to redeem a new access token.

This method will differentiate cache empty from token refresh error. If your app cares the exact token refresh error during token cache look-up, then this method is suitable. Otherwise, the other method acquire_token_silent is recommended.
get_accounts

Get a list of accounts which previously signed in, i.e. exists in cache.

An account can later be used in acquire_token_silent to find its tokens.
get_authorization_request_url

Constructs a URL for you to start a Authorization Code Grant.
initiate_auth_code_flow

Initiate an auth code flow.

Later when the response reaches your redirect_uri, you can use acquire_token_by_auth_code_flow to complete the authentication/authorization.
remove_account

Sign me out and forget me from token cache

acquire_token_by_auth_code_flow

Validate the auth response being redirected back, and obtain tokens.

It automatically provides nonce protection.

acquire_token_by_auth_code_flow(auth_code_flow, auth_response, scopes=None, **kwargs)

Parameters

auth_code_flow
dict
Required

The same dict returned by initiate_auth_code_flow.

auth_response
dict
Required

A dict of the query string received from auth server.

scopes
list[str]
default value: None

Scopes requested to access a protected API (a resource).

Most of the time, you can leave it empty.

If you requested user consent for multiple resources, here you will need to provide a subset of what you required in initiate_auth_code_flow.

OAuth2 was designed mostly for singleton services, where tokens are always meant for the same resource and the only changes are in the scopes. In AAD, tokens can be issued for multiple 3rd party resources. You can ask authorization code for multiple resources, but when you redeem it, the token is for only one intended recipient, called audience. So the developer need to specify a scope so that we can restrict the token to be issued for the corresponding audience.

Returns

  • A dict containing "access_token" and/or "id_token", among others, depends on what scope was used. (See https://tools.ietf.org/html/rfc6749#section-5.1)

  • A dict containing "error", optionally "error_description", "error_uri". (It is either this or that)

  • Most client-side data error would result in ValueError exception. So the usage pattern could be without any protocol details:

    
   def authorize():  # A controller in a web app
       try:
           result = msal_app.acquire_token_by_auth_code_flow(
               session.get("flow", {}), request.args)
           if "error" in result:
               return render_template("error.html", result)
           use(result)  # Token(s) are available in result and cache
       except ValueError:  # Usually caused by CSRF
           pass  # Simply ignore them
       return redirect(url_for("index"))

acquire_token_by_authorization_code

The second half of the Authorization Code Grant.

acquire_token_by_authorization_code(code, scopes, redirect_uri=None, nonce=None, claims_challenge=None, **kwargs)

Parameters

code
Required

The authorization code returned from Authorization Server.

scopes
list[str]
Required

(Required) Scopes requested to access a protected API (a resource).

If you requested user consent for multiple resources, here you will typically want to provide a subset of what you required in AuthCode.

OAuth2 was designed mostly for singleton services, where tokens are always meant for the same resource and the only changes are in the scopes. In AAD, tokens can be issued for multiple 3rd party resources. You can ask authorization code for multiple resources, but when you redeem it, the token is for only one intended recipient, called audience. So the developer need to specify a scope so that we can restrict the token to be issued for the corresponding audience.

nonce
default value: None

If you provided a nonce when calling get_authorization_request_url, same nonce should also be provided here, so that we'll validate it. An exception will be raised if the nonce in id token mismatches.

claims_challenge
default value: None

The claims_challenge parameter requests specific claims requested by the resource provider in the form of a claims_challenge directive in the www-authenticate header to be returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token. It is a string of a JSON object which contains lists of claims being requested from these locations.

claims_challenge
default value: None

Returns

A dict representing the json response from AAD:

  • A successful response would contain "access_token" key,

  • an error response would contain "error" and usually "error_description".

acquire_token_by_refresh_token

Acquire token(s) based on a refresh token (RT) obtained from elsewhere.

You use this method only when you have old RTs from elsewhere, and now you want to migrate them into MSAL. Calling this method results in new tokens automatically storing into MSAL.

You do NOT need to use this method if you are already using MSAL. MSAL maintains RT automatically inside its token cache, and an access token can be retrieved when you call acquire_token_silent.

acquire_token_by_refresh_token(refresh_token, scopes, **kwargs)

Parameters

refresh_token
str
Required

The old refresh token, as a string.

scopes
list
Required

The scopes associate with this old RT. Each scope needs to be in the Microsoft identity platform (v2) format. See Scopes not resources.

Returns

  • A dict contains "error" and some other keys, when error happened.

  • A dict contains no "error" key means migration was successful.

acquire_token_by_username_password

Gets a token for a given resource via user credentials.

See this page for constraints of Username Password Flow. https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication

acquire_token_by_username_password(username, password, scopes, claims_challenge=None, **kwargs)

Parameters

username
str
Required

Typically a UPN in the form of an email address.

password
str
Required

The password.

scopes
list[str]
Required

Scopes requested to access a protected API (a resource).

claims_challenge
default value: None

The claims_challenge parameter requests specific claims requested by the resource provider in the form of a claims_challenge directive in the www-authenticate header to be returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token. It is a string of a JSON object which contains lists of claims being requested from these locations.

Returns

A dict representing the json response from AAD:

  • A successful response would contain "access_token" key,

  • an error response would contain "error" and usually "error_description".

acquire_token_silent

Acquire an access token for given account, without user interaction.

It is done either by finding a valid access token from cache, or by finding a valid refresh token from cache and then automatically use it to redeem a new access token.

This method will combine the cache empty and refresh error into one return value, None. If your app does not care about the exact token refresh error during token cache look-up, then this method is easier and recommended.

Internally, this method calls acquire_token_silent_with_error.

acquire_token_silent(scopes, account, authority=None, force_refresh=False, claims_challenge=None, **kwargs)

Parameters

claims_challenge
Required

The claims_challenge parameter requests specific claims requested by the resource provider in the form of a claims_challenge directive in the www-authenticate header to be returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token. It is a string of a JSON object which contains lists of claims being requested from these locations.

account
Required
authority
default value: None
force_refresh
default value: False
claims_challenge
default value: None

Returns

  • A dict containing no "error" key, and typically contains an "access_token" key, if cache lookup succeeded.

  • None when cache lookup does not yield a token.

acquire_token_silent_with_error

Acquire an access token for given account, without user interaction.

It is done either by finding a valid access token from cache, or by finding a valid refresh token from cache and then automatically use it to redeem a new access token.

This method will differentiate cache empty from token refresh error. If your app cares the exact token refresh error during token cache look-up, then this method is suitable. Otherwise, the other method acquire_token_silent is recommended.

acquire_token_silent_with_error(scopes, account, authority=None, force_refresh=False, claims_challenge=None, **kwargs)

Parameters

scopes
list[str]
Required

(Required) Scopes requested to access a protected API (a resource).

account
Required

one of the account object returned by get_accounts, or use None when you want to find an access token for this client.

force_refresh
default value: None

If True, it will skip Access Token look-up, and try to find a Refresh Token to obtain a new Access Token.

claims_challenge
default value: False

The claims_challenge parameter requests specific claims requested by the resource provider in the form of a claims_challenge directive in the www-authenticate header to be returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token. It is a string of a JSON object which contains lists of claims being requested from these locations.

claims_challenge
default value: None

Returns

  • A dict containing no "error" key, and typically contains an "access_token" key, if cache lookup succeeded.

  • None when there is simply no token in the cache.

  • A dict containing an "error" key, when token refresh failed.

get_accounts

Get a list of accounts which previously signed in, i.e. exists in cache.

An account can later be used in acquire_token_silent to find its tokens.

get_accounts(username=None)

Parameters

username
default value: None

Filter accounts with this username only. Case insensitive.

Returns

A list of account objects. Each account is a dict. For now, we only document its "username" field. Your app can choose to display those information to end user, and allow user to choose one of his/her accounts to proceed.

get_authorization_request_url

Constructs a URL for you to start a Authorization Code Grant.

get_authorization_request_url(scopes, login_hint=None, state=None, redirect_uri=None, response_type='code', prompt=None, nonce=None, domain_hint=None, claims_challenge=None, **kwargs)

Parameters

scopes
list[str]
Required

(Required) Scopes requested to access a protected API (a resource).

state
str
default value: None

Recommended by OAuth2 for CSRF protection.

login_hint
str
default value: None

Identifier of the user. Generally a User Principal Name (UPN).

redirect_uri
str
default value: None

Address to return to upon receiving a response from the authority.

response_type
str
default value: code

Default value is "code" for an OAuth2 Authorization Code grant.

You could use other content such as "id_token" or "token", which would trigger an Implicit Grant, but that is not recommended.

prompt
str
default value: None

By default, no prompt value will be sent, not even "none". You will have to specify a value explicitly. Its valid values are defined in Open ID Connect specs https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest

nonce
default value: None

A cryptographically random value used to mitigate replay attacks. See also OIDC specs.

domain_hint
default value: None

Can be one of "consumers" or "organizations" or your tenant domain "contoso.com". If included, it will skip the email-based discovery process that user goes through on the sign-in page, leading to a slightly more streamlined user experience. More information on possible values here and here.

claims_challenge
default value: None

The claims_challenge parameter requests specific claims requested by the resource provider in the form of a claims_challenge directive in the www-authenticate header to be returned from the UserInfo Endpoint and/or in the ID Token and/or Access Token. It is a string of a JSON object which contains lists of claims being requested from these locations.

Returns

The authorization url as a string.

initiate_auth_code_flow

Initiate an auth code flow.

Later when the response reaches your redirect_uri, you can use acquire_token_by_auth_code_flow to complete the authentication/authorization.

initiate_auth_code_flow(scopes, redirect_uri=None, state=None, prompt=None, login_hint=None, domain_hint=None, claims_challenge=None, max_age=None, response_mode=None)

Parameters

scopes
list
Required

It is a list of case-sensitive strings.

redirect_uri
str
default value: None

Optional. If not specified, server will use the pre-registered one.

state
str
default value: None

An opaque value used by the client to maintain state between the request and callback. If absent, this library will automatically generate one internally.

prompt
str
default value: None

By default, no prompt value will be sent, not even "none". You will have to specify a value explicitly. Its valid values are defined in Open ID Connect specs https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest

login_hint
str
default value: None

Optional. Identifier of the user. Generally a User Principal Name (UPN).

domain_hint
default value: None

Can be one of "consumers" or "organizations" or your tenant domain "contoso.com". If included, it will skip the email-based discovery process that user goes through on the sign-in page, leading to a slightly more streamlined user experience. More information on possible values here and here.

max_age
int
default value: None

OPTIONAL. Maximum Authentication Age. Specifies the allowable elapsed time in seconds since the last time the End-User was actively authenticated. If the elapsed time is greater than this value, Microsoft identity platform will actively re-authenticate the End-User.

MSAL Python will also automatically validate the auth_time in ID token.

New in version 1.15.

response_mode
str
default value: None

OPTIONAL. Specifies the method with which response parameters should be returned. The default value is equivalent to query, which is still secure enough in MSAL Python (because MSAL Python does not transfer tokens via query parameter in the first place). For even better security, we recommend using the value form_post. In "form_post" mode, response parameters will be encoded as HTML form values that are transmitted via the HTTP POST method and encoded in the body using the application/x-www-form-urlencoded format. Valid values can be either "form_post" for HTTP POST to callback URI or "query" (the default) for HTTP GET with parameters encoded in query string. More information on possible values here https://openid.net/specs/oauth-v2-multiple-response-types-1_0.html#ResponseModes and here https://openid.net/specs/oauth-v2-form-post-response-mode-1_0.html#FormPostResponseMode

response_mode
default value: None

Returns

The auth code flow. It is a dict in this form:


   {
       "auth_uri": "https://...",  // Guide user to visit this
       "state": "...",  // You may choose to verify it by yourself,
                        // or just let acquire_token_by_auth_code_flow()
                        // do that for you.
       "...": "...",  // Everything else are reserved and internal
   }

The caller is expected to:

  1. somehow store this content, typically inside the current session,

  2. guide the end user (i.e. resource owner) to visit that auth_uri,

  3. and then relay this dict and subsequent auth response to acquire_token_by_auth_code_flow.

remove_account

Sign me out and forget me from token cache

remove_account(account)

Parameters

account
Required

Attributes

ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID 

ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID = '832'

ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID 

ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID = '622'

ACQUIRE_TOKEN_BY_REFRESH_TOKEN 

ACQUIRE_TOKEN_BY_REFRESH_TOKEN = '85'

ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID 

ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID = '301'

ACQUIRE_TOKEN_FOR_CLIENT_ID 

ACQUIRE_TOKEN_FOR_CLIENT_ID = '730'

ACQUIRE_TOKEN_INTERACTIVE 

ACQUIRE_TOKEN_INTERACTIVE = '169'

ACQUIRE_TOKEN_ON_BEHALF_OF_ID 

ACQUIRE_TOKEN_ON_BEHALF_OF_ID = '523'

ACQUIRE_TOKEN_SILENT_ID 

ACQUIRE_TOKEN_SILENT_ID = '84'

ATTEMPT_REGION_DISCOVERY 

ATTEMPT_REGION_DISCOVERY = True

GET_ACCOUNTS_ID 

GET_ACCOUNTS_ID = '902'

REMOVE_ACCOUNT_ID 

REMOVE_ACCOUNT_ID = '903'