MSAL Python

https://msal-python.readthedocs.io/en/latest
Admin
MSAL Python is a Microsoft Authentication Library for Python that enables applications to...
Tokens:36,124
Snippets:155
Trust Score:8.3
Update:21 hours ago
Show doc for...
Tokens:
Raw
### acquire_token_for_client with fmi_path

Source: https://msal-python.readthedocs.io/en/latest/

Example usage of acquire_token_for_client with the optional fmi_path parameter. The fmi_path is sent in the token request body and the resulting token is cached separately per FMI path.

```python
result = cca.acquire_token_for_client(
    scopes=["api://resource/.default"],
    fmi_path="SomeFmiPath/FmiCredentialPath",
)
```

--------------------------------

### ClientApplication.initiate_auth_code_flow

Source: https://msal-python.readthedocs.io/en/latest/

Initiates an auth code flow. The returned dict contains an auth_uri to guide the user to visit, and a state value. The caller is expected to redirect the user to the auth_uri and later use acquire_token_by_auth_code_flow() to complete the flow.

```APIDOC
## ClientApplication.initiate_auth_code_flow

### Description
Initiates 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.

### Method
initiate_auth_code_flow

### Signature
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) - Optional - If not specified, server will use the pre-registered one.
- **state** (str) - Optional - 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) - Optional - 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** (str) - Optional - 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.
- **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`. For even better security, we recommend using the value `form_post`. 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.

### 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:
```

--------------------------------

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

Source: https://msal-python.readthedocs.io/en/latest/

Constructs a URL to start an Authorization Code Grant. This URL is used to redirect the user to the authorization endpoint.

```APIDOC
## 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)

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

### Method
Python method

### Parameters
- **scopes** (list[str]) - Required - Scopes requested to access a protected API (a resource).
- **state** (str) - Optional - Recommended by OAuth2 for CSRF protection.
- **login_hint** (str) - Optional - Identifier of the user. Generally a User Principal Name (UPN).
- **redirect_uri** (str) - Optional - Address to return to upon receiving a response from the authority.
- **response_type** (str) - Optional - 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) - Optional - 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** - Optional - A cryptographically random value used to mitigate replay attacks. See also OIDC specs.
- **domain_hint** - Optional - 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.
- **claims_challenge** - Optional - 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.
```

--------------------------------

### ClientApplication.__init__

Source: https://msal-python.readthedocs.io/en/latest/

Initializes a new instance of the ClientApplication class. This is the base class for public and confidential client applications.

```APIDOC
## ClientApplication.__init__

### Description
Initializes a new instance of the ClientApplication class. This is the base class for public and confidential client applications.

### Method
Constructor

### Signature
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, instance_discovery=None, allow_broker=None, enable_pii_log=None, oidc_authority=None)

### Parameters
- **client_id** (str) - Required - Your app has a client_id after you register it on Microsoft Entra admin center.
- **client_credential** (Union[dict, str, None]) - Optional - For PublicClientApplication, use None. For ConfidentialClientApplication, supports different input formats for different scenarios, such as a client secret string or a certificate in X.509 (.pem) format.
- **authority** - Optional - Authority URL.
- **validate_authority** (bool) - Optional - Whether to validate the authority.
- **token_cache** - Optional - Token cache instance.
- **http_client** - Optional - HTTP client instance.
- **verify** (bool) - Optional - Whether to verify SSL certificates.
- **proxies** - Optional - Proxy configuration.
- **timeout** - Optional - Timeout for HTTP requests.
- **client_claims** - Optional - Additional client claims.
- **app_name** - Optional - Application name.
- **app_version** - Optional - Application version.
- **client_capabilities** - Optional - Client capabilities.
- **azure_region** - Optional - Azure region.
- **exclude_scopes** - Optional - Scopes to exclude.
- **http_cache** - Optional - HTTP cache instance.
- **instance_discovery** - Optional - Whether to perform instance discovery.
- **allow_broker** - Optional - Whether to allow broker.
- **enable_pii_log** - Optional - Whether to enable PII logging.
- **oidc_authority** - Optional - OIDC authority.

### Response
No return value.
```

--------------------------------

### acquire_token_by_username_password

Source: https://msal-python.readthedocs.io/en/latest/

Gets a token for a given resource via user credentials. See the constraints of Username Password Flow in the provided link.

```APIDOC
## acquire_token_by_username_password

### Description
Gets a token for a given resource via user credentials. See the constraints of Username Password Flow in the provided link.

### Method
POST

### Endpoint
Not specified

### Parameters
#### Path 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** - Optional - 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) - Optional - 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.

### Response
#### Success Response (200)
- **access_token** (str) - Present in a successful response.

#### Error Response
- **error** (str) - Present in an error response.
- **error_description** (str) - Usually present in an error response.

#### Response Example
{
  "access_token": "..."
}
```

--------------------------------

### PublicClientApplication.__init__

Source: https://msal-python.readthedocs.io/en/latest/

Initializes a PublicClientApplication instance. This constructor is the same as ClientApplication.__init__ except that client_credential must be None. It also accepts broker opt-in flags for various platforms.

```APIDOC
## [POST] /PublicClientApplication/__init__

### Description
Initializes a PublicClientApplication instance. This constructor is the same as ClientApplication.__init__ except that client_credential must be None. It also accepts broker opt-in flags for various platforms.

### Method
POST

### Endpoint
PublicClientApplication/__init__

### Parameters
#### Request Body
- **client_id** (string) - Required - The application client ID.
- **client_credential** (string) - Optional - Must be None for public client.
- **enable_broker_on_windows** (boolean) - Optional - Opt-in to use broker on Windows 10+.
- **enable_broker_on_mac** (boolean) - Optional - Opt-in to use broker on Apple Silicon Mac with Company Portal installed.
- **enable_broker_on_linux** (boolean) - Optional - Opt-in to use broker on Linux with Intune installed.
- **enable_broker_on_wsl** (boolean) - Optional - Opt-in to use broker on WSL.

### Request Example
{
  "client_id": "your-client-id",
  "client_credential": null,
  "enable_broker_on_windows": true,
  "enable_broker_on_mac": false,
  "enable_broker_on_linux": false,
  "enable_broker_on_wsl": false
}

### Response
#### Success Response (200)
- **instance** (object) - The created PublicClientApplication instance.

#### Response Example
{
  "instance": {}
}
```

--------------------------------

### ClientApplication Constructor

Source: https://msal-python.readthedocs.io/en/latest/

Initializes a ClientApplication instance with configurable parameters for authentication, token caching, HTTP client behavior, and telemetry.

```APIDOC
## ClientApplication Constructor

### Description
Initializes a ClientApplication instance with configurable parameters for authentication, token caching, HTTP client behavior, and telemetry.

### Parameters
- **client_claims** (dict) - Optional - A dictionary of extra claims that will be signed by the ConfidentialClientApplication's private key. Overrides default claims: aud, iss, sub, exp, iat, jti.
- **authority** (str) - Optional - A URL identifying a token authority. Format: https://login.microsoftonline.com/your_tenant. Default: https://login.microsoftonline.com/common. Since version 1.17, can also use AuthorityBuilder with predefined constants.
- **validate_authority** (bool) - Optional - Turns authority validation on or off. Default: true.
- **token_cache** (TokenCache) - Optional - Sets the token cache used by this ClientApplication instance. Default: an in-memory cache.
- **http_client** - Optional - Your implementation of abstract class HttpClient. Defaults to a requests session instance with one retry on connection error.
- **verify** - Optional - Passed to the verify parameter in the underlying requests library. Not applicable if custom http_client is provided.
- **proxies** - Optional - Passed to the proxies parameter in the underlying requests library. Not applicable if custom http_client is provided.
- **timeout** - Optional - Passed to the timeout parameter in the underlying requests library. Not applicable if custom http_client is provided.
- **app_name** - Optional - Application name for Microsoft telemetry. Default: None.
- **app_version** - Optional - Application version for Microsoft telemetry. Default: None.

### Example
```python
from msal import PublicClientApplication
app = PublicClientApplication("my_client_id", authority=my_authority, ...)
```
```

--------------------------------

### ClientApplication Constructor

Source: https://msal-python.readthedocs.io/en/latest/

Initializes a ClientApplication instance with parameters for authority, instance discovery, broker, PII logging, and OIDC authority.

```APIDOC
## ClientApplication Constructor

### Description
Initializes a ClientApplication instance with configurable parameters for authority, instance discovery, broker, PII logging, and OIDC authority.

### Method
Constructor

### Parameters
#### Constructor Parameters
- **authority** (str) - Optional - The authority URL. Defaults to Microsoft Entra ID authority.
- **instance_discovery** (boolean) - Optional - Enables or disables Instance Discovery. Defaults to None (enabled).
- **allow_broker** (boolean) - Deprecated - Use `enable_broker_on_windows` instead.
- **enable_pii_log** (boolean) - Optional - When enabled, logs may include PII. Default is False.
- **oidc_authority** (str) - Optional - URL identifying an OIDC authority. MSAL appends `.well-known/openid-configuration` to retrieve metadata.
- **http_cache** (dict) - Optional - A persisted HTTP cache to reuse across runs.

### Request Example
```python
app = msal.PublicClientApplication(
    "your_client_id",
    authority="https://contoso.com/adfs",
    instance_discovery=False,
    enable_pii_log=False,
    oidc_authority="https://contoso.com/tenant",
    http_cache=persisted_http_cache,
)
```

### Response
No return value.
```

--------------------------------

### PublicClientApplication.acquire_token_interactive(scopes, prompt=None, login_hint=None, domain_hint=None, claims_challenge=None, timeout=None, port=None, extra_scopes_to_consent=None, max_age=None, parent_window_handle=None, on_before_launching_ui=None, auth_scheme=None, **kwargs)

Source: https://msal-python.readthedocs.io/en/latest/

Acquires a token interactively via a local browser. Prerequisite: In Azure Portal, configure the Redirect URI of your "Mobile and Desktop application" as http://localhost. If you opt in to use broker during PublicClientApplication creation, your app also needs the Redirect URI: ms-appx-web://Microsoft.AAD.BrokerPlugin/YOUR_CLIENT_ID.

```APIDOC
## PublicClientApplication.acquire_token_interactive(scopes, prompt=None, login_hint=None, domain_hint=None, claims_challenge=None, timeout=None, port=None, extra_scopes_to_consent=None, max_age=None, parent_window_handle=None, on_before_launching_ui=None, auth_scheme=None, **kwargs)

### Description
Acquire token interactively i.e. via a local browser.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scopes** (list) - Required - It is a list of case-sensitive strings.
- **prompt** (str) - Optional - 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** - Optional - (Documentation not provided in source)
- **claims_challenge** - Optional - (Documentation not provided in source)
- **timeout** - Optional - (Documentation not provided in source)
- **port** - Optional - (Documentation not provided in source)
- **extra_scopes_to_consent** - Optional - (Documentation not provided in source)
- **max_age** - Optional - (Documentation not provided in source)
- **parent_window_handle** - Optional - (Documentation not provided in source)
- **on_before_launching_ui** - Optional - (Documentation not provided in source)
- **auth_scheme** - Optional - (Documentation not provided in source)

### Request Example
N/A

### Response
#### Success Response (200)
- **access_token** - Present in a successful response.
- **error** - Present in an error response.
- **error_description** - Usually present in an error response.

#### Response Example
N/A
```

--------------------------------

### PublicClientApplication constructor parameters (broker configuration)

Source: https://msal-python.readthedocs.io/en/latest/

Parameters for enabling broker support on various platforms when creating a PublicClientApplication instance. These settings are only effective on specific operating systems and default to None, meaning MSAL will not utilize a broker.

```APIDOC
## PublicClientApplication constructor parameters (broker configuration)

### Description
Parameters for enabling broker support on various platforms when creating a PublicClientApplication instance.

### Method
N/A (SDK constructor)

### Endpoint
N/A (SDK constructor)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **enable_broker_on_windows** (boolean) - Optional - 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) - Optional - This setting is only effective if your app is running on an Apple Silicon (arm64) Mac. Broker is not supported on Intel-based Macs, where this setting is ignored and MSAL will fall back to non-broker. This parameter defaults to None, which means MSAL will not utilize a broker. New in MSAL Python 1.31.0.
- **enable_broker_on_linux** (boolean) - Optional - This setting is only effective if your app is running on Linux, including WSL. This parameter defaults to None, which means MSAL will not utilize a broker. New in MSAL Python 1.33.0.
- **enable_broker_on_wsl** (boolean) - Optional - This setting is only effective if your app is running on WSL. This parameter defaults to None, which means MSAL will not utilize a broker. New in MSAL Python 1.33.0.

### Request Example
N/A

### Response
#### Success Response (200)
N/A

#### Response Example
N/A
```

--------------------------------

### initiate_device_flow

Source: https://msal-python.readthedocs.io/en/latest/

Initiates a Device Flow instance, which will be used in acquire_token_by_device_flow().

```APIDOC
## initiate_device_flow

### Description
Initiates a Device Flow instance, which will be used in acquire_token_by_device_flow().

### Method
Not applicable (SDK method)

### Endpoint
Not applicable (SDK method)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **scopes** (list) - Optional - Scopes requested for the token.
- **claims_challenge** (string) - Optional - JSON string of claims requested by the resource provider.
- **kwargs** - Optional - Additional keyword arguments.

### Request Example
```python
flow = app.initiate_device_flow(scopes=["https://graph.microsoft.com/.default"])
```

### Response
#### Success Response (200)
- A device flow instance to be used with acquire_token_by_device_flow().

#### Response Example
```json
{
  "user_code": "ABC123",
  "device_code": "...",
  "verification_uri": "https://microsoft.com/devicelogin"
}
```
```

--------------------------------

### Recipe 2: Load managed identity configuration from environment variable

Source: https://msal-python.readthedocs.io/en/latest/

Loads a JSON configuration from the MY_MANAGED_IDENTITY_CONFIG environment variable, which can specify either a client ID or system-assigned identity. Asserts the variable exists, then creates a ManagedIdentityClient and acquires a token.

```python
import json, os, msal, requests
config = os.getenv("MY_MANAGED_IDENTITY_CONFIG")
assert config, "An ENV VAR with value should exist"
client = msal.ManagedIdentityClient(
    json.loads(config),
    http_client=requests.Session(),
    )
token = client.acquire_token_for_client("resource")
```

--------------------------------

### msal.PopAuthScheme.__init__

Source: https://msal-python.readthedocs.io/en/latest/

Creates an auth scheme needed to obtain a Proof-of-Possession token. The constructor accepts an HTTP method, URL, and nonce.

```APIDOC
## msal.PopAuthScheme.__init__

### Description
Creates an auth scheme needed to obtain a Proof-of-Possession token.

### Method
Constructor

### Signature
`__init__(http_method=None, url=None, nonce=None)`

### Parameters
- **http_method** (str) - Optional - Uppercase HTTP verb, such as "GET" and "POST".
- **url** (str) - Optional - The URL to be signed.
- **nonce** (str) - Optional - The nonce from the resource's challenge.

### Usage
This class is used as the `auth_scheme` parameter in many acquire token methods to support Proof of Possession (PoP) tokens.

### Class Constants
- `HTTP_GET = 'GET'`
- `HTTP_POST = 'POST'`
- `HTTP_PUT = 'PUT'`
- `HTTP_DELETE = 'DELETE'`
- `HTTP_PATCH = 'PATCH'`
```

--------------------------------

### Generate PFX file with openssl

Source: https://msal-python.readthedocs.io/en/latest/

Command to generate a .pfx file from a .key and .pem file. Use this to convert your certificate to PFX format for use with the private_key_pfx_path option.

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

--------------------------------

### ClientApplication Parameters

Source: https://msal-python.readthedocs.io/en/latest/

Configuration parameters for the MSAL Python ClientApplication class.

```APIDOC
## ClientApplication Parameters

### Description
Configuration parameters for the MSAL Python ClientApplication class.

### Parameters

