update docs (#26301)

xiangyan99 · Scott Schaab · web-flow · commit 9cf809d72d41 · 2022-09-19T13:55:28.000-07:00
* update docs

* update

* Update sdk/identity/azure-identity/azure/identity/_credentials/on_behalf_of.py

Co-authored-by: Scott Schaab &lt;sschaab@microsoft.com&gt;

* Update sdk/identity/azure-identity/azure/identity/_credentials/client_secret.py

Co-authored-by: Scott Schaab &lt;sschaab@microsoft.com&gt;

* Update sdk/identity/azure-identity/azure/identity/_credentials/certificate.py

Co-authored-by: Scott Schaab &lt;sschaab@microsoft.com&gt;

* updates

* updates

Co-authored-by: Scott Schaab &lt;sschaab@microsoft.com&gt;
diff --git a/sdk/identity/azure-identity/BREAKING_CHANGES.md b/sdk/identity/azure-identity/BREAKING_CHANGES.md
@@ -0,0 +1,23 @@
+# Breaking Changes
+
+## 1.11.0
+
+### Behavioral change to credential types supporting multi-tenant authentication
+
+As of `azure-identity` 1.11.0, the default behavior of credentials supporting multi-tenant authentication has changed. Each of these credentials will throw an `ClientAuthenticationError` if the requested `tenant_id` doesn't match the tenant ID originally configured on the credential. Apps must now do one of the following things:
+
+- Add all IDs, of tenants from which tokens should be acquired, to the `additionally_allowed_tenants` list in the credential options. For example:
+
+```py
+credential = DefaultAzureCredential(additionally_allowed_tenants = ["<tenant_id_1>", "<tenant_id_2>"])
+```
+
+- Add `*` to enable token acquisition from any tenant. This is the original behavior and is compatible with previous versions supporting multi tenant authentication. For example:
+
+```py
+credential = DefaultAzureCredential(additionally_allowed_tenants=['*'])
+```
+
+Note: Credential types which do not require a `tenant_id` on construction will only throw `ClientAuthenticationError` when the application has provided a value for `tenant_id` in the constructor. If no `tenant_id` is specified when constructing the credential, the credential will acquire tokens for any requested `tenant_id` regardless of the value of `additionally_allowed_tenants`.
+
+More information on this change and the consideration behind it can be found [here](https://aka.ms/azsdk/blog/multi-tenant-guidance).
diff --git a/sdk/identity/azure-identity/CHANGELOG.md b/sdk/identity/azure-identity/CHANGELOG.md
@@ -1,6 +1,6 @@
 # Release History
 
-## 1.11.0 (2022-09-20)
+## 1.11.0 (2022-09-19)
 
 ### Features Added
 
@@ -16,6 +16,18 @@
   - `UsernamePasswordCredential`
   - `VisualStudioCodeCredential`
 
+### Breaking Changes
+
+- Credential types supporting multi-tenant authentication will now throw `ClientAuthenticationError` if the requested tenant ID doesn't match the credential's tenant ID, and is not included in `additionally_allowed_tenants`. Applications must now explicitly add additional tenants to the `additionally_allowed_tenants` list, or add '*' to list, to enable acquiring tokens from tenants other than the originally specified tenant ID.
+
+More information on this change and the consideration behind it can be found [here](https://aka.ms/azsdk/blog/multi-tenant-guidance).
+
+- These beta features in 1.11.0b3 have been removed from this release and will be added back in 1.12.0b1
+  - `tenant_id` for `AzureCliCredential`
+  - removed `VisualStudioCodeCredential` from `DefaultAzureCredential` token chain
+  - `AZURE_CLIENT_CERTIFICATE_PASSWORD` support for `EnvironmentCredential`
+  - `validate_authority` support
+
 ## 1.11.0b3 (2022-08-09)
 
 Azure-identity is supported on Python 3.7 or later. For more details, please read our page on [Azure SDK for Python version support policy](https://github.com/Azure/azure-sdk-for-python/wiki/Azure-SDKs-Python-version-support-policy).
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/authorization_code.py b/sdk/identity/azure-identity/azure/identity/_credentials/authorization_code.py
@@ -30,9 +30,9 @@ class AuthorizationCodeCredential(GetTokenMixin):
         the authority for Azure Public Cloud (which is the default). :class:`~azure.identity.AzureAuthorityHosts`
         defines authorities for other clouds.
     :keyword str client_secret: One of the application's client secrets. Required only for web apps and web APIs.
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to attempt to acquire tokens
-        for any tenant.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(self, tenant_id, client_id, authorization_code, redirect_uri, **kwargs):
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/azure_cli.py b/sdk/identity/azure-identity/azure/identity/_credentials/azure_cli.py
@@ -36,9 +36,6 @@ class AzureCliCredential(object):
 
     This requires previously logging in to Azure via "az login", and will use the CLI's currently logged in identity.
 
-    :keyword List[str] additionally_allowed_tenants: optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
     """
     def __init__(self, *, additionally_allowed_tenants: List[str] = None):
 
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/azure_powershell.py b/sdk/identity/azure-identity/azure/identity/_credentials/azure_powershell.py
@@ -52,9 +52,6 @@ class AzurePowerShellCredential(object):
 
     This requires previously logging in to Azure via "Connect-AzAccount", and will use the currently logged in identity.
 
-    :keyword List[str] additionally_allowed_tenants: optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
     """
     def __init__(self, *, additionally_allowed_tenants: List[str] = None):
 
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/certificate.py b/sdk/identity/azure-identity/azure/identity/_credentials/certificate.py
@@ -45,9 +45,9 @@ class CertificateCredential(ClientCredentialBase):
     :keyword cache_persistence_options: Configuration for persistent token caching. If unspecified, the credential
         will cache tokens in memory.
     :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(self, tenant_id, client_id, certificate_path=None, **kwargs):
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/client_assertion.py b/sdk/identity/azure-identity/azure/identity/_credentials/client_assertion.py
@@ -29,9 +29,9 @@ def __init__(self, tenant_id, client_id, func, **kwargs):
         :keyword str authority: Authority of an Azure Active Directory endpoint, for example
             "login.microsoftonline.com", the authority for Azure Public Cloud (which is the default).
             :class:`~azure.identity.AzureAuthorityHosts` defines authorities for other clouds.
-        :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-            may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-            any tenant the application is installed.
+        :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+            for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+            acquire tokens for any tenant the application can access.
         """
         self._func = func
         self._client = AadClient(tenant_id, client_id, **kwargs)
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/client_secret.py b/sdk/identity/azure-identity/azure/identity/_credentials/client_secret.py
@@ -24,9 +24,9 @@ class ClientSecretCredential(ClientCredentialBase):
     :keyword cache_persistence_options: Configuration for persistent token caching. If unspecified, the credential
         will cache tokens in memory.
     :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(self, tenant_id, client_id, client_secret, **kwargs):
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/on_behalf_of.py b/sdk/identity/azure-identity/azure/identity/_credentials/on_behalf_of.py
@@ -48,9 +48,9 @@ class OnBehalfOfCredential(MsalCredential, GetTokenMixin):
         is a unicode string, it will be encoded as UTF-8. If the certificate requires a different encoding, pass
         appropriately encoded bytes instead.
     :paramtype password: str or bytes
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(self, tenant_id, client_id, **kwargs):
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/user_password.py b/sdk/identity/azure-identity/azure/identity/_credentials/user_password.py
@@ -37,9 +37,9 @@ class UsernamePasswordCredential(InteractiveCredential):
     :keyword cache_persistence_options: Configuration for persistent token caching. If unspecified, the credential
         will cache tokens in memory.
     :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(self, client_id, username, password, **kwargs):
diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/vscode.py b/sdk/identity/azure-identity/azure/identity/_credentials/vscode.py
@@ -121,9 +121,9 @@ class VisualStudioCodeCredential(_VSCodeCredentialBase, GetTokenMixin):
     :keyword str tenant_id: ID of the tenant the credential should authenticate in. Defaults to the "Azure: Tenant"
         setting in VS Code's user settings or, when that setting has no value, the "organizations" tenant, which
         supports only Azure Active Directory work or school accounts.
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __enter__(self):
diff --git a/sdk/identity/azure-identity/azure/identity/_internal/__init__.py b/sdk/identity/azure-identity/azure/identity/_internal/__init__.py
@@ -84,7 +84,7 @@ def resolve_tenant(
         return default_tenant
     if not default_tenant:
         return tenant_id
-    if additionally_allowed_tenants == ['*'] or tenant_id in additionally_allowed_tenants:
+    if '*' in additionally_allowed_tenants or tenant_id in additionally_allowed_tenants:
         _LOGGER.info("A token was requested for a different tenant than was configured on the credential, "
                      "and the requested tenant ID was used to authenticate. Configured tenant ID: %s, "
                      "Requested tenant ID %s", default_tenant, tenant_id)
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/authorization_code.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/authorization_code.py
@@ -30,9 +30,9 @@ class AuthorizationCodeCredential(AsyncContextManager, GetTokenMixin):
         the authority for Azure Public Cloud (which is the default). :class:`~azure.identity.AzureAuthorityHosts`
         defines authorities for other clouds.
     :keyword str client_secret: One of the application's client secrets. Required only for web apps and web APIs.
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     async def __aenter__(self):
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/azure_cli.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/azure_cli.py
@@ -32,9 +32,6 @@ class AzureCliCredential(AsyncContextManager):
 
     This requires previously logging in to Azure via "az login", and will use the CLI's currently logged in identity.
 
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
     """
 
     def __init__(self, *, additionally_allowed_tenants: List[str] = None):
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/azure_powershell.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/azure_powershell.py
@@ -29,9 +29,6 @@ class AzurePowerShellCredential(AsyncContextManager):
 
     This requires previously logging in to Azure via "Connect-AzAccount", and will use the currently logged in identity.
 
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
     """
 
     def __init__(self, *, additionally_allowed_tenants: List[str] = None):
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/certificate.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/certificate.py
@@ -42,9 +42,9 @@ class CertificateCredential(AsyncContextManager, GetTokenMixin):
     :keyword cache_persistence_options: Configuration for persistent token caching. If unspecified, the credential
           will cache tokens in memory.
     :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(self, tenant_id, client_id, certificate_path=None, **kwargs):
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_assertion.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_assertion.py
@@ -28,9 +28,9 @@ def __init__(self, tenant_id: str, client_id: str, func: "Callable[[], str]", **
         :keyword str authority: Authority of an Azure Active Directory endpoint, for example
             "login.microsoftonline.com", the authority for Azure Public Cloud (which is the default).
             :class:`~azure.identity.AzureAuthorityHosts` defines authorities for other clouds.
-        :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-            may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-            any tenant the application is installed.
+        :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+            for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+            acquire tokens for any tenant the application can access.
         """
         self._func = func
         self._client = AadClient(tenant_id, client_id, **kwargs)
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_secret.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_secret.py
@@ -31,9 +31,9 @@ class ClientSecretCredential(AsyncContextManager, GetTokenMixin):
     :keyword cache_persistence_options: Configuration for persistent token caching. If unspecified, the credential
           will cache tokens in memory.
     :paramtype cache_persistence_options: ~azure.identity.TokenCachePersistenceOptions
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(self, tenant_id: str, client_id: str, client_secret: str, **kwargs: "Any") -> None:
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/on_behalf_of.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/on_behalf_of.py
@@ -45,9 +45,9 @@ class OnBehalfOfCredential(AsyncContextManager, GetTokenMixin):
         is a unicode string, it will be encoded as UTF-8. If the certificate requires a different encoding, pass
         appropriately encoded bytes instead.
     :paramtype password: str or bytes
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     def __init__(
diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/vscode.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/vscode.py
@@ -27,9 +27,9 @@ class VisualStudioCodeCredential(_VSCodeCredentialBase, AsyncContextManager, Get
     :keyword str tenant_id: ID of the tenant the credential should authenticate in. Defaults to the "Azure: Tenant"
         setting in VS Code's user settings or, when that setting has no value, the "organizations" tenant, which
         supports only Azure Active Directory work or school accounts.
-    :keyword List[str] additionally_allowed_tenants: Optional additional tenant ids for which the credential
-        may acquire tokens. Add the wildcard value "*" to allow the credential to acquire tokens for
-        any tenant the application is installed.
+    :keyword List[str] additionally_allowed_tenants: Specifies tenants in addition to the specified "tenant_id"
+        for which the credential may acquire tokens. Add the wildcard value "*" to allow the credential to
+        acquire tokens for any tenant the application can access.
     """
 
     async def __aenter__(self) -> "VisualStudioCodeCredential":
