Propagate existing changes

python/docs-ref-autogen/msal/msal.application.ClientApplication.yml

@@ -56,10 +56,22 @@ constructor:
       : [], \"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   ````"
+      \ nbf, and sub...\"\n   }\n   ````\n\n\n\n## Supporting reading client cerficates\
+      \ from PFX files*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\",\n       \"passphrase\"\
+      : \"Passphrase if the private_key is encrypted (Optional. Added in version 1.6.0)\"\
+      ,\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\
+      \   ````"
     defaultValue: None
     types:
-    - <xref:typing.Union>[<xref:str>, <xref:dict>]
+    - <xref:typing.Union>[<xref:dict>, <xref:str>]
   - 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>\

python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml

@@ -56,10 +56,22 @@ constructor:
       : [], \"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   ````"
+      \ nbf, and sub...\"\n   }\n   ````\n\n\n\n## Supporting reading client cerficates\
+      \ from PFX files*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\",\n       \"passphrase\"\
+      : \"Passphrase if the private_key is encrypted (Optional. Added in version 1.6.0)\"\
+      ,\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\
+      \   ````"
     defaultValue: None
     types:
-    - <xref:typing.Union>[<xref:str>, <xref:dict>]
+    - <xref:typing.Union>[<xref:dict>, <xref:str>]
   - 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>\

python/docs-ref-autogen/msal/msal.managed_identity.ArcPlatformNotSupportedError.yml

@@ -0,0 +1,9 @@
+### YamlMime:PythonClass
+uid: msal.managed_identity.ArcPlatformNotSupportedError
+name: ArcPlatformNotSupportedError
+fullName: msal.managed_identity.ArcPlatformNotSupportedError
+module: msal.managed_identity
+inheritances:
+- msal.managed_identity.ManagedIdentityError
+constructor:
+  syntax: ArcPlatformNotSupportedError()

python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentity.yml

@@ -0,0 +1,55 @@
+### YamlMime:PythonClass
+uid: msal.managed_identity.ManagedIdentity
+name: ManagedIdentity
+fullName: msal.managed_identity.ManagedIdentity
+module: msal.managed_identity
+inheritances:
+- collections.UserDict
+summary: 'Feed an instance of this class to <xref:msal.ManagedIdentityClient>
+
+  to acquire token for the specified managed identity.'
+constructor:
+  syntax: ManagedIdentity(identifier=None, id_type=None)
+  parameters:
+  - name: identifier
+    defaultValue: None
+  - name: id_type
+    defaultValue: None
+methods:
+- uid: msal.managed_identity.ManagedIdentity.is_managed_identity
+  name: is_managed_identity
+  signature: is_managed_identity(unknown)
+  parameters:
+  - name: unknown
+    isRequired: true
+- uid: msal.managed_identity.ManagedIdentity.is_system_assigned
+  name: is_system_assigned
+  signature: is_system_assigned(unknown)
+  parameters:
+  - name: unknown
+    isRequired: true
+- uid: msal.managed_identity.ManagedIdentity.is_user_assigned
+  name: is_user_assigned
+  signature: is_user_assigned(unknown)
+  parameters:
+  - name: unknown
+    isRequired: true
+attributes:
+- uid: msal.managed_identity.ManagedIdentity.CLIENT_ID
+  name: CLIENT_ID
+  signature: CLIENT_ID = 'ClientId'
+- uid: msal.managed_identity.ManagedIdentity.ID
+  name: ID
+  signature: ID = 'Id'
+- uid: msal.managed_identity.ManagedIdentity.ID_TYPE
+  name: ID_TYPE
+  signature: ID_TYPE = 'ManagedIdentityIdType'
+- uid: msal.managed_identity.ManagedIdentity.OBJECT_ID
+  name: OBJECT_ID
+  signature: OBJECT_ID = 'ObjectId'
+- uid: msal.managed_identity.ManagedIdentity.RESOURCE_ID
+  name: RESOURCE_ID
+  signature: RESOURCE_ID = 'ResourceId'
+- uid: msal.managed_identity.ManagedIdentity.SYSTEM_ASSIGNED
+  name: SYSTEM_ASSIGNED
+  signature: SYSTEM_ASSIGNED = 'SystemAssigned'

python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityClient.yml

@@ -0,0 +1,93 @@
+### YamlMime:PythonClass
+uid: msal.managed_identity.ManagedIdentityClient
+name: ManagedIdentityClient
+fullName: msal.managed_identity.ManagedIdentityClient
+module: msal.managed_identity
+inheritances:
+- builtins.object
+summary: "This API encapsulates multiple managed identity back-ends:\nVM, App Service,\
+  \ Azure Automation (Runbooks), Azure Function, Service Fabric,\nand Azure Arc.\n\
+  \nIt also provides token cache support.\n\n> [!NOTE]\n> Cloud Shell support is NOT\
+  \ implemented in this class.\n>\n> Since MSAL Python 1.18 in May 2022, it has been\
+  \ implemented in\n>\n> <xref:PublicClientApplication.acquire_token_interactive>\
+  \ via calling pattern\n>\n> PublicClientApplication(...).acquire_token_interactive(scopes=[...],\
+  \ prompt=\"none\").\n>\n> That is appropriate, because Cloud Shell yields a token\
+  \ with\n>\n> delegated permissions for the end user who has signed in to the Azure\
+  \ Portal\n>\n> (like what a PublicClientApplication does),\n>\n> not a token with\
+  \ application permissions for an app.\n>\n\nCreate a managed identity client.\n\n\
+  Recipe 1: Hard code a managed identity for your app:\n\n<!-- literal_block {\"ids\"\
+  : [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\"\
+  : \"preserve\", \"language\": \"default\", \"force\": false, \"linenos\": false}\
+  \ -->\n\n````default\n\n   import msal, requests\n   client = msal.ManagedIdentityClient(\n\
+  \       msal.UserAssignedManagedIdentity(client_id=\"foo\"),\n       http_client=requests.Session(),\n\
+  \       )\n   token = client.acquire_token_for_client(\"resource\")\n   ````\n\n\
+  Recipe 2: Write once, run everywhere.\nIf you use different managed identity on\
+  \ different deployment,\nyou may use an environment variable (such as MY_MANAGED_IDENTITY_CONFIG)\n\
+  to store a json blob like\n`{\"ManagedIdentityIdType\": \"ClientId\", \"Id\": \"\
+  foo\"}` or\n`{\"ManagedIdentityIdType\": \"SystemAssignedManagedIdentity\", \"Id\"\
+  : null})`.\nThe following app can load managed identity configuration dynamically:\n\
+  \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
+  : [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\",\
+  \ \"force\": false, \"linenos\": false} -->\n\n````default\n\n   import json, os,\
+  \ msal, requests\n   config = os.getenv(\"MY_MANAGED_IDENTITY_CONFIG\")\n   assert\
+  \ config, \"An ENV VAR with value should exist\"\n   client = msal.ManagedIdentityClient(\n\
+  \       json.loads(config),\n       http_client=requests.Session(),\n       )\n\
+  \   token = client.acquire_token_for_client(\"resource\")\n   ````"
+constructor:
+  syntax: 'ManagedIdentityClient(managed_identity: dict | ManagedIdentity | SystemAssignedManagedIdentity
+    | UserAssignedManagedIdentity, *, http_client, token_cache=None, http_cache=None)'
+  parameters:
+  - name: managed_identity
+    description: 'It accepts an instance of <xref:msal.managed_identity.SystemAssignedManagedIdentity>
+
+      or <xref:msal.managed_identity.UserAssignedManagedIdentity>.
+
+      They are equivalent to a dict with a certain shape,
+
+      which may be loaded from a JSON configuration file or an env var.'
+    isRequired: true
+  - name: http_client
+    description: "An http client object. For example, you can use `requests.Session()`,\n\
+      optionally with exponential backoff behavior demonstrated in this recipe:\n\n\
+      <!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
+      : [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\"\
+      , \"force\": false, \"linenos\": false} -->\n\n````default\n\n   import msal,\
+      \ requests\n   from requests.adapters import HTTPAdapter, Retry\n   s = requests.Session()\n\
+      \   retries = Retry(total=3, backoff_factor=0.1, status_forcelist=[\n      \
+      \ 429, 500, 501, 502, 503, 504])\n   s.mount('https://', HTTPAdapter(max_retries=retries))\n\
+      \   managed_identity = ...\n   client = msal.ManagedIdentityClient(managed_identity,\
+      \ http_client=s)\n   ````"
+    isRequired: true
+  - name: token_cache
+    description: 'Optional. It accepts a <xref:msal.TokenCache> instance to store
+      tokens.
+
+      It will use an in-memory token cache by default.'
+    isRequired: true
+  - name: http_cache
+    description: 'Optional. It has the same characteristics as the
+
+      >>:paramref:`msal.ClientApplication.http_cache`<<.'
+    isRequired: true
+  keywordOnlyParameters:
+  - name: http_client
+    isRequired: true
+  - name: token_cache
+    isRequired: true
+  - name: http_cache
+    isRequired: true
+methods:
+- uid: msal.managed_identity.ManagedIdentityClient.acquire_token_for_client
+  name: acquire_token_for_client
+  summary: "Acquire token for the managed identity.\n\nThe result will be automatically\
+    \ cached.\nSubsequent calls will automatically search from cache first.\n\n> [!NOTE]\n\
+    > Known issue: When an Azure VM has only one user-assigned managed identity,\n\
+    >\n> and your app specifies to use system-assigned managed identity,\n>\n> Azure\
+    \ VM may still return a token for your user-assigned identity.\n>\n> \n>\n> This\
+    \ is a service-side behavior that cannot be changed by this library.\n>\n> [Azure\
+    \ VM docs](https://learn.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token#get-a-token-using-http)\n\
+    >"
+  signature: acquire_token_for_client(*, resource)
+  keywordOnlyParameters:
+  - name: resource
+    isRequired: true

python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityError.yml

@@ -0,0 +1,9 @@
+### YamlMime:PythonClass
+uid: msal.managed_identity.ManagedIdentityError
+name: ManagedIdentityError
+fullName: msal.managed_identity.ManagedIdentityError
+module: msal.managed_identity
+inheritances:
+- builtins.ValueError
+constructor:
+  syntax: ManagedIdentityError()

python/docs-ref-autogen/msal/msal.managed_identity.SystemAssignedManagedIdentity.yml

@@ -0,0 +1,18 @@
+### YamlMime:PythonClass
+uid: msal.managed_identity.SystemAssignedManagedIdentity
+name: SystemAssignedManagedIdentity
+fullName: msal.managed_identity.SystemAssignedManagedIdentity
+module: msal.managed_identity
+inheritances:
+- msal.managed_identity.ManagedIdentity
+summary: "Represent a system-assigned managed identity.\n\nIt is equivalent to a Python\
+  \ dict of:\n\n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"\
+  dupnames\": [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"\
+  default\", \"force\": false, \"linenos\": false} -->\n\n````default\n\n   {\"ManagedIdentityIdType\"\
+  : \"SystemAssigned\", \"Id\": None}\n   ````\n\nor a JSON blob of:\n\n<!-- literal_block\
+  \ {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\":\
+  \ [], \"xml:space\": \"preserve\", \"language\": \"default\", \"force\": false,\
+  \ \"linenos\": false} -->\n\n````default\n\n   {\"ManagedIdentityIdType\": \"SystemAssigned\"\
+  , \"Id\": null}\n   ````"
+constructor:
+  syntax: SystemAssignedManagedIdentity()

python/docs-ref-autogen/msal/msal.managed_identity.UserAssignedManagedIdentity.yml

@@ -0,0 +1,23 @@
+### YamlMime:PythonClass
+uid: msal.managed_identity.UserAssignedManagedIdentity
+name: UserAssignedManagedIdentity
+fullName: msal.managed_identity.UserAssignedManagedIdentity
+module: msal.managed_identity
+inheritances:
+- msal.managed_identity.ManagedIdentity
+summary: "Represent a user-assigned managed identity.\n\nDepends on the id you provided,\
+  \ the outcome is equivalent to one of the below:\n\n<!-- literal_block {\"ids\"\
+  : [], \"classes\": [], \"names\": [], \"dupnames\": [], \"backrefs\": [], \"xml:space\"\
+  : \"preserve\", \"language\": \"default\", \"force\": false, \"linenos\": false}\
+  \ -->\n\n````default\n\n   {\"ManagedIdentityIdType\": \"ClientId\", \"Id\": \"\
+  foo\"}\n   {\"ManagedIdentityIdType\": \"ResourceId\", \"Id\": \"foo\"}\n   {\"\
+  ManagedIdentityIdType\": \"ObjectId\", \"Id\": \"foo\"}\n   ````"
+constructor:
+  syntax: UserAssignedManagedIdentity(*, client_id=None, resource_id=None, object_id=None)
+  keywordOnlyParameters:
+  - name: client_id
+    isRequired: true
+  - name: resource_id
+    isRequired: true
+  - name: object_id
+    isRequired: true

python/docs-ref-autogen/msal/msal.managed_identity.yml

@@ -0,0 +1,23 @@
+### YamlMime:PythonModule
+uid: msal.managed_identity
+name: managed_identity
+fullName: msal.managed_identity
+functions:
+- uid: msal.managed_identity.get_managed_identity_source
+  name: get_managed_identity_source
+  summary: 'Detect the current environment and return the likely identity source.
+
+
+    When this function returns `CLOUD_SHELL`, you should use
+
+    <xref:msal.PublicClientApplication.acquire_token_interactive> with `prompt="none"`
+
+    to obtain a token.'
+  signature: get_managed_identity_source()
+classes:
+- msal.managed_identity.ArcPlatformNotSupportedError
+- msal.managed_identity.ManagedIdentity
+- msal.managed_identity.ManagedIdentityClient
+- msal.managed_identity.ManagedIdentityError
+- msal.managed_identity.SystemAssignedManagedIdentity
+- msal.managed_identity.UserAssignedManagedIdentity

python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml

@@ -11,9 +11,12 @@ summary: "This serialization can be a starting point to implement your own persi
   \n<!-- literal_block {\"ids\": [], \"classes\": [], \"names\": [], \"dupnames\"\
   : [], \"backrefs\": [], \"xml:space\": \"preserve\", \"language\": \"default\",\
   \ \"force\": false, \"linenos\": false} -->\n\n````default\n\n   import os, atexit,\
-  \ msal\n   cache = msal.SerializableTokenCache()\n   if os.path.exists(\"my_cache.bin\"\
-  ):\n       cache.deserialize(open(\"my_cache.bin\", \"r\").read())\n   atexit.register(lambda:\n\
-  \       open(\"my_cache.bin\", \"w\").write(cache.serialize())\n       # Hint: The\
+  \ msal\n   cache_filename = os.path.join(  # Persist cache into this file\n    \
+  \   os.getenv(\"XDG_RUNTIME_DIR\", \"\"),  # 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\n\
+  \       \"my_cache.bin\")\n   cache = msal.SerializableTokenCache()\n   if os.path.exists(cache_filename):\n\
+  \       cache.deserialize(open(cache_filename, \"r\").read())\n   atexit.register(lambda:\n\
+  \       open(cache_filename, \"w\").write(cache.serialize())\n       # Hint: The\
   \ following optional line persists only when state changed\n       if cache.has_state_changed\
   \ else None\n       )\n   app = msal.ClientApplication(..., token_cache=cache)\n\
   \   ...\n   ````"

python/docs-ref-autogen/msal/msal.token_cache.TokenCache.yml

@@ -27,6 +27,7 @@ methods:
     defaultValue: None
 - uid: msal.token_cache.TokenCache.find
   name: find
+  summary: Equivalent to list(search(...)).
   signature: find(credential_type, target=None, query=None)
   parameters:
   - name: credential_type
@@ -69,6 +70,22 @@ methods:
   parameters:
   - name: rt_item
     isRequired: true
+- uid: msal.token_cache.TokenCache.search
+  name: search
+  summary: 'Returns a generator of matching entries.
+
+
+    It is O(1) for AT hits, and O(n) for other types.
+
+    Note that it holds a lock during the entire search.'
+  signature: search(credential_type, target=None, query=None)
+  parameters:
+  - name: credential_type
+    isRequired: true
+  - name: target
+    defaultValue: None
+  - name: query
+    defaultValue: None
 - uid: msal.token_cache.TokenCache.update_rt
   name: update_rt
   signature: update_rt(rt_item, new_rt)

python/docs-ref-autogen/msal/msal.yml

@@ -6,4 +6,5 @@ type: rootImport
 modules:
 - msal.application
 - msal.auth_scheme
+- msal.managed_identity
 - msal.token_cache

python/docs-ref-autogen/toc.yml

@@ -17,6 +17,22 @@
     - name: PopAuthScheme
       uid: msal.auth_scheme.PopAuthScheme
     name: auth_scheme
+  - items:
+    - name: Overview
+      uid: msal.managed_identity
+    - name: ArcPlatformNotSupportedError
+      uid: msal.managed_identity.ArcPlatformNotSupportedError
+    - name: ManagedIdentity
+      uid: msal.managed_identity.ManagedIdentity
+    - name: ManagedIdentityClient
+      uid: msal.managed_identity.ManagedIdentityClient
+    - name: ManagedIdentityError
+      uid: msal.managed_identity.ManagedIdentityError
+    - name: SystemAssignedManagedIdentity
+      uid: msal.managed_identity.SystemAssignedManagedIdentity
+    - name: UserAssignedManagedIdentity
+      uid: msal.managed_identity.UserAssignedManagedIdentity
+    name: managed_identity
   - items:
     - name: Overview
       uid: msal.token_cache