#### client_capabilities
- **Type**: list[str]
- **Optional**: Yes
- **Description**: Allows configuration of one or more client capabilities, e.g. ["CP1"]. Client capability informs the Microsoft identity platform (STS) what this client is capable of, 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. 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
- **Type**: str
- **Optional**: Yes
- **Description**: 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:
  1. `azure_region=None` - This default value means no region is configured. MSAL will use the region defined in env var `MSAL_FORCE_REGION`.
  2. `azure_region="some_region"` - meaning the specified region is used.
  3. `azure_region=True` - meaning MSAL will try to auto-detect the region. This is not recommended.
  4. `azure_region=False` - meaning MSAL will use no region.
  Note: Region auto-discovery has been tested on VMs and on Azure Functions. It is unreliable. Applications using this option should configure a short timeout. For more details and for the values of the region string see https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting. New in version 1.12.0.

#### exclude_scopes
- **Type**: list[str]
- **Optional**: Yes
- **Description**: 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
- **Type**: dict
- **Optional**: Yes
- **Description**: 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 persisted file's format may change due to, but not limited to, unstable protocol, so your implementation shall tolerate unexpected loading errors.
```

--------------------------------

### Recipe 1: Hard code a managed identity for your app

Source: https://msal-python.readthedocs.io/en/latest/

Creates a ManagedIdentityClient with a user-assigned managed identity specified by client_id and a requests.Session as http_client. Then acquires a token for a resource.

```python
import msal, requests
client = msal.ManagedIdentityClient(
    msal.UserAssignedManagedIdentity(client_id="foo"),
    http_client=requests.Session(),
    )
token = client.acquire_token_for_client("resource")
```

--------------------------------

### File-based cache persistence recipe using msal.SerializableTokenCache

Source: https://msal-python.readthedocs.io/en/latest/

This snippet shows a simple recipe for persisting the token cache to a file, using the XDG_RUNTIME_DIR environment variable to automatically wipe the cache on Linux when the user's SSH session ends. It registers an atexit handler to write the cache only if has_state_changed is true. Note that this does not encrypt the cache; for encryption, use MSAL Extensions.

```python
import os, atexit, msal
cache_filename = os.path.join(  # Persist cache into this file
    os.getenv(
        # Automatically wipe out the cache from Linux when user's ssh session ends.
        # See also https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/690
        "XDG_RUNTIME_DIR", ""),
    "my_cache.bin")
cache = msal.SerializableTokenCache()
if os.path.exists(cache_filename):
    cache.deserialize(open(cache_filename, "r").read())
atexit.register(lambda:
    open(cache_filename, "w").write(cache.serialize())
    # Hint: The following optional line persists only when state changed
    if cache.has_state_changed else None
    )
app = msal.ClientApplication(..., token_cache=cache)
...
```

--------------------------------

### msal.PublicClientApplication.initiate_device_flow

Source: https://msal-python.readthedocs.io/en/latest/

Initiates a device flow to obtain a token for a public client application. This method is part of the PublicClientApplication class.

```APIDOC
## initiate_device_flow

### Description
Initiates a device flow to obtain a token for a public client application. This method is part of the PublicClientApplication class.

### Method
POST

### Endpoint
Not applicable (SDK method)

### Parameters
#### Required Parameters
- **scopes** (list of str) - Required - Scopes requested to access a protected API (a resource).

### Response
#### Success Response
- A dict representing a newly created Device Flow object. A successful response would contain "user_code" key, among others.

#### Error Response
- An error response would contain some other readable key/value pairs.

```

--------------------------------

### acquire_token_on_behalf_of(user_assertion, scopes, claims_challenge=None, forwarded_client_claims=None, **kwargs)

Source: https://msal-python.readthedocs.io/en/latest/

Acquires a token using the on-behalf-of (OBO) flow. The current app is a middle-tier service that was called with a token representing an end user. It can use that token (a user assertion) to request another token to access a downstream web API on behalf of that user. Parameters include user_assertion (required), scopes (required), claims_challenge, and forwarded_client_claims.

```APIDOC
## acquire_token_on_behalf_of(user_assertion, scopes, claims_challenge=None, forwarded_client_claims=None, **kwargs)

### Description
Acquires a token using the on-behalf-of (OBO) flow. The current app is a middle-tier service which was called with a token representing an end user. The current app can use such token (a.k.a. a user assertion) to request another token to access downstream web API, on behalf of that user. See detail docs here: https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow

### Method
acquire_token_on_behalf_of

### Parameters
- **user_assertion** (str) - Required - The incoming token already received by this app.
- **scopes** (list[str]) - Required - Scopes required by downstream API (a resource).
- **claims_challenge** - Optional - 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.
- **forwarded_client_claims** (str) - Optional - A JSON string of client-originated claims to include in the token request. Unlike `claims_challenge` (server-issued, which bypasses the cache), tokens acquired with `forwarded_client_claims` are cached and keyed on the claims value. Send the same value on every request that should share the cached token; omitting or changing it routes to a different cache entry (a cache miss). The value is merged into the standard OAuth `claims` request parameter sent on the wire.

### Response
A dict representing the json response from Microsoft Entra:
- A successful response would contain "access_token" key,
- an error response would contain "error" and usually "error_description".
```

--------------------------------

### AuthorityBuilder usage

Source: https://msal-python.readthedocs.io/en/latest/

Shows how to use the AuthorityBuilder with predefined constants to construct an authority URL, and how to pass it to a PublicClientApplication. This is available since version 1.17.

```python
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, ...)
```

--------------------------------

### msal.Prompt constants

Source: https://msal-python.readthedocs.io/en/latest/

Defines constant strings for the prompt parameter, based on OpenID Connect Core 1.0.

```APIDOC
## msal.Prompt

### Description
This class defines the constant strings for prompt parameter. The values are based on https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest

### Constants
- **SELECT_ACCOUNT** = 'select_account'
- **NONE** = 'none'
- **CONSENT** = 'consent'
- **LOGIN** = 'login'
```

--------------------------------

### msal.SerializableTokenCache.add

Source: https://msal-python.readthedocs.io/en/latest/

Handle a token obtaining event, and add tokens into cache.

```APIDOC
## msal.SerializableTokenCache.add

### Description
Handle a token obtaining event, and add tokens into cache.

### Method
add

### Signature
add(_event_, _**kwargs_)

### Parameters
- **event** - The token obtaining event.
- **kwargs** - Additional keyword arguments.

### Returns
None
```

--------------------------------

### msal.TokenCache.add

Source: https://msal-python.readthedocs.io/en/latest/

Handles a token obtaining event and adds tokens into the cache.

```APIDOC
## msal.TokenCache.add

### Description
Handle a token obtaining event, and add tokens into cache.

### Method
add

### Signature
add(_event_, _now=None_)

### Parameters
- **event** - The token obtaining event.
- **now** (optional) - The current time.

### Returns
None
```

--------------------------------

### ManagedIdentityClient with retrying HTTP client

Source: https://msal-python.readthedocs.io/en/latest/

Shows how to create a ManagedIdentityClient using a requests.Session with exponential backoff retries for status codes 429, 500, 501, 502, 503, and 504.

```python
import msal, requests
from requests.adapters import HTTPAdapter, Retry
s = requests.Session()
retries = Retry(total=3, backoff_factor=0.1, status_forcelist=[
    429, 500, 501, 502, 503, 504])
s.mount('https://', HTTPAdapter(max_retries=retries))
managed_identity = ...
client = msal.ManagedIdentityClient(managed_identity, http_client=s)
```

--------------------------------

### UserAssignedManagedIdentity equivalent dicts

Source: https://msal-python.readthedocs.io/en/latest/

Shows the three possible dict representations of a UserAssignedManagedIdentity depending on the provided id (client_id, resource_id, or object_id).

```python
{"ManagedIdentityIdType": "ClientId", "Id": "foo"}
```

```python
{"ManagedIdentityIdType": "ResourceId", "Id": "foo"}
```

```python
{"ManagedIdentityIdType": "ObjectId", "Id": "foo"}
```

--------------------------------

### acquire_token_for_client(scopes, claims_challenge=None, fmi_path=None, forwarded_client_claims=None, **kwargs)

Source: https://msal-python.readthedocs.io/en/latest/

Acquires a token for the current confidential client, not for an end user. Since MSAL Python 1.23, it automatically looks for a token from cache and only sends a request to the Identity Provider when the cache misses. Parameters include scopes (required), claims_challenge, fmi_path, and forwarded_client_claims. Returns a dict with 'access_token' on success or 'error' and 'error_description' on failure.

```APIDOC
## acquire_token_for_client(scopes, claims_challenge=None, fmi_path=None, forwarded_client_claims=None, **kwargs)

### Description
Acquires a token for the current confidential client, not for an end user. Since MSAL Python 1.23, it automatically looks for a token from cache and only sends a request to the Identity Provider when the cache misses.

### Method
acquire_token_for_client

### Parameters
- **scopes** (list[str]) - Required - Scopes requested to access a protected API (a resource).
- **claims_challenge** - Optional - 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.
- **fmi_path** (str) - Optional - The Federated Managed Identity (FMI) credential path. When provided, it is sent as the `fmi_path` parameter in the token request body, and the resulting token is cached separately so that different FMI paths do not share cached tokens.
- **forwarded_client_claims** (str) - Optional - A JSON string of client-originated claims to include in the token request. Unlike `claims_challenge` (server-issued, which bypasses the cache), tokens acquired with `forwarded_client_claims` are cached and keyed on the claims value. Send the same value on every request that should share the cached token; omitting or changing it routes to a different cache entry (a cache miss). The value is merged into the standard OAuth `claims` request parameter sent on the wire.

### Request Example
```python
result = cca.acquire_token_for_client(
    scopes=["api://resource/.default"],
    fmi_path="SomeFmiPath/FmiCredentialPath",
)
```

### Response
A dict representing the json response from Microsoft Entra:
- A successful response would contain "access_token" key,
- an error response would contain "error" and usually "error_description".
```

--------------------------------

### Client Credential Configuration

Source: https://msal-python.readthedocs.io/en/latest/

Configuration options for the client_credential parameter in ConfidentialClientApplication, including private key, thumbprint, passphrase, and public certificate.

```APIDOC
## Client Credential Configuration

### Description
Configure the client_credential parameter for ConfidentialClientApplication to authenticate using certificates or client assertions.

### Parameters
#### client_credential (dict)
- **private_key** (str) - Required - PEM format private key.
- **thumbprint** (str) - Optional - SHA-1 thumbprint (deprecated). If absent and public_certificate is present, SHA-256 thumbprint is auto-calculated.
- **passphrase** (str) - Optional - Needed if private_key is encrypted.
- **public_certificate** (str) - Optional - Public key certificate for Subject Name/Issuer auth.
- **client_assertion** (str or callable) - Optional - Pre-signed JWT or callable returning a fresh assertion.
- **private_key_pfx_path** (str) - Optional - Path to PFX file.

### Example (Certificate)
```python
{
    "private_key": "...-----BEGIN PRIVATE KEY-----... in PEM format",
    "thumbprint": "A1B2C3D4E5F6...",
    "passphrase": "...",
    "public_certificate": "...-----BEGIN CERTIFICATE-----..."
}
```

### Example (Client Assertion)
```python
{
    "client_assertion": "...a JWT with claims aud, exp, iss, jti, nbf, and sub..."
}
```

### Example (PFX)
```python
{
    "private_key_pfx_path": "/path/to/your.pfx",
    "public_certificate": True,
    "passphrase": "..."
}
```

### Notes
- Use callable for client_assertion to avoid expiration issues.
- Wrap expensive callbacks with msal.AutoRefresher.
- Convert PFX to PEM using openssl if needed.
```

--------------------------------

### Client credential dict with PFX path

Source: https://msal-python.readthedocs.io/en/latest/

Feed a dictionary containing the path to a PFX file. This usage automatically uses SHA-256 thumbprint. Added in version 1.29.0. public_certificate is only needed for Subject Name/Issuer auth (since version 1.30.0).

```python
{
    "private_key_pfx_path": "/path/to/your.pfx",  # Added in version 1.29.0
    "public_certificate": True,  # Only needed if you use Subject Name/Issuer auth. Added in version 1.30.0
    "passphrase": "Passphrase if the private_key is encrypted (Optional)",
}
```
Tokens:
Raw