Update docs for Identity Preview 4 (#7659)

sdk/identity/azure-identity/HISTORY.md

@@ -1,6 +1,6 @@
 # Release History
 
-## 1.0.0b4
+## 1.0.0b4 (2019-10-07)
 ### New features:
 - `AuthorizationCodeCredential` authenticates with a previously obtained
 authorization code. See Azure Active Directory's
@@ -22,8 +22,9 @@ Government would use `KnownAuthorities.AZURE_GOVERNMENT` instead:
 
 ### Fixes and improvements:
 - `UsernamePasswordCredential` correctly handles environment configuration with
-no tenant information (#7260)
-- user realm discovery requests are sent through credential pipelines (#7260)
+no tenant information ([#7260](https://github.com/Azure/azure-sdk-for-python/pull/7260))
+- user realm discovery requests are sent through credential pipelines
+([#7260](https://github.com/Azure/azure-sdk-for-python/pull/7260))
 
 
 ## 1.0.0b3 (2019-09-10)

sdk/identity/azure-identity/README.md

@@ -144,7 +144,7 @@ from azure.storage.blob import BlobServiceClient
 # If environment configuration is incomplete, it will try managed identity.
 credential = DefaultAzureCredential()
 
-client = BlobServiceClient(account_url=<your storage account url>, credential=credential)
+client = BlobServiceClient(account_url, credential=credential)
 ```
 Executing this on a development machine requires first
 [configuring the environment][#environment-variables] with appropriate values
@@ -160,7 +160,7 @@ from azure.keyvault.keys import KeyClient
 
 credential = ClientSecretCredential(client_id, client_secret, tenant_id)
 
-client = KeyClient(vault_url=<your vault url>, credential=credential)
+client = KeyClient(vault_endpoint, credential)
 ```
 
 ## Authenticating a service principal with a certificate:
@@ -175,7 +175,7 @@ from azure.keyvault.secrets import SecretClient
 cert_path = "/app/certs/certificate.pem"
 credential = CertificateCredential(client_id, tenant_id, cert_path)
 
-client = SecretClient(vault_url=<your vault url>, credential=credential)
+client = SecretClient(vault_endpoint, credential)
 ```
 
 ## Chaining credentials:
@@ -210,7 +210,7 @@ for more information.
 This example demonstrates authenticating the asynchronous `SecretClient` from
 [`azure-keyvault-secrets`][azure_keyvault_secrets] with asynchronous credentials.
 ```py
-# all credentials have async equivalents supported on Python 3.5.3+
+# most credentials have async equivalents supported on Python 3.5.3+
 from azure.identity.aio import DefaultAzureCredential
 
 default_credential = DefaultAzureCredential()
@@ -233,7 +233,7 @@ to authenticate. `ClientAuthenticationError` has a `message` attribute which
 describes why authentication failed. When raised by `ChainedTokenCredential`,
 the message collects error messages from each credential in the chain.
 
-For more details on dealing with Azure Active Directory errors please refer to the
+For more details on handling Azure Active Directory errors please refer to the
 Azure Active Directory
 [error code documentation](https://docs.microsoft.com/en-us/azure/active-directory/develop/reference-aadsts-error-codes).
 

sdk/identity/azure-identity/azure/identity/_credentials/authorization_code.py

@@ -27,8 +27,8 @@ class AuthorizationCodeCredential(object):
 
     Keyword arguments
         - **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.KnownAuthorities` defines
-            authorities for other clouds.
+          authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities` defines
+          authorities for other clouds.
     """
 
     def __init__(self, client_id, tenant_id, authorization_code, redirect_uri, client_secret=None, **kwargs):

sdk/identity/azure-identity/azure/identity/_credentials/browser.py

@@ -33,12 +33,12 @@ class InteractiveBrowserCredential(PublicClientCredential):
     :param str client_id: the application's client ID
 
     Keyword arguments
-        - *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.KnownAuthorities` defines
-            authorities for other clouds.
-        - *tenant (str)*: a tenant ID or a domain associated with a tenant. Defaults to the 'organizations' tenant,
+        - **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.KnownAuthorities` defines
+          authorities for other clouds.
+        - **tenant (str)**: a tenant ID or a domain associated with a tenant. Defaults to the 'organizations' tenant,
           which can authenticate work or school accounts.
-        - *timeout (int)*: seconds to wait for the user to complete authentication. Defaults to 300 (5 minutes).
+        - **timeout (int)**: seconds to wait for the user to complete authentication. Defaults to 300 (5 minutes).
 
     """
 

sdk/identity/azure-identity/azure/identity/_credentials/client_credential.py

@@ -26,8 +26,8 @@ class ClientSecretCredential(ClientSecretCredentialBase):
 
     Keyword arguments
         - **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.KnownAuthorities` defines
-            authorities for other clouds.
+          authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities` defines
+          authorities for other clouds.
     """
 
     def __init__(self, client_id, secret, tenant_id, **kwargs):
@@ -61,8 +61,8 @@ class CertificateCredential(CertificateCredentialBase):
 
     Keyword arguments
         - **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.KnownAuthorities` defines
-            authorities for other clouds.
+          authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities` defines
+          authorities for other clouds.
     """
 
     def __init__(self, client_id, tenant_id, certificate_path, **kwargs):

sdk/identity/azure-identity/azure/identity/_credentials/environment.py

@@ -42,6 +42,9 @@ class EnvironmentCredential:
       - **AZURE_CLIENT_ID**: the application's client ID
       - **AZURE_USERNAME**: a username (usually an email address)
       - **AZURE_PASSWORD**: that user's password
+      - **AZURE_TENANT_ID**: (optional) ID of the service principal's tenant. Also called its 'directory' ID.
+        If not provided, defaults to the 'organizations' tenant, which supports only Azure Active Directory work or
+        school accounts.
     """
 
     def __init__(self, **kwargs):
@@ -75,6 +78,7 @@ def get_token(self, *scopes, **kwargs):  # pylint:disable=unused-argument
         # type: (*str, **Any) -> AccessToken
         """
         Request an access token for `scopes`.
+
         :param str scopes: desired scopes for the token
         :rtype: :class:`azure.core.credentials.AccessToken`
         :raises: :class:`azure.core.exceptions.ClientAuthenticationError`

sdk/identity/azure-identity/azure/identity/_credentials/user.py

@@ -46,13 +46,13 @@ class DeviceCodeCredential(PublicClientCredential):
         If not provided, the credential will print instructions to stdout.
 
     Keyword arguments
-        - *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.KnownAuthorities` defines
-            authorities for other clouds.
-        - *tenant (str)* - tenant ID or a domain associated with a tenant. If not provided, defaults to the
+        - **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.KnownAuthorities` defines
+          authorities for other clouds.
+        - **tenant (str)** - tenant ID or a domain associated with a tenant. If not provided, defaults to the
           'organizations' tenant, which supports only Azure Active Directory work or school accounts.
-        - *timeout (int)* - seconds to wait for the user to authenticate. Defaults to the validity period of the device
-          code as set by Azure Active Directory, which also prevails when ``timeout`` is longer.
+        - **timeout (int)** - seconds to wait for the user to authenticate. Defaults to the validity period of the
+          device code as set by Azure Active Directory, which also prevails when ``timeout`` is longer.
 
     """
 
@@ -117,8 +117,8 @@ class SharedTokenCacheCredential(object):
 
     Keyword arguments
         - **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.KnownAuthorities` defines
-            authorities for other clouds.
+          authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities` defines
+          authorities for other clouds.
     """
 
     def __init__(self, username, **kwargs):  # pylint:disable=unused-argument
@@ -193,10 +193,10 @@ class UsernamePasswordCredential(PublicClientCredential):
     :param str password: the user's password
 
     Keyword arguments
-        - *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.KnownAuthorities` defines
-            authorities for other clouds.
-        - *tenant (str)* - tenant ID or a domain associated with a tenant. If not provided, defaults to the
+        - **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.KnownAuthorities` defines
+          authorities for other clouds.
+        - **tenant (str)** - tenant ID or a domain associated with a tenant. If not provided, defaults to the
           'organizations' tenant, which supports only Azure Active Directory work or school accounts.
 
     """

sdk/identity/azure-identity/azure/identity/aio/_credentials/authorization_code.py

@@ -28,12 +28,19 @@ class AuthorizationCodeCredential(object):
 
     Keyword arguments
         - **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.KnownAuthorities` defines
-            authorities for other clouds.
+          authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities` defines
+          authorities for other clouds.
     """
 
-    def __init__(self, client_id, tenant_id, authorization_code, redirect_uri, client_secret=None, **kwargs):
-        # type: (str, str, str, str, Optional[str], **Any) -> None
+    def __init__(
+        self,
+        client_id: str,
+        tenant_id: str,
+        authorization_code: str,
+        redirect_uri: str,
+        client_secret: "Optional[str]" = None,
+        **kwargs: "Any"
+    ) -> None:
         self._authorization_code = authorization_code  # type: Optional[str]
         self._client_id = client_id
         self._client_secret = client_secret
@@ -50,10 +57,10 @@ async def get_token(self, *scopes: str, **kwargs: "Any") -> "AccessToken":
         :rtype: :class:`azure.core.credentials.AccessToken`
         :raises: :class:`azure.core.exceptions.ClientAuthenticationError`
 
-        Keyword arguments:
-            - **executor**: (optional) a :class:`concurrent.futures.Executor` used to execute asynchronous calls
-            - **loop**: (optional) an event loop on which to schedule network I/O. If not provided, the currently
-                running loop will be used.
+        **Keyword arguments:**
+          - **executor** - (optional) a :class:`concurrent.futures.Executor` used to execute asynchronous calls
+          - **loop** - (optional) an event loop on which to schedule network I/O. If not provided, the currently running
+            loop will be used.
         """
 
         if self._authorization_code:

sdk/identity/azure-identity/azure/identity/aio/_credentials/client_credential.py

@@ -22,8 +22,8 @@ class ClientSecretCredential(ClientSecretCredentialBase):
 
     Keyword arguments
         - **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.KnownAuthorities` defines
-            authorities for other clouds.
+          authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities` defines
+          authorities for other clouds.
     """
 
     def __init__(self, client_id: str, secret: str, tenant_id: str, **kwargs: "Mapping[str, Any]") -> None:
@@ -55,8 +55,8 @@ class CertificateCredential(CertificateCredentialBase):
 
     Keyword arguments
         - **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.KnownAuthorities` defines
-            authorities for other clouds.
+          authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities` defines
+          authorities for other clouds.
     """
 
     def __init__(self, client_id: str, tenant_id: str, certificate_path: str, **kwargs: "Mapping[str, Any]") -> None:

sdk/identity/azure-identity/azure/identity/aio/_credentials/user.py

@@ -39,8 +39,8 @@ async def get_token(self, *scopes: str, **kwargs: "Any") -> "AccessToken":  # py
 
         Keyword arguments
             - **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.KnownAuthorities`
-                defines authorities for other clouds.
+              the authority for Azure Public Cloud (which is the default). :class:`~azure.identity.KnownAuthorities`
+              defines authorities for other clouds.
         """
 
         if not self._client: