From 270bb517d8c567ecd699b372e4d5b700f188ebce Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Fri, 20 Dec 2024 17:49:38 -0800 Subject: [PATCH 01/17] Initial pass --- sdk/identity/azure_identity/README.md | 477 ++++++++++++++++++++++---- 1 file changed, 410 insertions(+), 67 deletions(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index 32911a5248..c91937be83 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -1,77 +1,420 @@ -# azure_identity - -Azure Identity crate for the unofficial Microsoft Azure SDK for Rust. This crate is part of a collection of crates: for more information please refer to . - -This crate provides several implementations of the [azure_core::auth::TokenCredential](https://docs.rs/azure_core/latest/azure_core/auth/trait.TokenCredential.html) trait. -It is recommended to start with `azure_identity::create_credential()?`, which will create an instance of `DefaultAzureCredential` by default. If you want to use a specific credential type, the `AZURE_CREDENTIAL_KIND` environment variable may be set to a value from `azure_credential_kinds`, such as `azurecli` or `virtualmachine`. - -```rust,no_run -use azure_core::credentials::TokenCredential; -use std::sync::Arc; - -#[tokio::main] -async fn main() -> Result<(), Box> { - let subscription_id = - std::env::var("AZURE_SUBSCRIPTION_ID").expect("AZURE_SUBSCRIPTION_ID required"); - - let credential: Arc = azure_identity::DefaultAzureCredential::new()?; - - // Let's enumerate the Azure storage accounts in the subscription using the REST API directly. - // This is just an example. It is easier to use the Azure SDK for Rust crates. - let url = url::Url::parse(&format!("https://management.azure.com/subscriptions/{subscription_id}/providers/Microsoft.Storage/storageAccounts?api-version=2019-06-01"))?; - - let access_token = credential - .get_token(&["https://management.azure.com/.default"]) - .await?; - - let response = reqwest::Client::new() - .get(url) - .header( - "Authorization", - format!("Bearer {}", access_token.token.secret()), - ) - .send() - .await? - .text() - .await?; - - println!("{response}"); - Ok(()) -} +# Azure Identity client library for Rust + +The Azure Identity library provides [Microsoft Entra ID](https://learn.microsoft.com/entra/fundamentals/whatis) ([formerly Azure Active Directory](https://learn.microsoft.com/entra/fundamentals/new-name)) token authentication support across the Azure SDK. It provides a set of [`TokenCredential`](https://learn.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet) implementations that can be used to construct Azure SDK clients that support Microsoft Entra token authentication. + +[Source code][source] | [Package (crates.io)][package] | [API reference documentation][identity_api_docs] | [Microsoft Entra ID documentation][entraid_doc] + +## Getting started + +### Install the package + +Install the Azure Identity library for Rust with cargo: + +```bash + cargo add azure_identity ``` -## Design +### Prerequisites + +* An [Azure subscription][azure_sub]. +* The [Azure CLI][azure_cli] can also be useful for authenticating in a development environment, creating accounts, and managing account roles. + +### Authenticate during local development + +When debugging and executing code locally, it's typical for developers to use their own accounts for authenticating calls to Azure services. The Azure Identity library supports authenticating through developer tools to simplify local development. + +#### Authenticate via the Azure CLI + +`DefaultAzureCredential` and `AzureCliCredential` can authenticate as the user signed in to the [Azure CLI][azure_cli]. To sign in to the Azure CLI, run `az login`. On a system with a default web browser, the Azure CLI launches the browser to authenticate a user. + +When no default browser is available, `az login` uses the device code authentication flow. This flow can also be selected manually by running `az login --use-device-code`. + +#### Authenticate via the Azure Developer CLI + +Developers coding outside of an IDE can also use the [Azure Developer CLI][azure_developer_cli] to authenticate. Applications using `DefaultAzureCredential` or `AzureDeveloperCliCredential` can then use this account to authenticate calls in their application when running locally. + +To authenticate with the [Azure Developer CLI][azure_developer_cli], run the command `azd auth login`. For users running on a system with a default web browser, the Azure Developer CLI launches the browser to authenticate the user. + +For systems without a default web browser, the `azd auth login --use-device-code` command uses the device code authentication flow. -Each `TokenCredential` implementation provides a `new` constructor that returns an `azure_core::Result>`. The credential provider is contained within an `Arc` because these are designed to be reused by multiple clients for efficiency e.g.: +## Key concepts + +### Credentials + +A credential is a class that contains or can obtain the data needed for a service client to authenticate requests. Service clients across the Azure SDK accept a credential instance when they're constructed, and use that credential to authenticate requests. + +The Azure Identity library focuses on OAuth authentication with Microsoft Entra ID. It offers various credential classes capable of acquiring a Microsoft Entra access token. See the [Credential classes](#credential-classes "Credential classes") section for a list of this library's credential classes. + +### DefaultAzureCredential + +`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 + +As of version 1.14.0, `DefaultAzureCredential` attempts to authenticate with all developer credentials until one succeeds, regardless of any errors previous developer credentials experienced. For example, a developer credential may attempt to get a token and fail, so `DefaultAzureCredential` will continue to the next credential in the flow. Deployed service credentials stop the flow with a thrown exception if they're able to attempt token retrieval, but don't receive one. Prior to version 1.14.0, developer credentials would similarly stop the authentication flow if token retrieval failed, but this is no longer the case. + +This allows for trying all of the developer credentials on your machine while having predictable deployed behavior. + +## Examples + +The following examples are provided: + +* [Authenticate with DefaultAzureCredential](#authenticate-with-defaultazurecredential "Authenticate with DefaultAzureCredential") + + +### Authenticate with `DefaultAzureCredential` + +More details on configuring your environment to use `DefaultAzureCredential` can be found in the class's [reference documentation][default_cred_ref]. + +This example demonstrates authenticating the `CosmosClient` from the [azure_data_cosmos][azure_data_cosmos] library using `DefaultAzureCredential`. ```rust -use azure_core::credentials::TokenCredential; +use azure_data_cosmos::CosmosClient; use azure_identity::DefaultAzureCredential; -# use azure_core::{ClientOptions, Result}; -# use std::sync::Arc; -# struct StorageAccountClient; -# impl StorageAccountClient { -# fn new(_endpoint: &str, _credential: Arc, _options: Option) -> Result> { -# Ok(Arc::new(StorageAccountClient)) -# } -# } -# struct SecretClient; -# impl SecretClient { -# fn new(_endpoint: &str, _credential: Arc, _options: Option) -> Result> { -# Ok(Arc::new(SecretClient)) -# } -# } let credential = DefaultAzureCredential::new().unwrap(); -let storage_client = StorageAccountClient::new( - "https://myaccount.blob.storage.azure.net", - credential.clone(), - None, -); -let secret_client = SecretClient::new("https://myvault.keyvault.azure.net", - credential.clone(), - None, -); +let client = CosmosClient::new("https://myaccount.documents.azure.com/", credential, None).unwrap(); +``` + + + + + + + + + + + +## Credential classes + +### Credential chains + +|Credential|Usage +|-|- +|[`DefaultAzureCredential`][default_cred_ref]| Provides a simplified authentication experience to quickly start developing applications run in Azure. + +### Authenticate Azure-hosted applications + +|Credential|Usage +|-|- +|[`ImdsManagedIdentityCredential`][managed_id_cred_ref]| Authenticates the managed identity of an Azure resource. +|[`WorkloadIdentityCredential`][workload_id_cred_ref]| Supports [Microsoft Entra Workload ID](https://learn.microsoft.com/azure/aks/workload-identity-overview) on Kubernetes. + + +### Authenticate service principals + +|Credential|Usage|Reference +|-|-|- +|[`ClientCertificateCredential`][cert_cred_ref]| Authenticates a service principal using a certificate. | [Service principal authentication](https://learn.microsoft.com/entra/identity-platform/app-objects-and-service-principals) + + + + + + +### Authenticate via development tools + +|Credential|Usage|Reference +|-|-|- +|[`AzureCliCredential`][cli_cred_ref]| Authenticates in a development environment with the Azure CLI. | [Azure CLI authentication](https://learn.microsoft.com/cli/azure/authenticate-azure-cli) + + + + + + + + + +## Token caching + +Token caching is a feature provided by the Azure Identity library that allows apps to: +- Cache tokens in memory (default) or on disk (opt-in). +- Improve resilience and performance. +- Reduce the number of requests made to Microsoft Entra ID to obtain access tokens. + +The Azure Identity library offers both in-memory and persistent disk caching. For more information, see the [token caching documentation](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/identity/azure-identity/TOKEN_CACHING.md). + +## Brokered authentication + +An authentication broker is an application that runs on a user’s machine and manages the authentication handshakes and token maintenance for connected accounts. Currently, only the Windows Web Account Manager (WAM) is supported. To enable support, use the [`azure-identity-broker`][azure_identity_broker] package. For details on authenticating using WAM, see the [broker plugin documentation][azure_identity_broker_readme]. + +## Troubleshooting + +See the [troubleshooting guide][troubleshooting_guide] for details on how to diagnose various failure scenarios. + +### Error handling + +Credentials raise `CredentialUnavailableError` when they're unable to attempt authentication because they lack required data or state. For example, [EnvironmentCredential][environment_cred_ref] raises this exception when [its configuration](#environment-variables "its configuration") is incomplete. + +Credentials raise `azure.core.exceptions.ClientAuthenticationError` when they fail to authenticate. `ClientAuthenticationError` has a `message` attribute, which describes why authentication failed. When raised by `DefaultAzureCredential` or `ChainedTokenCredential`, the message collects error messages from each credential in the chain. + +For more information on handling specific Microsoft Entra ID errors, see the Microsoft Entra ID [error code documentation](https://learn.microsoft.com/entra/identity-platform/reference-error-codes). + +### Logging + +This library uses the standard [logging](https://docs.python.org/3/library/logging.html) library for logging. Credentials log basic information, including HTTP sessions (URLs, headers, etc.) at INFO level. These log entries don't contain authentication secrets. + +Detailed DEBUG-level logging, including request/response bodies and header values, isn't enabled by default. It can be enabled with the `logging_enable` argument. For example: + +```python +credential = DefaultAzureCredential(logging_enable=True) ``` -Credentials are cached in memory and refreshed as needed. Using the same credentials in multiple clients prevents authenticating and refreshing tokens numerous times for each client otherwise. +> CAUTION: DEBUG-level logs from credentials contain sensitive information. +> These logs must be protected to avoid compromising account security. + +## Next steps + +### Client library support + +Client and management libraries listed on the [Azure SDK release page](https://azure.github.io/azure-sdk/releases/latest/python.html) that support Microsoft Entra authentication accept credentials from this library. You can learn more about using these libraries in their documentation, which is linked from the release page. + +### Known issues + +This library doesn't support [Azure AD B2C][b2c]. + +For other open issues, refer to the library's [GitHub repository](https://github.com/Azure/azure-sdk-for-python/issues?q=is%3Aopen+is%3Aissue+label%3AAzure.Identity). + +### Provide feedback + +If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-python/issues). + +## Contributing + +This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit [https://cla.microsoft.com](https://cla.microsoft.com). + +When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You'll only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + + +[azure_cli]: https://learn.microsoft.com/cli/azure +[azure_data_cosmos]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos +[azure_developer_cli]: https://learn.microsoft.com/azure/developer/azure-developer-cli/ +[azure_sub]: https://azure.microsoft.com/free/ +[cert_cred_ref]: +[cli_cred_ref]: +[default_cred_ref]: +[entraid_doc]: https://learn.microsoft.com/entra/identity/ +[identity_api_docs]: https://docs.rs/azure_identity/latest/azure_identity/ +[managed_id_cred_ref]: +[package]: https://crates.io/crates/azure_identity +[source]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity +[workload_id_cred_ref]: + + From 60022d3ac43865980f029d2a6930192543cc3fc6 Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Fri, 20 Dec 2024 17:52:52 -0800 Subject: [PATCH 02/17] changed TokenCredential link --- sdk/identity/azure_identity/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index c91937be83..8d159b2cb2 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -1,6 +1,6 @@ # Azure Identity client library for Rust -The Azure Identity library provides [Microsoft Entra ID](https://learn.microsoft.com/entra/fundamentals/whatis) ([formerly Azure Active Directory](https://learn.microsoft.com/entra/fundamentals/new-name)) token authentication support across the Azure SDK. It provides a set of [`TokenCredential`](https://learn.microsoft.com/dotnet/api/azure.core.tokencredential?view=azure-dotnet) implementations that can be used to construct Azure SDK clients that support Microsoft Entra token authentication. +The Azure Identity library provides [Microsoft Entra ID](https://learn.microsoft.com/entra/fundamentals/whatis) ([formerly Azure Active Directory](https://learn.microsoft.com/entra/fundamentals/new-name)) token authentication support across the Azure SDK. It provides a set of [`TokenCredential`][token_cred_ref] implementations that can be used to construct Azure SDK clients that support Microsoft Entra token authentication. [Source code][source] | [Package (crates.io)][package] | [API reference documentation][identity_api_docs] | [Microsoft Entra ID documentation][entraid_doc] @@ -379,6 +379,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope [managed_id_cred_ref]: [package]: https://crates.io/crates/azure_identity [source]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity +[token_cred_ref]: [workload_id_cred_ref]: - + + + + + ## Next steps ### Client library support -Client and management libraries listed on the [Azure SDK release page](https://azure.github.io/azure-sdk/releases/latest/python.html) that support Microsoft Entra authentication accept credentials from this library. You can learn more about using these libraries in their documentation, which is linked from the release page. - -### Known issues - -This library doesn't support [Azure AD B2C][b2c]. - -For other open issues, refer to the library's [GitHub repository](https://github.com/Azure/azure-sdk-for-python/issues?q=is%3Aopen+is%3Aissue+label%3AAzure.Identity). +Client and management libraries that support Microsoft Entra authentication accept credentials from this library. You can learn more about using these libraries in their documentation, which is available at [Docs.rs](https://Docs.rs). ### Provide feedback -If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-python/issues). +If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-rust/issues). ## Contributing From 1d0c0b85c75e4c6c86afc172e223d214f566841a Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Tue, 28 Jan 2025 14:35:12 -0800 Subject: [PATCH 05/17] Refactor README.md to improve link formatting and consistency --- sdk/identity/azure_identity/README.md | 30 +++++++++++++-------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index 8b54ae3d05..075355c964 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -2,7 +2,7 @@ The Azure Identity library provides [Microsoft Entra ID](https://learn.microsoft.com/entra/fundamentals/whatis) ([formerly Azure Active Directory](https://learn.microsoft.com/entra/fundamentals/new-name)) token authentication support across the Azure SDK. It provides a set of [`TokenCredential`][token_cred_ref] implementations that can be used to construct Azure SDK clients that support Microsoft Entra token authentication. -[Source code][source] | [Package (crates.io)][package] | [API reference documentation][identity_api_docs] | [Microsoft Entra ID documentation][entraid_doc] +[Source code] | [Package (crates.io)] | [API reference documentation] | [Microsoft Entra ID documentation] ## Getting started @@ -16,8 +16,8 @@ cargo add azure_identity ### Prerequisites -* An [Azure subscription][azure_sub]. -* The [Azure CLI][azure_cli] can also be useful for authenticating in a development environment, creating accounts, and managing account roles. +* An [Azure subscription]. +* The [Azure CLI] can also be useful for authenticating in a development environment, creating accounts, and managing account roles. ### Authenticate during local development @@ -25,15 +25,15 @@ When debugging and executing code locally, it's typical for developers to use th #### Authenticate via the Azure CLI -`DefaultAzureCredential` and `AzureCliCredential` can authenticate as the user signed in to the [Azure CLI][azure_cli]. To sign in to the Azure CLI, run `az login`. On a system with a default web browser, the Azure CLI launches the browser to authenticate a user. +`DefaultAzureCredential` and `AzureCliCredential` can authenticate as the user signed in to the [Azure CLI]. To sign in to the Azure CLI, run `az login`. On a system with a default web browser, the Azure CLI launches the browser to authenticate a user. When no default browser is available, `az login` uses the device code authentication flow. This flow can also be selected manually by running `az login --use-device-code`. #### Authenticate via the Azure Developer CLI -Developers coding outside of an IDE can also use the [Azure Developer CLI][azure_developer_cli] to authenticate. Applications using `DefaultAzureCredential` or `AzureDeveloperCliCredential` can then use this account to authenticate calls in their application when running locally. +Developers coding outside of an IDE can also use the [Azure Developer CLI] to authenticate. Applications using `DefaultAzureCredential` or `AzureDeveloperCliCredential` can then use this account to authenticate calls in their application when running locally. -To authenticate with the [Azure Developer CLI][azure_developer_cli], run the command `azd auth login`. For users running on a system with a default web browser, the Azure Developer CLI launches the browser to authenticate the user. +To authenticate with the [Azure Developer CLI], run the command `azd auth login`. For users running on a system with a default web browser, the Azure Developer CLI launches the browser to authenticate the user. For systems without a default web browser, the `azd auth login --use-device-code` command uses the device code authentication flow. @@ -69,7 +69,7 @@ The following examples are provided: More details on configuring your environment to use `DefaultAzureCredential` can be found in the class's [reference documentation][default_cred_ref]. -This example demonstrates authenticating the `CosmosClient` from the [azure_data_cosmos][azure_data_cosmos] library using `DefaultAzureCredential`. +This example demonstrates authenticating the `CosmosClient` from the [azure_data_cosmos] library using `DefaultAzureCredential`. ```rust use azure_data_cosmos::CosmosClient; @@ -370,19 +370,19 @@ When you submit a pull request, a CLA-bot will automatically determine whether y This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. -[azure_cli]: https://learn.microsoft.com/cli/azure +[Azure CLI]: https://learn.microsoft.com/cli/azure [azure_data_cosmos]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos -[azure_developer_cli]: https://learn.microsoft.com/azure/developer/azure-developer-cli/ -[azure_sub]: https://azure.microsoft.com/free/ +[Azure Developer CLI]: https://learn.microsoft.com/azure/developer/azure-developer-cli/ +[Azure subscription]: https://azure.microsoft.com/free/ [cert_cred_ref]: [cli_cred_ref]: -[default_cred_ref]: -[entraid_doc]: https://learn.microsoft.com/entra/identity/ -[identity_api_docs]: https://docs.rs/azure_identity/latest/azure_identity/ +[default_cred_ref]: +[Microsoft Entra ID documentation]: https://learn.microsoft.com/entra/identity/ +[API reference documentation]: https://docs.rs/azure_identity/latest/azure_identity/ [managed_id_cred_ref]: -[package]: https://crates.io/crates/azure_identity -[source]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity +[Package (crates.io)]: https://crates.io/crates/azure_identity +[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity [token_cred_ref]: [workload_id_cred_ref]: From 573d73a7a2979cd8a9d7907b6f847e61d11292b3 Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Tue, 28 Jan 2025 15:04:48 -0800 Subject: [PATCH 06/17] Clarify version behavior of DefaultAzureCredential and removed commented section in README.md --- sdk/identity/azure_identity/README.md | 125 +------------------------- 1 file changed, 1 insertion(+), 124 deletions(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index 075355c964..09af059eea 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -51,7 +51,7 @@ The Azure Identity library focuses on OAuth authentication with Microsoft Entra #### Continuation policy -As of version 1.14.0, `DefaultAzureCredential` attempts to authenticate with all developer credentials until one succeeds, regardless of any errors previous developer credentials experienced. For example, a developer credential may attempt to get a token and fail, so `DefaultAzureCredential` will continue to the next credential in the flow. Deployed service credentials stop the flow with a thrown exception if they're able to attempt token retrieval, but don't receive one. Prior to version 1.14.0, developer credentials would similarly stop the authentication flow if token retrieval failed, but this is no longer the case. +As of version 1.14.0, `DefaultAzureCredential` attempts to authenticate with all developer credentials until one succeeds, regardless of any errors previous developer credentials experienced. For example, a developer credential may attempt to get a token and fail, so `DefaultAzureCredential` will continue to the next credential in the flow. Deployed service credentials stop the flow with a thrown exception if they're able to attempt token retrieval, but don't receive one. Prior to version 1.14.0, developer credentials would similarly stop the authentication flow if token retrieval failed, but this is no longer the case. This allows for trying all of the developer credentials on your machine while having predictable deployed behavior. @@ -60,10 +60,6 @@ This allows for trying all of the developer credentials on your machine while ha The following examples are provided: * [Authenticate with DefaultAzureCredential](#authenticate-with-defaultazurecredential "Authenticate with DefaultAzureCredential") - ### Authenticate with `DefaultAzureCredential` @@ -79,125 +75,6 @@ let credential = DefaultAzureCredential::new().unwrap(); let client = CosmosClient::new("https://myaccount.documents.azure.com/", credential, None).unwrap(); ``` - - - - - - - - - ## Credential classes From 93393c7f5ed46862e9802001ff9f5f91dbf2d433 Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Tue, 28 Jan 2025 15:33:23 -0800 Subject: [PATCH 07/17] Update README.md example to use proper error handling in DefaultAzureCredential example --- sdk/identity/azure_identity/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index 09af059eea..ac212b6661 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -71,8 +71,10 @@ This example demonstrates authenticating the `CosmosClient` from the [azure_data use azure_data_cosmos::CosmosClient; use azure_identity::DefaultAzureCredential; -let credential = DefaultAzureCredential::new().unwrap(); -let client = CosmosClient::new("https://myaccount.documents.azure.com/", credential, None).unwrap(); +fn main() -> Result<(), Box> { + let credential = DefaultAzureCredential::new()?; + let client = CosmosClient::new("https://myaccount.documents.azure.com/", credential.clone(), None)?; +} ``` From 6c69f2ab018b830e2a9f725dd00fb6669e033ee3 Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Tue, 28 Jan 2025 15:42:34 -0800 Subject: [PATCH 08/17] Removed commented out sections --- sdk/identity/azure_identity/README.md | 174 +------------------------- 1 file changed, 1 insertion(+), 173 deletions(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index ac212b6661..f8db8e46ed 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -29,14 +29,6 @@ When debugging and executing code locally, it's typical for developers to use th When no default browser is available, `az login` uses the device code authentication flow. This flow can also be selected manually by running `az login --use-device-code`. -#### Authenticate via the Azure Developer CLI - -Developers coding outside of an IDE can also use the [Azure Developer CLI] to authenticate. Applications using `DefaultAzureCredential` or `AzureDeveloperCliCredential` can then use this account to authenticate calls in their application when running locally. - -To authenticate with the [Azure Developer CLI], run the command `azd auth login`. For users running on a system with a default web browser, the Azure Developer CLI launches the browser to authenticate the user. - -For systems without a default web browser, the `azd auth login --use-device-code` command uses the device code authentication flow. - ## Key concepts ### Credentials @@ -85,150 +77,25 @@ fn main() -> Result<(), Box> { |Credential|Usage |-|- |[`DefaultAzureCredential`][default_cred_ref]| Provides a simplified authentication experience to quickly start developing applications run in Azure. - + ### Authenticate Azure-hosted applications |Credential|Usage |-|- |[`ImdsManagedIdentityCredential`][managed_id_cred_ref]| Authenticates the managed identity of an Azure resource. |[`WorkloadIdentityCredential`][workload_id_cred_ref]| Supports [Microsoft Entra Workload ID](https://learn.microsoft.com/azure/aks/workload-identity-overview) on Kubernetes. - ### Authenticate service principals |Credential|Usage|Reference |-|-|- |[`ClientCertificateCredential`][cert_cred_ref]| Authenticates a service principal using a certificate. | [Service principal authentication](https://learn.microsoft.com/entra/identity-platform/app-objects-and-service-principals) - - - - - ### Authenticate via development tools |Credential|Usage|Reference |-|-|- |[`AzureCliCredential`][cli_cred_ref]| Authenticates in a development environment with the Azure CLI. | [Azure CLI authentication](https://learn.microsoft.com/cli/azure/authenticate-azure-cli) - - - - - - - - - - - - - - - - - ## Next steps @@ -251,7 +118,6 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope [Azure CLI]: https://learn.microsoft.com/cli/azure [azure_data_cosmos]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos -[Azure Developer CLI]: https://learn.microsoft.com/azure/developer/azure-developer-cli/ [Azure subscription]: https://azure.microsoft.com/free/ [cert_cred_ref]: [cli_cred_ref]: [workload_id_cred_ref]: - - From b1c1aee11b82437f7f13306a900161deca89fd4b Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Wed, 29 Jan 2025 11:14:39 -0800 Subject: [PATCH 09/17] Update README.md example to use SecretClient instead of CosmosClient --- sdk/identity/azure_identity/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index f8db8e46ed..7b5f2d4e20 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -60,12 +60,12 @@ More details on configuring your environment to use `DefaultAzureCredential` can This example demonstrates authenticating the `CosmosClient` from the [azure_data_cosmos] library using `DefaultAzureCredential`. ```rust -use azure_data_cosmos::CosmosClient; use azure_identity::DefaultAzureCredential; +use azure_security_keyvault_secrets::SecretClient; fn main() -> Result<(), Box> { let credential = DefaultAzureCredential::new()?; - let client = CosmosClient::new("https://myaccount.documents.azure.com/", credential.clone(), None)?; + let client = SecretClient::new("https://myaccount.documents.azure.com/", credential.clone(), None)?; } ``` From 17b2c81cb04801ec28f44930d4ac74e81b360872 Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Thu, 30 Jan 2025 12:01:08 -0800 Subject: [PATCH 10/17] Add azure_security_keyvault_secrets as a dev dependency and update README example to include proper return handling --- sdk/identity/azure_identity/Cargo.toml | 1 + sdk/identity/azure_identity/README.md | 1 + 2 files changed, 2 insertions(+) diff --git a/sdk/identity/azure_identity/Cargo.toml b/sdk/identity/azure_identity/Cargo.toml index defd286c70..d4c6e6c29c 100644 --- a/sdk/identity/azure_identity/Cargo.toml +++ b/sdk/identity/azure_identity/Cargo.toml @@ -33,6 +33,7 @@ async-process.workspace = true tz-rs = { workspace = true, optional = true } [dev-dependencies] +azure_security_keyvault_secrets.workspace = true reqwest.workspace = true tokio.workspace = true tracing-subscriber.workspace = true diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index 7b5f2d4e20..c30c5bf105 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -66,6 +66,7 @@ use azure_security_keyvault_secrets::SecretClient; fn main() -> Result<(), Box> { let credential = DefaultAzureCredential::new()?; let client = SecretClient::new("https://myaccount.documents.azure.com/", credential.clone(), None)?; + Ok(()) } ``` From bf88d0267f1787485f4d3af31c46e554c011cfae Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Thu, 30 Jan 2025 12:07:42 -0800 Subject: [PATCH 11/17] Add azure_security_keyvault_secrets as a dependency and update README --- Cargo.lock | 1 + sdk/identity/azure_identity/Cargo.toml | 2 +- sdk/identity/azure_identity/README.md | 1 - 3 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 49ec632e85..8b236fb386 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -419,6 +419,7 @@ dependencies = [ "async-process", "async-trait", "azure_core", + "azure_security_keyvault_secrets", "clap", "futures", "oauth2", diff --git a/sdk/identity/azure_identity/Cargo.toml b/sdk/identity/azure_identity/Cargo.toml index 450bf33501..c4a3af6acf 100644 --- a/sdk/identity/azure_identity/Cargo.toml +++ b/sdk/identity/azure_identity/Cargo.toml @@ -33,7 +33,7 @@ async-process.workspace = true tz-rs = { workspace = true, optional = true } [dev-dependencies] -azure_security_keyvault_secrets.workspace = true +azure_security_keyvault_secrets = { path = "../../keyvault/azure_security_keyvault_secrets" } reqwest.workspace = true tokio.workspace = true tracing-subscriber.workspace = true diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index c30c5bf105..d8283403dc 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -70,7 +70,6 @@ fn main() -> Result<(), Box> { } ``` - ## Credential classes ### Credential chains From b6c8cd8fd21129211396b19a874939d992e6b300 Mon Sep 17 00:00:00 2001 From: Ronnie Geraghty Date: Thu, 30 Jan 2025 16:26:35 -0800 Subject: [PATCH 12/17] Update README to demonstrate authentication with SecretClient from azure_security_keyvault_secrets --- sdk/identity/azure_identity/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sdk/identity/azure_identity/README.md b/sdk/identity/azure_identity/README.md index d8283403dc..50bbacb23e 100644 --- a/sdk/identity/azure_identity/README.md +++ b/sdk/identity/azure_identity/README.md @@ -57,7 +57,7 @@ The following examples are provided: More details on configuring your environment to use `DefaultAzureCredential` can be found in the class's [reference documentation][default_cred_ref]. -This example demonstrates authenticating the `CosmosClient` from the [azure_data_cosmos] library using `DefaultAzureCredential`. +This example demonstrates authenticating the `SecretClient` from the [azure_security_keyvault_secrets] library using `DefaultAzureCredential`. ```rust use azure_identity::DefaultAzureCredential; @@ -65,7 +65,7 @@ use azure_security_keyvault_secrets::SecretClient; fn main() -> Result<(), Box> { let credential = DefaultAzureCredential::new()?; - let client = SecretClient::new("https://myaccount.documents.azure.com/", credential.clone(), None)?; + let client = SecretClient::new("https://.vault.azure.net/", credential.clone(), None)?; Ok(()) } ``` @@ -117,7 +117,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope [Azure CLI]: https://learn.microsoft.com/cli/azure -[azure_data_cosmos]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos +[azure_security_keyvault_secrets]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/keyvault/azure_security_keyvault_secrets [Azure subscription]: https://azure.microsoft.com/free/ [cert_cred_ref]: [cli_cred_ref]: that support Microsoft Entra authentication accept credentials from this library. You can learn more about using these libraries in their documentation, which is available at [Docs.rs](https://Docs.rs). +Client and management libraries listed on the [Azure SDK release page](https://azure.github.io/azure-sdk/releases/latest/rust.html)that support Microsoft Entra authentication accept credentials from this library. You can learn more about using these libraries in their documentation, which is available at [Docs.rs](https://Docs.rs). ### Provide feedback @@ -119,14 +119,13 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope [Azure CLI]: https://learn.microsoft.com/cli/azure [azure_security_keyvault_secrets]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/keyvault/azure_security_keyvault_secrets [Azure subscription]: https://azure.microsoft.com/free/ -[cert_cred_ref]: -[cli_cred_ref]: -[default_cred_ref]: +[cert_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.ClientCertificateCredential.html +[cli_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.AzureauthCliCredential.html +[default_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.DefaultAzureCredential.html [Microsoft Entra ID documentation]: https://learn.microsoft.com/entra/identity/ [API reference documentation]: https://docs.rs/azure_identity/latest/azure_identity/ -[managed_id_cred_ref]: +[managed_id_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.ImdsManagedIdentityCredential.html [Package (crates.io)]: https://crates.io/crates/azure_identity [Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity -[token_cred_ref]: -[workload_id_cred_ref]: +[token_cred_ref]: https://docs.rs/azure_core/latest/azure_core/struct.TokenCredential.html +[workload_id_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.WorkloadIdentityCredential.html