Skip to content

Commit acd9f6b

Browse files
ronniegeraghtyRickWinter
ronniegeraghty
and
RickWinter
authored
Updates to the azure_identity README (Azure#1990)
* Initial pass * changed TokenCredential link * Fixed code block formatting for install command * First draft of identity beta README * Refactor README.md to improve link formatting and consistency * Clarify version behavior of DefaultAzureCredential and removed commented section in README.md * Update README.md example to use proper error handling in DefaultAzureCredential example * Removed commented out sections * Update README.md example to use SecretClient instead of CosmosClient * Add azure_security_keyvault_secrets as a dev dependency and update README example to include proper return handling * Add azure_security_keyvault_secrets as a dependency and update README * Update README to demonstrate authentication with SecretClient from azure_security_keyvault_secrets * Fix README example to use correct Key Vault URL format * Update sdk/identity/azure_identity/README.md Co-authored-by: Rick Winter <[email protected]> * Update README to reflect version change for DefaultAzureCredential behavior * Clarify continuation policy for DefaultAzureCredential in README * Fixed links to point to existing or future Rust library reference docs. --------- Co-authored-by: Rick Winter <[email protected]>
1 parent e2b80b2 commit acd9f6b

File tree

3 files changed

+117
-61
lines changed

3 files changed

+117
-61
lines changed

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎sdk/identity/azure_identity/Cargo.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ async-process.workspace = true
3333
tz-rs = { workspace = true, optional = true }
3434

3535
[dev-dependencies]
36+
azure_security_keyvault_secrets = { path = "../../keyvault/azure_security_keyvault_secrets" }
3637
reqwest.workspace = true
3738
tokio.workspace = true
3839
tracing-subscriber.workspace = true

‎sdk/identity/azure_identity/README.md‎

Lines changed: 115 additions & 61 deletions
Original file line numberDiff line numberDiff line change
@@ -1,77 +1,131 @@
1-
# azure_identity
1+
# Azure Identity client library for Rust
22

3-
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 <https://github.com/Azure/azure-sdk-for-rust>.
3+
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.
44

5-
This crate provides several implementations of the [azure_core::auth::TokenCredential](https://docs.rs/azure_core/latest/azure_core/auth/trait.TokenCredential.html) trait.
6-
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`.
5+
[Source code] | [Package (crates.io)] | [API reference documentation] | [Microsoft Entra ID documentation]
76

8-
```rust,no_run
9-
use azure_core::credentials::TokenCredential;
10-
use std::sync::Arc;
7+
## Getting started
118

12-
#[tokio::main]
13-
async fn main() -> Result<(), Box<dyn std::error::Error>> {
14-
let subscription_id =
15-
std::env::var("AZURE_SUBSCRIPTION_ID").expect("AZURE_SUBSCRIPTION_ID required");
9+
### Install the package
1610

17-
let credential: Arc<dyn TokenCredential> = azure_identity::DefaultAzureCredential::new()?;
11+
Install the Azure Identity library for Rust with cargo:
1812

19-
// Let's enumerate the Azure storage accounts in the subscription using the REST API directly.
20-
// This is just an example. It is easier to use the Azure SDK for Rust crates.
21-
let url = url::Url::parse(&format!("https://management.azure.com/subscriptions/{subscription_id}/providers/Microsoft.Storage/storageAccounts?api-version=2019-06-01"))?;
13+
```bash
14+
cargo add azure_identity
15+
```
2216

23-
let access_token = credential
24-
.get_token(&["https://management.azure.com/.default"])
25-
.await?;
17+
### Prerequisites
2618

27-
let response = reqwest::Client::new()
28-
.get(url)
29-
.header(
30-
"Authorization",
31-
format!("Bearer {}", access_token.token.secret()),
32-
)
33-
.send()
34-
.await?
35-
.text()
36-
.await?;
19+
* An [Azure subscription].
20+
* The [Azure CLI] can also be useful for authenticating in a development environment, creating accounts, and managing account roles.
3721

38-
println!("{response}");
39-
Ok(())
40-
}
41-
```
22+
### Authenticate during local development
23+
24+
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.
25+
26+
#### Authenticate via the Azure CLI
27+
28+
`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.
29+
30+
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`.
31+
32+
## Key concepts
33+
34+
### Credentials
35+
36+
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.
4237

43-
## Design
38+
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.
4439

45-
Each `TokenCredential` implementation provides a `new` constructor that returns an `azure_core::Result<Arc<Self>>`. The credential provider is contained within an `Arc` because these are designed to be reused by multiple clients for efficiency e.g.:
40+
### DefaultAzureCredential
41+
42+
`DefaultAzureCredential` simplifies authentication while developing apps that deploy to Azure by combining credentials used in Azure hosting environments with credentials used in local development.
43+
44+
#### Continuation policy
45+
46+
`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.
47+
48+
This allows for trying all of the developer credentials on your machine while having predictable deployed behavior.
49+
50+
## Examples
51+
52+
The following examples are provided:
53+
<!-- no toc -->
54+
* [Authenticate with DefaultAzureCredential](#authenticate-with-defaultazurecredential "Authenticate with DefaultAzureCredential")
55+
56+
### Authenticate with `DefaultAzureCredential`
57+
58+
More details on configuring your environment to use `DefaultAzureCredential` can be found in the class's [reference documentation][default_cred_ref].
59+
60+
This example demonstrates authenticating the `SecretClient` from the [azure_security_keyvault_secrets] crate using `DefaultAzureCredential`.
4661

4762
```rust
48-
use azure_core::credentials::TokenCredential;
4963
use azure_identity::DefaultAzureCredential;
50-
# use azure_core::{ClientOptions, Result};
51-
# use std::sync::Arc;
52-
# struct StorageAccountClient;
53-
# impl StorageAccountClient {
54-
# fn new(_endpoint: &str, _credential: Arc<dyn TokenCredential>, _options: Option<ClientOptions>) -> Result<Arc<Self>> {
55-
# Ok(Arc::new(StorageAccountClient))
56-
# }
57-
# }
58-
# struct SecretClient;
59-
# impl SecretClient {
60-
# fn new(_endpoint: &str, _credential: Arc<dyn TokenCredential>, _options: Option<ClientOptions>) -> Result<Arc<Self>> {
61-
# Ok(Arc::new(SecretClient))
62-
# }
63-
# }
64-
65-
let credential = DefaultAzureCredential::new().unwrap();
66-
let storage_client = StorageAccountClient::new(
67-
"https://myaccount.blob.storage.azure.net",
68-
credential.clone(),
69-
None,
70-
);
71-
let secret_client = SecretClient::new("https://myvault.keyvault.azure.net",
72-
credential.clone(),
73-
None,
74-
);
64+
use azure_security_keyvault_secrets::SecretClient;
65+
66+
fn main() -> Result<(), Box<dyn std::error::Error>> {
67+
let credential = DefaultAzureCredential::new()?;
68+
let client = SecretClient::new("https://your-key-vault-name.vault.azure.net/", credential.clone(), None)?;
69+
Ok(())
70+
}
7571
```
7672

77-
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.
73+
## Credential classes
74+
75+
### Credential chains
76+
77+
|Credential|Usage
78+
|-|-
79+
|[`DefaultAzureCredential`][default_cred_ref]| Provides a simplified authentication experience to quickly start developing applications run in Azure.
80+
81+
### Authenticate Azure-hosted applications
82+
83+
|Credential|Usage
84+
|-|-
85+
|[`ImdsManagedIdentityCredential`][managed_id_cred_ref]| Authenticates the managed identity of an Azure resource.
86+
|[`WorkloadIdentityCredential`][workload_id_cred_ref]| Supports [Microsoft Entra Workload ID](https://learn.microsoft.com/azure/aks/workload-identity-overview) on Kubernetes.
87+
88+
### Authenticate service principals
89+
90+
|Credential|Usage|Reference
91+
|-|-|-
92+
|[`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)
93+
94+
### Authenticate via development tools
95+
96+
|Credential|Usage|Reference
97+
|-|-|-
98+
|[`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)
99+
100+
## Next steps
101+
102+
### Client library support
103+
104+
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).
105+
106+
### Provide feedback
107+
108+
If you encounter bugs or have suggestions, [open an issue](https://github.com/Azure/azure-sdk-for-rust/issues).
109+
110+
## Contributing
111+
112+
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).
113+
114+
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.
115+
116+
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 [[email protected]](mailto:[email protected]) with any additional questions or comments.
117+
118+
<!-- LINKS -->
119+
[Azure CLI]: https://learn.microsoft.com/cli/azure
120+
[azure_security_keyvault_secrets]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/keyvault/azure_security_keyvault_secrets
121+
[Azure subscription]: https://azure.microsoft.com/free/
122+
[cert_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.ClientCertificateCredential.html
123+
[cli_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.AzureauthCliCredential.html
124+
[default_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.DefaultAzureCredential.html
125+
[Microsoft Entra ID documentation]: https://learn.microsoft.com/entra/identity/
126+
[API reference documentation]: https://docs.rs/azure_identity/latest/azure_identity/
127+
[managed_id_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.ImdsManagedIdentityCredential.html
128+
[Package (crates.io)]: https://crates.io/crates/azure_identity
129+
[Source code]: https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/identity/azure_identity
130+
[token_cred_ref]: https://docs.rs/azure_core/latest/azure_core/struct.TokenCredential.html
131+
[workload_id_cred_ref]: https://docs.rs/azure_identity/latest/azure_identity/struct.WorkloadIdentityCredential.html

0 commit comments

Comments
 (0)