diff --git a/python/docs-ref-autogen/msal/msal.application.ClientApplication.yml b/python/docs-ref-autogen/msal/msal.application.ClientApplication.yml index 6b70dee..8efa0bc 100644 --- a/python/docs-ref-autogen/msal/msal.application.ClientApplication.yml +++ b/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\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\n\n````default\n\ + \n openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem\n\ + \ ````" defaultValue: None types: - - [, ] + - [, ] - name: client_claims description: "*Added in version 0.5.0*:\nIt is a dictionary of extra claims that\ \ would be signed by\nby this \ diff --git a/python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml b/python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml index bac827a..61e7cbf 100644 --- a/python/docs-ref-autogen/msal/msal.application.ConfidentialClientApplication.yml +++ b/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\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\n\n````default\n\ + \n openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.pem\n\ + \ ````" defaultValue: None types: - - [, ] + - [, ] - name: client_claims description: "*Added in version 0.5.0*:\nIt is a dictionary of extra claims that\ \ would be signed by\nby this \ diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.ArcPlatformNotSupportedError.yml b/python/docs-ref-autogen/msal/msal.managed_identity.ArcPlatformNotSupportedError.yml new file mode 100644 index 0000000..08f4c51 --- /dev/null +++ b/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() diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentity.yml b/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentity.yml new file mode 100644 index 0000000..a33c5d4 --- /dev/null +++ b/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 + + 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' diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityClient.yml b/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityClient.yml new file mode 100644 index 0000000..50ca2c6 --- /dev/null +++ b/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> \ + \ 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\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\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 + + or . + + 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\ + \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 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 diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityError.yml b/python/docs-ref-autogen/msal/msal.managed_identity.ManagedIdentityError.yml new file mode 100644 index 0000000..f9ffbc8 --- /dev/null +++ b/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() diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.SystemAssignedManagedIdentity.yml b/python/docs-ref-autogen/msal/msal.managed_identity.SystemAssignedManagedIdentity.yml new file mode 100644 index 0000000..54aa706 --- /dev/null +++ b/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\n\n````default\n\n {\"ManagedIdentityIdType\"\ + : \"SystemAssigned\", \"Id\": None}\n ````\n\nor a JSON blob of:\n\n\n\n````default\n\n {\"ManagedIdentityIdType\": \"SystemAssigned\"\ + , \"Id\": null}\n ````" +constructor: + syntax: SystemAssignedManagedIdentity() diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.UserAssignedManagedIdentity.yml b/python/docs-ref-autogen/msal/msal.managed_identity.UserAssignedManagedIdentity.yml new file mode 100644 index 0000000..97947a9 --- /dev/null +++ b/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\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 diff --git a/python/docs-ref-autogen/msal/msal.managed_identity.yml b/python/docs-ref-autogen/msal/msal.managed_identity.yml new file mode 100644 index 0000000..4ca6913 --- /dev/null +++ b/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 + + 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 diff --git a/python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml b/python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml index 704d424..34990d1 100644 --- a/python/docs-ref-autogen/msal/msal.token_cache.SerializableTokenCache.yml +++ b/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\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 ````" diff --git a/python/docs-ref-autogen/msal/msal.token_cache.TokenCache.yml b/python/docs-ref-autogen/msal/msal.token_cache.TokenCache.yml index 8f906db..444f212 100644 --- a/python/docs-ref-autogen/msal/msal.token_cache.TokenCache.yml +++ b/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) diff --git a/python/docs-ref-autogen/msal/msal.yml b/python/docs-ref-autogen/msal/msal.yml index a496341..7bed890 100644 --- a/python/docs-ref-autogen/msal/msal.yml +++ b/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 diff --git a/python/docs-ref-autogen/toc.yml b/python/docs-ref-autogen/toc.yml index 9a7b04f..ef1d824 100644 --- a/python/docs-ref-autogen/toc.yml +++ b/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