msal.application.ClientApplication.yml

### YamlMime:PythonClass
uid: msal.application.ClientApplication
name: ClientApplication
fullName: msal.application.ClientApplication
module: msal.application
summary: 'You do not usually directly use this class. Use its subclasses instead:

  <xref:msal.application.PublicClientApplication> and <xref:msal.application.ConfidentialClientApplication>.


  Create an instance of application.'
constructor:
  syntax: 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:
  - name: client_id
    description: Your app has a client_id after you register it on Microsoft Entra
      admin center.
    isRequired: true
    types:
    - <xref:str>
  - name: client_credential
    description: "For <xref:msal.application.PublicClientApplication>, you use *None*\
      \ here.\n\nFor <xref:msal.application.ConfidentialClientApplication>,\nit supports\
      \ many different input formats for different scenarios.\n\n\n\n## Support using\
      \ a client secret.Just feed in a string, such as `\"your client secret\"`.\n\
      \n\n\n## Support using a certificate in X.509 (.pem) formatDeprecated because\
      \ it uses SHA-1 thumbprint,\nunless you are still using ADFS which supports\
      \ SHA-1 thumbprint only.\nPlease use the .pfx option documented later in this\
      \ page.Feed in a dict in this form:\n\n<!-- literal_block {\"ids\": [], \"classes\"\
      : [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\"\
      , \"language\": \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\
      \n   {\n       \"private_key\": \"...-----BEGIN PRIVATE KEY-----... in PEM format\"\
      ,\n       \"thumbprint\": \"An SHA-1 thumbprint such as A1B2C3D4E5F6...\"\n\
      \           \"Changed in version 1.35.0, if thumbprint is absent\"\n       \
      \    \"and a public_certificate is present, MSAL will\"\n           \"automatically\
      \ calculate an SHA-256 thumbprint instead.\",\n       \"passphrase\": \"Needed\
      \ if the private_key is encrypted (Added in version 1.6.0)\",\n       \"public_certificate\"\
      : \"...-----BEGIN CERTIFICATE-----...\",  # Needed if you use Subject Name/Issuer\
      \ auth. Added in version 0.5.0.\n   }\n   ````\n\nMSAL Python requires a \"\
      private_key\" in PEM format.\nIf your cert is in PKCS12 (.pfx) format,\nyou\
      \ can convert it to X.509 (.pem) format,\nby `openssl pkcs12 -in file.pfx -out\
      \ file.pem -nodes`.The thumbprint is available in your app's registration in\
      \ Azure Portal.\nAlternatively, you can [calculate the thumbprint](https://github.com/Azure/azure-sdk-for-python/blob/07d10639d7e47f4852eaeb74aef5d569db499d6e/sdk/identity/azure-identity/azure/identity/_credentials/certificate.py#L94-L97).`public_certificate`\
      \ (optional) is public key certificate\nwhich will be sent through 'x5c' JWT\
      \ header.\nThis is useful when you use [Subject Name/Issuer Authentication](https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60)\n\
      which is an approach to allow easier certificate rotation.\nPer [specs](https://tools.ietf.org/html/rfc7515#section-4.1.6),\n\
      \"the certificate containing\nthe public key corresponding to the key used to\
      \ digitally sign the\nJWS MUST be the first certificate.  This MAY be followed\
      \ by\nadditional certificates, with each subsequent certificate being the\n\
      one used to certify the previous one.\"\nHowever, your certificate's issuer\
      \ may use a different order.\nSo, if your attempt ends up with an error AADSTS700027\
      \ -\n\"The provided signature value did not match the expected signature value\"\
      ,\nyou may try use only the leaf cert (in PEM/str format) instead.\n\n\n\n##\
      \ Supporting raw assertion obtained from elsewhere*Added in version 1.13.0*:\n\
      It can also be a completely pre-signed assertion that you've assembled yourself.\n\
      Simply pass a container containing only the key \"client_assertion\", like this:\n\
      \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
      : [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
      , \"force\": false, \"linenos\": false} -->\n\n````default\n\n   {\n       \"\
      client_assertion\": \"...a JWT with claims aud, exp, iss, jti, nbf, and sub...\"\
      \n   }\n   ````\n\n\n\n## Supporting reading client certificates from PFX filesThis\
      \ usage will automatically use SHA-256 thumbprint of the certificate.*Added\
      \ in version 1.29.0*:\nFeed in a dictionary containing the path to a PFX file:\n\
      \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
      : [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
      , \"force\": false, \"linenos\": false} -->\n\n````default\n\n   {\n       \"\
      private_key_pfx_path\": \"/path/to/your.pfx\",  # Added in version 1.29.0\n\
      \       \"public_certificate\": True,  # Only needed if you use Subject Name/Issuer\
      \ auth. Added in version 1.30.0\n       \"passphrase\": \"Passphrase if the\
      \ private_key is encrypted (Optional)\",\n   }\n   ````\n\nThe following command\
      \ will generate a .pfx file from your .key and .pem file:\n\n<!-- literal_block\
      \ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
      : [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
      \ \"linenos\": false} -->\n\n````default\n\n   openssl pkcs12 -export -out certificate.pfx\
      \ -inkey privateKey.key -in certificate.pem\n   ````\n\n[Subject Name/Issuer\
      \ Auth](https://github.com/AzureAD/microsoft-authentication-library-for-python/issues/60)\n\
      is an approach to allow easier certificate rotation.\nIf your .pfx file contains\
      \ both the private key and public cert,\nyou can opt in for Subject Name/Issuer\
      \ Auth by setting \"public_certificate\" to `True`."
    defaultValue: None
    types:
    - <xref:typing.Union>[<xref:dict>, <xref:str>, <xref:None>]
  - name: client_claims
    description: "*Added in version 0.5.0*:\nIt is a dictionary of extra claims that\
      \ would be signed by\nby this <xref:msal.application.ConfidentialClientApplication>\
      \ 's private key.\nFor example, you can use {\"client_ip\": \"x.x.x.x\"}.\n\
      You may also override any of the following default claims:\n\n<!-- literal_block\
      \ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
      : [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
      \ \"linenos\": false} -->\n\n````default\n\n   {\n       \"aud\": the_token_endpoint,\n\
      \       \"iss\": self.client_id,\n       \"sub\": same_as_issuer,\n       \"\
      exp\": now + 10_min,\n       \"iat\": now,\n       \"jti\": a_random_uuid\n\
      \   }\n   ````"
    defaultValue: None
    types:
    - <xref:dict>
  - name: authority
    description: "A URL that identifies a token authority. It should be of the format\n\
      `https://login.microsoftonline.com/your_tenant`\nBy default, we will use `https://login.microsoftonline.com/common`\n\
      \n*Changed in version 1.17*: you can also use predefined constant\nand a builder\
      \ like this:\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\"\
      : [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\"\
      : \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\n\
      \   from msal.authority import (\n       AuthorityBuilder,\n       AZURE_US_GOVERNMENT,\
      \ AZURE_CHINA, AZURE_PUBLIC)\n   my_authority = AuthorityBuilder(AZURE_PUBLIC,\
      \ \"contoso.onmicrosoft.com\")\n   # Now you get an equivalent of\n   # \"https://login.microsoftonline.com/contoso.onmicrosoft.com\"\
      \n\n   # You can feed such an authority to msal's ClientApplication\n   from\
      \ msal import PublicClientApplication\n   app = PublicClientApplication(\"my_client_id\"\
      , authority=my_authority, ...)\n   ````"
    defaultValue: None
    types:
    - <xref:str>
  - name: validate_authority
    description: '(optional) Turns authority validation

      on or off. This parameter default to true.'
    defaultValue: 'True'
    types:
    - <xref:bool>
  - name: token_cache
    description: 'Sets the token cache used by this ClientApplication instance.

      By default, an in-memory cache will be created and used.'
    defaultValue: None
    types:
    - <xref:msal.token_cache.TokenCache>
  - name: http_client
    description: '(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.'
    defaultValue: None
  - name: verify
    description: '(optional)

      It will be passed to the

      [verify parameter in the underlying requests library](http://docs.python-requests.org/en/v2.9.1/user/advanced/#ssl-cert-verification)

      This does not apply if you have chosen to pass your own Http client'
    defaultValue: 'True'
  - name: proxies
    description: '(optional)

      It will be passed to the

      [proxies parameter in the underlying requests library](http://docs.python-requests.org/en/v2.9.1/user/advanced/#proxies)

      This does not apply if you have chosen to pass your own Http client'
    defaultValue: None
  - name: timeout
    description: '(optional)

      It will be passed to the

      [timeout parameter in the underlying requests library](http://docs.python-requests.org/en/v2.9.1/user/advanced/#timeouts)

      This does not apply if you have chosen to pass your own Http client'
    defaultValue: None
  - name: app_name
    description: '(optional)

      You can provide your application name for Microsoft telemetry purposes.

      Default value is None, means it will not be passed to Microsoft.'
    defaultValue: None
  - name: app_version
    description: '(optional)

      You can provide your application version for Microsoft telemetry purposes.

      Default value is None, means it will not be passed to Microsoft.'
    defaultValue: None
  - name: client_capabilities
    description: '(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)](https://learn.microsoft.com/entra/identity/conditional-access/concept-continuous-access-evaluation)

      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](https://openid.net/specs/openid-connect-core-1_0-final.html#ClaimsParameter)

      which you will later provide via one of the acquire-token request.'
    defaultValue: None
    types:
    - <xref:list>[<xref:str>]
  - name: azure_region
    description: "(optional)\nInstructs MSAL to use the Entra regional token service.\
      \ This legacy feature is only available to\nfirst-party applications. Only `acquire_token_for_client()`\
      \ is supported.\n\nSupports 4 values:\n\n1. `azure_region=None` - This default\
      \ value means no region is configured. MSAL will use the region defined in env\
      \ var `MSAL_FORCE_REGION`. \n\n2. `azure_region=\"some_region\"` - meaning the\
      \ specified region is used. \n\n3. `azure_region=True` - meaning MSAL will try\
      \ to auto-detect the region. This is not recommended. \n\n4. `azure_region=False`\
      \ - meaning MSAL will use no region. \n\n\n> [!NOTE]\n> Region auto-discovery\
      \ has been tested on VMs and on Azure Functions. It is unreliable.\n>\n> Applications\
      \ using this option should configure a short timeout.\n>\n> \n>\n> For more\
      \ details and for the values of the region string\n>\n> \n>\n> see [https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting](https://learn.microsoft.com/entra/msal/dotnet/resources/region-discovery-troubleshooting)\n\
      >\n\nNew in version 1.12.0."
    defaultValue: None
    types:
    - <xref:str>
  - name: exclude_scopes
    description: '(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"]`.'
    defaultValue: None
    types:
    - <xref:list>[<xref:str>]
  - name: http_cache
    description: "MSAL has long been caching tokens in the `token_cache`.\nRecently,\
      \ MSAL also introduced a concept of `http_cache`,\nby automatically caching\
      \ some finite amount of non-token http responses,\nso that *long-lived*\n`PublicClientApplication`\
      \ and `ConfidentialClientApplication`\nwould be more performant and responsive\
      \ in some situations.\n\nThis `http_cache` parameter accepts any dict-like object.\n\
      If not provided, MSAL will use an in-memory dict.\n\nIf your app is a command-line\
      \ app (CLI),\nyou would want to persist your http_cache across different CLI\
      \ runs.\nThe persisted file's format may change due to, but not limited to,\n\
      [unstable protocol](https://docs.python.org/3/library/pickle.html#data-stream-format),\n\
      so your implementation shall tolerate unexpected loading errors.\nThe following\
      \ recipe shows a way to do so:\n\n<!-- literal_block {\"ids\": [], \"classes\"\
      : [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\"\
      , \"language\": \"default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\
      \n   # Just add the following lines at the beginning of your CLI script\n  \
      \ import sys, atexit, pickle, logging\n   http_cache_filename = sys.argv[0]\
      \ + \".http_cache\"\n   try:\n       with open(http_cache_filename, \"rb\")\
      \ as f:\n           persisted_http_cache = pickle.load(f)  # Take a snapshot\n\
      \   except (\n           FileNotFoundError,  # Or IOError in Python 2\n    \
      \       pickle.UnpicklingError,  # A corrupted http cache file\n           AttributeError,\
      \  # Cache created by a different version of MSAL\n           ):\n       persisted_http_cache\
      \ = {}  # Recover by starting afresh\n   except:  # Unexpected exceptions\n\
      \       logging.exception(\"You may want to debug this\")\n       persisted_http_cache\
      \ = {}  # Recover by starting afresh\n   atexit.register(lambda: pickle.dump(\n\
      \       # When exit, flush it back to the file.\n       # It may occasionally\
      \ overwrite another process's concurrent write,\n       # but that is fine.\
      \ Subsequent runs will reach eventual consistency.\n       persisted_http_cache,\
      \ open(http_cache_file, \"wb\")))\n\n   # And then you can implement your app\
      \ as you normally would\n   app = msal.PublicClientApplication(\n       \"your_client_id\"\
      ,\n       ...,\n       http_cache=persisted_http_cache,  # Utilize persisted_http_cache\n\
      \       ...,\n       #token_cache=...,  # You may combine the old token_cache\
      \ trick\n           # Please refer to token_cache recipe at\n           # https://msal-python.readthedocs.io/en/latest/#msal.SerializableTokenCache\n\
      \       )\n   app.acquire_token_interactive([\"your\", \"scope\"], ...)\n  \
      \ ````\n\nContent inside `http_cache` are cheap to obtain.\nThere is no need\
      \ to share them among different apps.\n\nContent inside `http_cache` will contain\
      \ no tokens nor\nPersonally Identifiable Information (PII). Encryption is unnecessary.\n\
      \nNew in version 1.16.0."
    defaultValue: None
    types:
    - <xref:dict>
  - name: instance_discovery
    description: "Historically, MSAL would connect to a central endpoint located at\n\
      `https://login.microsoftonline.com` to acquire some metadata,\nespecially when\
      \ using an unfamiliar authority.\nThis behavior is known as Instance Discovery.\n\
      \nThis parameter defaults to None, which enables the Instance Discovery.\n\n\
      If you know some authorities which you allow MSAL to operate with as-is,\nwithout\
      \ involving any Instance Discovery, the recommended pattern is:\n\n<!-- literal_block\
      \ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
      : [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
      \ \"linenos\": false} -->\n\n````default\n\n   known_authorities = frozenset([\
      \  # Treat your known authorities as const\n       \"https://contoso.com/adfs\"\
      , \"https://login.azs/foo\"])\n   ...\n   authority = \"https://contoso.com/adfs\"\
      \  # Assuming your app will use this\n   app1 = PublicClientApplication(\n \
      \      \"client_id\",\n       authority=authority,\n       # Conditionally disable\
      \ Instance Discovery for known authorities\n       instance_discovery=authority\
      \ not in known_authorities,\n       )\n   ````\n\nIf you do not know some authorities\
      \ beforehand,\nyet still want MSAL to accept any authority that you will provide,\n\
      you can use a `False` to unconditionally disable Instance Discovery.\n\nNew\
      \ in version 1.19.0."
    defaultValue: None
    types:
    - <xref:boolean>
  - name: allow_broker
    description: Deprecated. Please use `enable_broker_on_windows` instead.
    defaultValue: None
    types:
    - <xref:boolean>
  - name: enable_pii_log
    description: '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.'
    defaultValue: None
    types:
    - <xref:boolean>
  - name: oidc_authority
    description: '*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.'
    defaultValue: None
    types:
    - <xref:str>
methods:
- uid: msal.application.ClientApplication.acquire_token_by_auth_code_flow
  name: acquire_token_by_auth_code_flow
  summary: 'Validate the auth response being redirected back, and obtain tokens.


    It automatically provides nonce protection.'
  signature: acquire_token_by_auth_code_flow(auth_code_flow, auth_response, scopes=None,
    **kwargs)
  parameters:
  - name: auth_code_flow
    description: The same dict returned by <xref:msal.application.ClientApplication.initiate_auth_code_flow>.
    isRequired: true
    types:
    - <xref:dict>
  - name: auth_response
    description: A dict of the query string received from auth server.
    isRequired: true
    types:
    - <xref:dict>
  - name: scopes
    description: '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

      <xref:msal.application.ClientApplication.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.'
    defaultValue: None
    types:
    - <xref:list>[<xref:str>]
  return:
    description: "* 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](https://tools.ietf.org/html/rfc6749#section-5.1))\
      \ \n\n* A dict containing \"error\", optionally \"error_description\", \"error_uri\"\
      . (It is either [this](https://tools.ietf.org/html/rfc6749#section-4.1.2.1)\
      \ or [that](https://tools.ietf.org/html/rfc6749#section-5.2)) \n\n* Most client-side\
      \ data error would result in ValueError exception. So the usage pattern could\
      \ be without any protocol details: \n\n  <!-- literal_block {\"ids\": [], \"\
      classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\"\
      : \"preserve\", \"language\": \"default\", \"force\": false, \"linenos\": false}\
      \ -->\n\n  ````default\n\n     def authorize():  # A controller in a web app\n\
      \         try:\n             result = msal_app.acquire_token_by_auth_code_flow(\n\
      \                 session.get(\"flow\", {}), request.args)\n             if\
      \ \"error\" in result:\n                 return render_template(\"error.html\"\
      , result)\n             use(result)  # Token(s) are available in result and\
      \ cache\n         except ValueError:  # Usually caused by CSRF\n           \
      \  pass  # Simply ignore them\n         return redirect(url_for(\"index\"))\n\
      \     ````"
- uid: msal.application.ClientApplication.acquire_token_by_authorization_code
  name: acquire_token_by_authorization_code
  summary: The second half of the Authorization Code Grant.
  signature: acquire_token_by_authorization_code(code, scopes, redirect_uri=None,
    nonce=None, claims_challenge=None, **kwargs)
  parameters:
  - name: code
    description: The authorization code returned from Authorization Server.
    isRequired: true
  - name: scopes
    description: '(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.'
    isRequired: true
    types:
    - <xref:list>[<xref:str>]
  - name: nonce
    description: 'If you provided a nonce when calling <xref:msal.application.ClientApplication.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.'
    defaultValue: None
  - name: claims_challenge
    description: '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.'
    defaultValue: None
  - name: redirect_uri
    defaultValue: None
  return:
    description: "A dict representing the json response from Microsoft Entra:\n\n\
      * A successful response would contain \"access_token\" key, \n\n* an error response\
      \ would contain \"error\" and usually \"error_description\"."
- uid: msal.application.ClientApplication.acquire_token_by_refresh_token
  name: acquire_token_by_refresh_token
  summary: '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 <xref:msal.application.ClientApplication.acquire_token_silent>.'
  signature: acquire_token_by_refresh_token(refresh_token, scopes, **kwargs)
  parameters:
  - name: refresh_token
    description: The old refresh token, as a string.
    isRequired: true
    types:
    - <xref:str>
  - name: scopes
    description: 'The scopes associate with this old RT.

      Each scope needs to be in the Microsoft identity platform (v2) format.

      See [Scopes not resources](https://docs.microsoft.com/en-us/azure/active-directory/develop/migrate-python-adal-msal#scopes-not-resources).'
    isRequired: true
    types:
    - <xref:list>
  return:
    description: "* A dict contains \"error\" and some other keys, when error happened.\
      \ \n\n* A dict contains no \"error\" key means migration was successful."
- uid: msal.application.ClientApplication.acquire_token_by_username_password
  name: acquire_token_by_username_password
  summary: '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](https://github.com/AzureAD/microsoft-authentication-library-for-python/wiki/Username-Password-Authentication)


    [Deprecated] This API is deprecated for public client flows and will be

    removed in a future release. Use a more secure flow instead.

    Migration guide: [https://aka.ms/msal-ropc-migration](https://aka.ms/msal-ropc-migration)'
  signature: acquire_token_by_username_password(username, password, scopes, claims_challenge=None,
    auth_scheme=None, **kwargs)
  parameters:
  - name: username
    description: Typically a UPN in the form of an email address.
    isRequired: true
    types:
    - <xref:str>
  - name: password
    description: The password.
    isRequired: true
    types:
    - <xref:str>
  - name: scopes
    description: Scopes requested to access a protected API (a resource).
    isRequired: true
    types:
    - <xref:list>[<xref:str>]
  - name: claims_challenge
    description: '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.'
    defaultValue: None
  - name: auth_scheme
    description: '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.'
    defaultValue: None
    types:
    - <xref:object>
  return:
    description: "A dict representing the json response from Microsoft Entra:\n\n\
      * A successful response would contain \"access_token\" key, \n\n* an error response\
      \ would contain \"error\" and usually \"error_description\"."
- uid: msal.application.ClientApplication.acquire_token_silent
  name: acquire_token_silent
  summary: 'Acquire an access token for given account, without user interaction.


    It has same parameters as the <xref:msal.application.ClientApplication.acquire_token_silent_with_error>.

    The difference is the behavior of the return value.

    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.'
  signature: acquire_token_silent(scopes, account, authority=None, force_refresh=False,
    claims_challenge=None, auth_scheme=None, **kwargs)
  parameters:
  - name: scopes
    isRequired: true
  - name: account
    isRequired: true
  - name: authority
    defaultValue: None
  - name: force_refresh
    defaultValue: 'False'
  - name: claims_challenge
    defaultValue: None
  - name: auth_scheme
    defaultValue: None
  return:
    description: "* A dict containing no \"error\" key, and typically contains an\
      \ \"access_token\" key, if cache lookup succeeded. \n\n* None when cache lookup\
      \ does not yield a token."
- uid: msal.application.ClientApplication.acquire_token_silent_with_error
  name: acquire_token_silent_with_error
  summary: '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 <xref:msal.application.ClientApplication.acquire_token_silent>
    is recommended.'
  signature: acquire_token_silent_with_error(scopes, account, authority=None, force_refresh=False,
    claims_challenge=None, auth_scheme=None, **kwargs)
  parameters:
  - name: scopes
    description: '(Required)

      Scopes requested to access a protected API (a resource).'
    isRequired: true
    types:
    - <xref:list>[<xref:str>]
  - name: account
    description: '(Required)

      One of the account object returned by <xref:msal.application.ClientApplication.get_accounts>.

      Starting from MSAL Python 1.23,

      a `None` input will become a NO-OP and always return `None`.'
    isRequired: true
  - name: force_refresh
    description: 'If True, it will skip Access Token look-up,

      and try to find a Refresh Token to obtain a new Access Token.'
    defaultValue: 'False'
  - name: claims_challenge
    description: '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.'
    defaultValue: None
  - name: auth_scheme
    description: '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.'
    defaultValue: None
    types:
    - <xref:object>
  - name: authority
    defaultValue: None
  return:
    description: "* A dict containing no \"error\" key, and typically contains an\
      \ \"access_token\" key, if cache lookup succeeded. \n\n* None when there is\
      \ simply no token in the cache. \n\n* A dict containing an \"error\" key, when\
      \ token refresh failed."
- uid: msal.application.ClientApplication.get_accounts
  name: get_accounts
  summary: 'Get a list of accounts which previously signed in, i.e. exists in cache.


    An account can later be used in <xref:msal.application.ClientApplication.acquire_token_silent>

    to find its tokens.'
  signature: get_accounts(username=None)
  parameters:
  - name: username
    description: Filter accounts with this username only. Case insensitive.
    defaultValue: None
  return:
    description: '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.'
- uid: msal.application.ClientApplication.get_authorization_request_url
  name: get_authorization_request_url
  summary: Constructs a URL for you to start a Authorization Code Grant.
  signature: 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:
  - name: scopes
    description: '(Required)

      Scopes requested to access a protected API (a resource).'
    isRequired: true
    types:
    - <xref:list>[<xref:str>]
  - name: state
    description: Recommended by OAuth2 for CSRF protection.
    defaultValue: None
    types:
    - <xref:str>
  - name: login_hint
    description: Identifier of the user. Generally a User Principal Name (UPN).
    defaultValue: None
    types:
    - <xref:str>
  - name: redirect_uri
    description: Address to return to upon receiving a response from the authority.
    defaultValue: None
    types:
    - <xref:str>
  - name: response_type
    description: '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](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-implicit-grant-flow#is-the-implicit-grant-suitable-for-my-app).'
    defaultValue: code
    types:
    - <xref:str>
  - name: prompt
    description: '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

      <xref:msal.Prompt>.'
    defaultValue: None
    types:
    - <xref:str>
  - name: nonce
    description: 'A cryptographically random value used to mitigate replay attacks.
      See also

      [OIDC specs](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest).'
    defaultValue: None
  - name: domain_hint
    description: '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](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code)
      and

      [domain_hint doc](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-oapx/86fb452d-e34a-494e-ac61-e526e263b6d8).'
    defaultValue: None
  - name: claims_challenge
    description: '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.'
    defaultValue: None
  return:
    description: The authorization url as a string.
- uid: msal.application.ClientApplication.initiate_auth_code_flow
  name: initiate_auth_code_flow
  summary: 'Initiate an auth code flow.


    Later when the response reaches your redirect_uri,

    you can use <xref:msal.application.ClientApplication.acquire_token_by_auth_code_flow>

    to complete the authentication/authorization.'
  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:
  - name: scopes
    description: It is a list of case-sensitive strings.
    isRequired: true
    types:
    - <xref:list>
  - name: redirect_uri
    description: Optional. If not specified, server will use the pre-registered one.
    defaultValue: None
    types:
    - <xref:str>
  - name: state
    description: 'An opaque value used by the client to

      maintain state between the request and callback.

      If absent, this library will automatically generate one internally.'
    defaultValue: None
    types:
    - <xref:str>
  - name: prompt
    description: '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

      <xref:msal.Prompt>.'
    defaultValue: None
    types:
    - <xref:str>
  - name: login_hint
    description: Optional. Identifier of the user. Generally a User Principal Name
      (UPN).
    defaultValue: None
    types:
    - <xref:str>
  - name: domain_hint
    description: '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](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code)
      and

      [domain_hint doc](https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-oapx/86fb452d-e34a-494e-ac61-e526e263b6d8).'
    defaultValue: None
  - name: max_age
    description: '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.'
    defaultValue: None
    types:
    - <xref:int>
  - name: response_mode
    description: 'OPTIONAL. Specifies the method with which response parameters should
      be returned.

      The default value is equivalent to `query`, which was 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>*



      > [!NOTE]

      > You should configure your web framework to accept form_post responses instead
      of query responses.

      >

      > While this parameter still works, it will be removed in a future version.

      >

      > Using query-based response modes is less secure and should be avoided.

      >'
    defaultValue: None
    types:
    - <xref:str>
  - name: claims_challenge
    defaultValue: None
  return:
    description: "The auth code flow. It is a dict in this form:\n\n<!-- literal_block\
      \ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\"\
      : [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
      \ \"linenos\": false} -->\n\n````default\n\n   {\n       \"auth_uri\": \"https://...\"\
      ,  // Guide user to visit this\n       \"state\": \"...\",  // You may choose\
      \ to verify it by yourself,\n                        // or just let acquire_token_by_auth_code_flow()\n\
      \                        // do that for you.\n       \"...\": \"...\",  // Everything\
      \ else are reserved and internal\n   }\n   ````\n\nThe caller is expected to:\n\
      \n1. somehow store this content, typically inside the current session, \n\n\
      2. guide the end user (i.e. resource owner) to visit that auth_uri, \n\n3. and\
      \ then relay this dict and subsequent auth response to <xref:msal.application.ClientApplication.acquire_token_by_auth_code_flow>."
- uid: msal.application.ClientApplication.is_pop_supported
  name: is_pop_supported
  summary: Returns True if this client supports Proof-of-Possession Access Token.
  signature: is_pop_supported()
- uid: msal.application.ClientApplication.remove_account
  name: remove_account
  summary: Sign me out and forget me from token cache
  signature: remove_account(account)
  parameters:
  - name: account
    isRequired: true
attributes:
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID
  name: ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID
  signature: ACQUIRE_TOKEN_BY_AUTHORIZATION_CODE_ID = '832'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID
  name: ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID
  signature: ACQUIRE_TOKEN_BY_DEVICE_FLOW_ID = '622'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_REFRESH_TOKEN
  name: ACQUIRE_TOKEN_BY_REFRESH_TOKEN
  signature: ACQUIRE_TOKEN_BY_REFRESH_TOKEN = '85'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID
  name: ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID
  signature: ACQUIRE_TOKEN_BY_USERNAME_PASSWORD_ID = '301'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_FOR_CLIENT_ID
  name: ACQUIRE_TOKEN_FOR_CLIENT_ID
  signature: ACQUIRE_TOKEN_FOR_CLIENT_ID = '730'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_INTERACTIVE
  name: ACQUIRE_TOKEN_INTERACTIVE
  signature: ACQUIRE_TOKEN_INTERACTIVE = '169'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_ON_BEHALF_OF_ID
  name: ACQUIRE_TOKEN_ON_BEHALF_OF_ID
  signature: ACQUIRE_TOKEN_ON_BEHALF_OF_ID = '523'
- uid: msal.application.ClientApplication.ACQUIRE_TOKEN_SILENT_ID
  name: ACQUIRE_TOKEN_SILENT_ID
  signature: ACQUIRE_TOKEN_SILENT_ID = '84'
- uid: msal.application.ClientApplication.ATTEMPT_REGION_DISCOVERY
  name: ATTEMPT_REGION_DISCOVERY
  signature: ATTEMPT_REGION_DISCOVERY = True
- uid: msal.application.ClientApplication.DISABLE_MSAL_FORCE_REGION
  name: DISABLE_MSAL_FORCE_REGION
  signature: DISABLE_MSAL_FORCE_REGION = False
- uid: msal.application.ClientApplication.GET_ACCOUNTS_ID
  name: GET_ACCOUNTS_ID
  signature: GET_ACCOUNTS_ID = '902'
- uid: msal.application.ClientApplication.REMOVE_ACCOUNT_ID
  name: REMOVE_ACCOUNT_ID
  signature: REMOVE_ACCOUNT_ID = '903'