diff --git a/sdk/identity/azure-identity/README.md b/sdk/identity/azure-identity/README.md index eaf655f6ba33..c0db7c1c4e84 100644 --- a/sdk/identity/azure-identity/README.md +++ b/sdk/identity/azure-identity/README.md @@ -59,21 +59,7 @@ The Azure Identity library focuses on OAuth authentication with Microsoft Entra ### DefaultAzureCredential -`DefaultAzureCredential` is appropriate for most applications that will run in Azure because it combines common production credentials with development credentials. `DefaultAzureCredential` attempts to authenticate via the following mechanisms, in this order, stopping when one succeeds: - ->Note: `DefaultAzureCredential` is intended to simplify getting started with the library by handling common ->scenarios with reasonable default behaviors. Developers who want more control or whose scenario ->isn't served by the default settings should use other credential types. - -![DefaultAzureCredential authentication flow](https://raw.githubusercontent.com/Azure/azure-sdk-for-python/main/sdk/identity/azure-identity/images/mermaidjs/DefaultAzureCredentialAuthFlow.svg) - -1. **Environment** - `DefaultAzureCredential` reads account information specified via [environment variables](#environment-variables "environment variables") and uses it to authenticate. -1. **Workload Identity** - If the application is deployed to Azure Kubernetes Service with Managed Identity enabled, `DefaultAzureCredential` authenticates with it. -1. **Managed Identity** - If the application is deployed to an Azure host with Managed Identity enabled, `DefaultAzureCredential` authenticates with it. -1. **Azure CLI** - If a user signed in via the Azure CLI `az login` command, `DefaultAzureCredential` authenticates as that user. -1. **Azure PowerShell** - If a user signed in via Azure PowerShell's `Connect-AzAccount` command, `DefaultAzureCredential` authenticates as that user. -1. **Azure Developer CLI** - If the developer authenticated via the Azure Developer CLI `azd auth login` command, `DefaultAzureCredential` authenticates with that account. -1. **Interactive browser** - If enabled, `DefaultAzureCredential` interactively authenticates a user via the default browser. This credential type is disabled by default. +`DefaultAzureCredential` simplifies authentication while developing apps that deploy to Azure by combining credentials used in Azure hosting environments with credentials used in local development. For more information, see [DefaultAzureCredential overview][dac_overview]. #### Continuation policy @@ -118,7 +104,7 @@ DefaultAzureCredential(exclude_interactive_browser_credential=False) When enabled, `DefaultAzureCredential` falls back to interactively authenticating via the system's default web browser when no other credential is available. -#### Specify a user-assigned managed identity for `DefaultAzureCredential` +#### Specify a user-assigned managed identity with `DefaultAzureCredential` Many Azure hosts allow the assignment of a user-assigned managed identity. To configure `DefaultAzureCredential` to authenticate a user-assigned managed identity, use the `managed_identity_client_id` keyword argument: @@ -130,20 +116,7 @@ Alternatively, set the environment variable `AZURE_CLIENT_ID` to the identity's ### Define a custom authentication flow with `ChainedTokenCredential` -`DefaultAzureCredential` is generally the quickest way to get started developing applications for Azure. For more advanced scenarios, [ChainedTokenCredential][chain_cred_ref] links multiple credential instances to be tried sequentially when authenticating. It tries each credential in turn until one provides a token or fails to authenticate due to an error. - -The following example demonstrates creating a credential that first attempts to authenticate using managed identity. The credential falls back to authenticating via the Azure CLI when a managed identity is unavailable. This example uses the `EventHubProducerClient` from the [azure-eventhub][azure_eventhub] client library. - -```python -from azure.eventhub import EventHubProducerClient -from azure.identity import AzureCliCredential, ChainedTokenCredential, ManagedIdentityCredential - -managed_identity = ManagedIdentityCredential() -azure_cli = AzureCliCredential() -credential_chain = ChainedTokenCredential(managed_identity, azure_cli) - -client = EventHubProducerClient(namespace, eventhub_name, credential_chain) -``` +While `DefaultAzureCredential` is generally the quickest way to authenticate apps for Azure, you can create a customized chain of credentials to be considered. `ChainedTokenCredential` enables users to combine multiple credential instances to define a customized chain of credentials. For more information, see [ChainedTokenCredential overview][ctc_overview]. ### Async credentials @@ -395,6 +368,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope [cli_cred_ref]: https://aka.ms/azsdk/python/identity/azclicredential [client_assertion_cred_ref]: https://aka.ms/azsdk/python/identity/clientassertioncredential [client_secret_cred_ref]: https://aka.ms/azsdk/python/identity/clientsecretcredential +[ctc_overview]: https://aka.ms/azsdk/python/identity/credential-chains#chainedtokencredential-overview +[dac_overview]: https://aka.ms/azsdk/python/identity/credential-chains#defaultazurecredential-overview [default_cred_ref]: https://aka.ms/azsdk/python/identity/defaultazurecredential [device_code_cred_ref]: https://aka.ms/azsdk/python/identity/devicecodecredential [environment_cred_ref]: https://aka.ms/azsdk/python/identity/environmentcredential diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/chained.py b/sdk/identity/azure-identity/azure/identity/_credentials/chained.py index 31f38937f1d7..36f2e33d1f8c 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/chained.py +++ b/sdk/identity/azure-identity/azure/identity/_credentials/chained.py @@ -37,7 +37,8 @@ class ChainedTokenCredential: """A sequence of credentials that is itself a credential. Its :func:`get_token` method calls ``get_token`` on each credential in the sequence, in order, returning the first - valid token received. + valid token received. For more information, see + https://aka.ms/azsdk/python/identity/credential-chains#chainedtokencredential-overview. :param credentials: credential instances to form the chain :type credentials: ~azure.core.credentials.TokenCredential diff --git a/sdk/identity/azure-identity/azure/identity/_credentials/default.py b/sdk/identity/azure-identity/azure/identity/_credentials/default.py index 035efb52bd39..57676c233aed 100644 --- a/sdk/identity/azure-identity/azure/identity/_credentials/default.py +++ b/sdk/identity/azure-identity/azure/identity/_credentials/default.py @@ -24,7 +24,8 @@ class DefaultAzureCredential(ChainedTokenCredential): - """A default credential capable of handling most Azure SDK authentication scenarios. + """A credential capable of handling most Azure SDK authentication scenarios. See + https://aka.ms/azsdk/python/identity/credential-chains#usage-guidance-for-defaultazurecredential. The identity it uses depends on the environment. When an access token is needed, it requests one using these identities in turn, stopping when one provides a token: diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/chained.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/chained.py index 16ce23709dcc..6f45d33b1e48 100644 --- a/sdk/identity/azure-identity/azure/identity/aio/_credentials/chained.py +++ b/sdk/identity/azure-identity/azure/identity/aio/_credentials/chained.py @@ -21,7 +21,8 @@ class ChainedTokenCredential(AsyncContextManager): """A sequence of credentials that is itself a credential. Its :func:`get_token` method calls ``get_token`` on each credential in the sequence, in order, returning the first - valid token received. + valid token received. For more information, see + https://aka.ms/azsdk/python/identity/credential-chains#chainedtokencredential-overview. :param credentials: credential instances to form the chain :type credentials: ~azure.core.credentials.AsyncTokenCredential diff --git a/sdk/identity/azure-identity/azure/identity/aio/_credentials/default.py b/sdk/identity/azure-identity/azure/identity/aio/_credentials/default.py index fe1bc03b6084..7073a8e9d639 100644 --- a/sdk/identity/azure-identity/azure/identity/aio/_credentials/default.py +++ b/sdk/identity/azure-identity/azure/identity/aio/_credentials/default.py @@ -25,7 +25,8 @@ class DefaultAzureCredential(ChainedTokenCredential): - """A default credential capable of handling most Azure SDK authentication scenarios. + """A credential capable of handling most Azure SDK authentication scenarios. See + https://aka.ms/azsdk/python/identity/credential-chains#usage-guidance-for-defaultazurecredential. The identity it uses depends on the environment. When an access token is needed, it requests one using these identities in turn, stopping when one provides a token: