• client_id (str) -- Your app has a client_id after you register it on Microsoft Entra admin center.
• client_credential (Union[dict, str, None]) --

  For PublicClientApplication, you use None here.

  For ConfidentialClientApplication, it supports many different input formats for different scenarios.

{


    "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",


    "thumbprint": "A1B2C3D4E5F6...",


    "passphrase": "Passphrase if the private_key is encrypted (Optional. Added in version 1.6.0)",
}

{


    "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",


    "thumbprint": "A1B2C3D4E5F6...",


    "public_certificate": "...-----BEGIN CERTIFICATE-----...",


    "passphrase": "Passphrase if the private_key is encrypted (Optional. Added in version 1.6.0)",
}

{


    "client_assertion": "...a JWT with claims aud, exp, iss, jti, nbf, and sub..."
}

{


    "private_key_pfx_path": "/path/to/your.pfx",


    "passphrase": "Passphrase if the private_key is encrypted (Optional)",
}

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem

{


    "private_key_pfx_path": "/path/to/your.pfx",


    "public_certificate": True,


    "passphrase": "Passphrase if the private_key is encrypted (Optional)",
}

•

client_claims (dict) --

Added in version 0.5.0: It is a dictionary of extra claims that would be signed by by this ConfidentialClientApplication 's private key. For example, you can use {"client_ip": "x.x.x.x"}. You may also override any of the following default claims:

{


    "aud": the_token_endpoint,


    "iss": self.client_id,


    "sub": same_as_issuer,


    "exp": now + 10_min,


    "iat": now,


    "jti": a_random_uuid
}

•

authority (str) --

A URL that identifies a token authority. It should be of the format https://login.microsoftonline.com/your_tenant By default, we will use https://login.microsoftonline.com/common

Changed in version 1.17: you can also use predefined constant and a builder like this:

from msal.authority import (


    AuthorityBuilder,


    AZURE_US_GOVERNMENT, AZURE_CHINA, AZURE_PUBLIC)
my_authority = AuthorityBuilder(AZURE_PUBLIC, "contoso.onmicrosoft.com")
# Now you get an equivalent of
# "https://login.microsoftonline.com/contoso.onmicrosoft.com"
# You can feed such an authority to msal's ClientApplication
from msal import PublicClientApplication
app = PublicClientApplication("my_client_id", authority=my_authority, ...)

• validate_authority (bool) -- (optional) Turns authority validation on or off. This parameter default to true.
• token_cache (TokenCache) -- Sets the token cache used by this ClientApplication instance. By default, an in-memory cache will be created and used.
• http_client -- (optional) Your implementation of abstract class HttpClient <msal.oauth2cli.http.http_client> Defaults to a requests session instance. Since MSAL 1.11.0, the default session would be configured to attempt one retry on connection error. If you are providing your own http_client, it will be your http_client's duty to decide whether to perform retry.
• verify -- (optional) It will be passed to the verify parameter in the underlying requests library This does not apply if you have chosen to pass your own Http client
• proxies -- (optional) It will be passed to the proxies parameter in the underlying requests library This does not apply if you have chosen to pass your own Http client
• timeout -- (optional) It will be passed to the timeout parameter in the underlying requests library This does not apply if you have chosen to pass your own Http client
• app_name -- (optional) You can provide your application name for Microsoft telemetry purposes. Default value is None, means it will not be passed to Microsoft.
• app_version -- (optional) You can provide your application version for Microsoft telemetry purposes. Default value is None, means it will not be passed to Microsoft.
• client_capabilities (list[str]) --

  (optional) Allows configuration of one or more client capabilities, e.g. ["CP1"].

  Client capability is meant to inform the Microsoft identity platform (STS) what this client is capable for, so STS can decide to turn on certain features. For example, if client is capable to handle claims challenge, STS may issue Continuous Access Evaluation (CAE) access tokens to resources, knowing that when the resource emits a claims challenge the client will be able to handle those challenges.

  Implementation details: Client capability is implemented using "claims" parameter on the wire, for now. MSAL will combine them into claims parameter which you will later provide via one of the acquire-token request.

• azure_region (str) --

  (optional) Instructs MSAL to use the Entra regional token service. This legacy feature is only available to first-party applications. Only acquire_token_for_client() is supported.

  Supports 4 values:

NOTE:

New in version 1.12.0.

• exclude_scopes (list[str]) -- (optional) Historically MSAL hardcodes offline_access scope, which would allow your app to have prolonged access to user's data. If that is unnecessary or undesirable for your app, now you can use this parameter to supply an exclusion list of scopes, such as exclude_scopes = ["offline_access"].
• http_cache (dict) --

  MSAL has long been caching tokens in the token_cache. Recently, MSAL also introduced a concept of http_cache, by automatically caching some finite amount of non-token http responses, so that long-lived PublicClientApplication and ConfidentialClientApplication would be more performant and responsive in some situations.

  This http_cache parameter accepts any dict-like object. If not provided, MSAL will use an in-memory dict.

  If your app is a command-line app (CLI), you would want to persist your http_cache across different CLI runs. The following recipe shows a way to do so:

# Just add the following lines at the beginning of your CLI script
import sys, atexit, pickle
http_cache_filename = sys.argv[0] + ".http_cache"
try:


    with open(http_cache_filename, "rb") as f:


        persisted_http_cache = pickle.load(f)  # Take a snapshot
except (


        FileNotFoundError,  # Or IOError in Python 2


        pickle.UnpicklingError,  # A corrupted http cache file


        AttributeError,  # Cache created by a different version of MSAL


        ):


    persisted_http_cache = {}  # Recover by starting afresh
atexit.register(lambda: pickle.dump(


    # When exit, flush it back to the file.


    # It may occasionally overwrite another process's concurrent write,


    # but that is fine. Subsequent runs will reach eventual consistency.


    persisted_http_cache, open(http_cache_file, "wb")))
# And then you can implement your app as you normally would
app = msal.PublicClientApplication(


    "your_client_id",


    ...,


    http_cache=persisted_http_cache,  # Utilize persisted_http_cache


    ...,


    #token_cache=...,  # You may combine the old token_cache trick


        # Please refer to token_cache recipe at


        # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache


    )
app.acquire_token_interactive(["your", "scope"], ...)

Content inside http_cache are cheap to obtain. There is no need to share them among different apps.

Content inside http_cache will contain no tokens nor Personally Identifiable Information (PII). Encryption is unnecessary.

New in version 1.16.0.

•

instance_discovery (boolean) --

Historically, MSAL would connect to a central endpoint located at https://login.microsoftonline.com to acquire some metadata, especially when using an unfamiliar authority. This behavior is known as Instance Discovery.

This parameter defaults to None, which enables the Instance Discovery.

If you know some authorities which you allow MSAL to operate with as-is, without involving any Instance Discovery, the recommended pattern is:

known_authorities = frozenset([  # Treat your known authorities as const


    "https://contoso.com/adfs", "https://login.azs/foo"])
...
authority = "https://contoso.com/adfs"  # Assuming your app will use this
app1 = PublicClientApplication(


    "client_id",


    authority=authority,


    # Conditionally disable Instance Discovery for known authorities


    instance_discovery=authority not in known_authorities,


    )

If you do not know some authorities beforehand, yet still want MSAL to accept any authority that you will provide, you can use a False to unconditionally disable Instance Discovery.

New in version 1.19.0.

• allow_broker (boolean) -- Deprecated. Please use enable_broker_on_windows instead.
• enable_pii_log (boolean) --

  When enabled, logs may include PII (Personal Identifiable Information). This can be useful in troubleshooting broker behaviors. The default behavior is False.

  New in version 1.24.0.

• oidc_authority (str) --

  Added in version 1.28.0: It is a URL that identifies an OpenID Connect (OIDC) authority of the format https://contoso.com/tenant. MSAL will append ".well-known/openid-configuration" to the authority and retrieve the OIDC metadata from there, to figure out the endpoints.

  Note: Broker will NOT be used for OIDC authority.

• auth_code_flow (dict) -- The same dict returned by initiate_auth_code_flow().
• auth_response (dict) -- A dict of the query string received from auth server.
• scopes (list[str]) --

  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 Microsoft Entra, 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.

• 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"))

• code -- The authorization code returned from Authorization Server.
• scopes (list[str]) --

  (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 Microsoft Entra, 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 -- 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 -- 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.

• A successful response would contain "access_token" key,
• an error response would contain "error" and usually "error_description".

• refresh_token (str) -- The old refresh token, as a string.
• scopes (list) -- The scopes associate with this old RT. Each scope needs to be in the Microsoft identity platform (v2) format. See Scopes not resources.

• A dict contains "error" and some other keys, when error happened.
• A dict contains no "error" key means migration was successful.

• username (str) -- Typically a UPN in the form of an email address.
• password (str) -- The password.
• scopes (list[str]) -- Scopes requested to access a protected API (a resource).
• claims_challenge -- 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.
• auth_scheme (object) --

  You can provide an msal.auth_scheme.PopAuthScheme object so that MSAL will get a Proof-of-Possession (POP) token for you.

  New in version 1.26.0.

• A successful response would contain "access_token" key,
• an error response would contain "error" and usually "error_description".

• 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.

• scopes (list[str]) -- (Required) Scopes requested to access a protected API (a resource).
• account -- (Required) One of the account object returned by get_accounts(). Starting from MSAL Python 1.23, a None input will become a NO-OP and always return None.
• force_refresh -- If True, it will skip Access Token look-up, and try to find a Refresh Token to obtain a new Access Token.
• claims_challenge -- 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.
• auth_scheme (object) --

  You can provide an msal.auth_scheme.PopAuthScheme object so that MSAL will get a Proof-of-Possession (POP) token for you.

  New in version 1.26.0.

• 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.

• scopes (list[str]) -- (Required) Scopes requested to access a protected API (a resource).
• state (str) -- Recommended by OAuth2 for CSRF protection.
• login_hint (str) -- Identifier of the user. Generally a User Principal Name (UPN).
• redirect_uri (str) -- Address to return to upon receiving a response from the authority.
• response_type (str) --

  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) -- By default, no prompt value will be sent, not even string "none". You will have to specify a value explicitly. Its valid values are the constants defined in Prompt.
• nonce -- A cryptographically random value used to mitigate replay attacks. See also OIDC specs.
• domain_hint -- 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 available in Auth Code Flow doc and domain_hint doc.
• claims_challenge -- 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.

• scopes (list) -- It is a list of case-sensitive strings.
• redirect_uri (str) -- Optional. If not specified, server will use the pre-registered one.
• state (str) -- 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) -- By default, no prompt value will be sent, not even string "none". You will have to specify a value explicitly. Its valid values are the constants defined in Prompt.
• login_hint (str) -- Optional. Identifier of the user. Generally a User Principal Name (UPN).
• domain_hint --

  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 available in Auth Code Flow doc and domain_hint doc.

• max_age (int) --

  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) -- 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>

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().

What is a broker, and why use it?

A broker is a component installed on your device. Broker implicitly gives your device an identity. By using a broker, your device becomes a factor that can satisfy MFA (Multi-factor authentication). This factor would become mandatory if a tenant's admin enables a corresponding Conditional Access (CA) policy. The broker's presence allows Microsoft identity platform to have higher confidence that the tokens are being issued to your device, and that is more secure.

An additional benefit of broker is, it runs as a long-lived process with your device's OS, and maintains its own cache, so that your broker-enabled apps (even a CLI) could automatically SSO from a previously established signed-in session.

You shall only enable broker when your app:

The fallback behaviors of MSAL Python's broker support

MSAL will either error out, or silently fallback to non-broker flows.

• enable_broker_on_windows (boolean) --

  This setting is only effective if your app is running on Windows 10+. This parameter defaults to None, which means MSAL will not utilize a broker.

  New in MSAL Python 1.25.0.

• enable_broker_on_mac (boolean) --

  This setting is only effective if your app is running on Mac. This parameter defaults to None, which means MSAL will not utilize a broker.

  New in MSAL Python 1.31.0.

• flow (dict) -- A dict previously generated by initiate_device_flow(). By default, this method's polling effect will block current thread. You can abort the polling loop at any time, by changing the value of the flow's "expires_at" key to 0.
• claims_challenge -- 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.

• A successful response would contain "access_token" key,
• an error response would contain "error" and usually "error_description".

• scopes (list) -- It is a list of case-sensitive strings.
• prompt (str) -- By default, no prompt value will be sent, not even string "none". You will have to specify a value explicitly. Its valid values are the constants defined in Prompt.
• login_hint (str) -- Optional. Identifier of the user. Generally a User Principal Name (UPN).
• domain_hint --

  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 available in Auth Code Flow doc and domain_hint doc.

• claims_challenge -- 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.
• timeout (int) -- This method will block the current thread. This parameter specifies the timeout value in seconds. Default value None means wait indefinitely.
• port (int) -- The port to be used to listen to an incoming auth response. By default we will use a system-allocated port. (The rest of the redirect_uri is hard coded as http://localhost.)
• extra_scopes_to_consent (list) -- "Extra scopes to consent" is a concept only available in Microsoft Entra. It refers to other resources you might want to prompt to consent for, in the same interaction, but for which you won't get back a token for in this particular operation.
• max_age (int) --

  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.

• parent_window_handle (int) --

  OPTIONAL.

Most Python scripts are console apps.

New in version 1.20.0.

• on_before_launching_ui (function) --

  A callback with the form of lambda ui="xyz", **kwargs: print("A {} will be launched".format(ui)), where ui will be either "browser" or "broker". You can use it to inform your end user to expect a pop-up window.

  New in version 1.20.0.

• auth_scheme (object) --

  You can provide an msal.auth_scheme.PopAuthScheme object so that MSAL will get a Proof-of-Possession (POP) token for you.

  New in version 1.26.0.

• A dict containing no "error" key, and typically contains an "access_token" key.
• A dict containing an "error" key, when token refresh failed.

• A successful response would contain "user_code" key, among others
• an error response would contain some other readable key/value pairs.

• scopes (list[str]) -- (Required) Scopes requested to access a protected API (a resource).
• claims_challenge -- 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.

• A successful response would contain "access_token" key,
• an error response would contain "error" and usually "error_description".

• user_assertion (str) -- The incoming token already received by this app
• scopes (list[str]) -- Scopes required by downstream API (a resource).
• claims_challenge -- 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.

• A successful response would contain "access_token" key,
• an error response would contain "error" and usually "error_description".

• http_method (str) -- Its value is an uppercase http verb, such as "GET" and "POST".
• url (str) -- The url to be signed.
• nonce (str) -- The nonce came from resource's challenge.