From e7270e182ef7537f032011eb6e19124352f78e5a Mon Sep 17 00:00:00 2001 From: Charles Lowell Date: Mon, 7 Oct 2019 13:48:43 -0700 Subject: [PATCH] Update docs for Identity Preview 4 (#7659) --- sdk/identity/azure-identity/HISTORY.md | 7 +++--- sdk/identity/azure-identity/README.md | 10 ++++---- .../_credentials/authorization_code.py | 4 ++-- .../azure/identity/_credentials/browser.py | 10 ++++---- .../_credentials/client_credential.py | 8 +++---- .../identity/_credentials/environment.py | 4 ++++ .../azure/identity/_credentials/user.py | 24 +++++++++---------- .../aio/_credentials/authorization_code.py | 23 +++++++++++------- .../aio/_credentials/client_credential.py | 8 +++---- .../azure/identity/aio/_credentials/user.py | 4 ++-- 10 files changed, 57 insertions(+), 45 deletions(-) diff --git a/sdk/identity/azure-identity/HISTORY.md b/sdk/identity/azure-identity/HISTORY.md index 9e5226d3431c..b16b0f2ccd54 100644 --- a/sdk/identity/azure-identity/HISTORY.md +++ b/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) diff --git a/sdk/identity/azure-identity/README.md b/sdk/identity/azure-identity/README.md index fbcbc9a71116..c03769cacea8 100644 --- a/sdk/identity/azure-identity/README.md +++ b/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=, 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=, 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=, 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). diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/authorization_code.py b/sdk/identity/azure-identity/azure/identity/_credentials/authorization_code.py index 82a23634b2fb..0252a3639915 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/authorization_code.py +++ b/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): diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/browser.py b/sdk/identity/azure-identity/azure/identity/_credentials/browser.py index cad67642c9b7..53bbd0d0fbe1 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/browser.py +++ b/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). """ diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/client_credential.py b/sdk/identity/azure-identity/azure/identity/_credentials/client_credential.py index d3afd2dff697..da93198238be 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/client_credential.py +++ b/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): diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/environment.py b/sdk/identity/azure-identity/azure/identity/_credentials/environment.py index b56822377e25..b46498d77e22 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/environment.py +++ b/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` diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/user.py b/sdk/identity/azure-identity/azure/identity/_credentials/user.py index ef966fa40f61..0078c077b8ab 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/user.py +++ b/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. """ 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 index 0ef0f0d0d969..e1c2d70d13ef 100644 --- a/sdk/identity/azure-identity/azure/identity/aio/_credentials/authorization_code.py +++ b/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: diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_credential.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_credential.py index 5ff081ad211d..bebda5e4c0f5 100644 --- a/sdk/identity/azure-identity/azure/identity/aio/_credentials/client_credential.py +++ b/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: diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/user.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/user.py index f1edc37a2632..d616524cb128 100644 --- a/sdk/identity/azure-identity/azure/identity/aio/_credentials/user.py +++ b/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: