Add ClientAssertionCredential (#2266)

* refactor workload identity central logic into client assertion credential

* add example to the readme

* Remove locale from link

* hopefully fix readme

* fixing readme hopefully final

---------

Co-authored-by: Heath Stewart <[email protected]>

Author: beelli-microsoft

sdk/identity/azure_identity/README.md

@@ -69,6 +69,62 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     Ok(())
 }
 ```
+### Authenticate with `ClientAssertionCredential`
+
+This example demonstrates how to use the `ClientAssertionCredential` in conjunction with `VirtualMachineManagedIdentityCredential` in order to retrieve an access token as an app registration
+that a virtual machine identity has been federated for, which can be used in "service to service"
+authentication flows. For more details on this scenario see [Configure an application to trust a managed identity](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-config-app-trust-managed-identity?tabs=microsoft-entra-admin-center)
+
+```rust no_run
+use azure_core::credentials::{AccessToken, TokenCredential};
+use azure_identity::{ClientAssertion, ClientAssertionCredential, ImdsId, TokenCredentialOptions, VirtualMachineManagedIdentityCredential};
+use std::sync::Arc;
+
+#[derive(Debug)]
+struct VmClientAssertion {
+    credential: Arc<dyn TokenCredential>,
+    scope: String,
+}
+
+#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
+#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
+impl ClientAssertion for VmClientAssertion {
+    async fn secret(&self) -> azure_core::Result<String> {
+        Ok(self
+            .credential
+            .get_token(&[&self.scope])
+            .await?
+            .token
+            .secret()
+            .to_string())
+    }
+}
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+        let assertion = VmClientAssertion {
+        credential: VirtualMachineManagedIdentityCredential::new(
+            ImdsId::SystemAssigned,
+            TokenCredentialOptions::default(),
+        )?,
+        scope: String::from("api://AzureADTokenExchange/.default"),
+    };
+
+    let client_assertion_credential = ClientAssertionCredential::new(
+        azure_core::new_http_client(),
+        azure_core::Url::parse("https://login.microsoftonline.com")?,
+        String::from("guid-for-aad-tenant-id"),
+        String::from("guid-for-app-id-of-client-app-registration"),
+        assertion,
+    )?;
+
+    let fic_scope = String::from("your-service-app.com/scope");
+    let fic_token = client_assertion_credential.get_token(&[&fic_scope]).await?;
+    Ok(())
+}
+
+```
+
 
 ## Credential classes
 

sdk/identity/azure_identity/src/credentials/client_assertion_credentials.rs

@@ -0,0 +1,160 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+use crate::{credentials::cache::TokenCache, federated_credentials_flow, TokenCredentialOptions};
+use azure_core::{
+    credentials::{AccessToken, TokenCredential},
+    error::{ErrorKind, ResultExt},
+    HttpClient, Url,
+};
+use std::{fmt::Debug, str, sync::Arc, time::Duration};
+use time::OffsetDateTime;
+
+const AZURE_TENANT_ID_ENV_KEY: &str = "AZURE_TENANT_ID";
+const AZURE_CLIENT_ID_ENV_KEY: &str = "AZURE_CLIENT_ID";
+
+/// Enables authentication of a Microsoft Entra service principal using a signed client assertion.
+#[derive(Debug)]
+pub struct ClientAssertionCredential<C> {
+    http_client: Arc<dyn HttpClient>,
+    authority_host: Url,
+    tenant_id: String,
+    client_id: String,
+    assertion: C,
+    cache: TokenCache,
+}
+
+#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
+#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
+/// Represents an entity capable of supplying a client assertion.
+pub trait ClientAssertion: Send + Sync + Debug {
+    /// Supply the client assertion secret.
+    async fn secret(&self) -> azure_core::Result<String>;
+}
+
+impl<C: ClientAssertion> ClientAssertionCredential<C> {
+    /// Create a new `ClientAssertionCredential`.
+    pub fn new(
+        http_client: Arc<dyn HttpClient>,
+        authority_host: Url,
+        tenant_id: String,
+        client_id: String,
+        assertion: C,
+    ) -> azure_core::Result<Arc<Self>> {
+        Ok(Arc::new(Self::new_exclusive(
+            http_client,
+            authority_host,
+            tenant_id,
+            client_id,
+            assertion,
+        )?))
+    }
+
+    /// Create a new `ClientAssertionCredential` without wrapping it in an
+    /// `Arc`. Intended for use by other credentials in the crate that will
+    /// themselves be protected by an `Arc`.
+    pub(crate) fn new_exclusive(
+        http_client: Arc<dyn HttpClient>,
+        authority_host: Url,
+        tenant_id: String,
+        client_id: String,
+        assertion: C,
+    ) -> azure_core::Result<Self> {
+        Ok(Self {
+            http_client,
+            authority_host,
+            tenant_id,
+            client_id,
+            assertion,
+            cache: TokenCache::new(),
+        })
+    }
+
+    /// Create a new `ClientAssertionCredential` from environment variables.
+    ///
+    /// # Variables
+    ///
+    /// * `AZURE_TENANT_ID`
+    /// * `AZURE_CLIENT_ID`
+    pub fn from_env(
+        options: impl Into<TokenCredentialOptions>,
+        assertion: C,
+    ) -> azure_core::Result<Arc<Self>> {
+        Ok(Arc::new(Self::from_env_exclusive(options, assertion)?))
+    }
+
+    /// Create a new `ClientAssertionCredential` from environment variables,
+    /// without wrapping it in an `Arc`. Intended for use by other credentials
+    /// in the crate that will themselves be protected by an `Arc`.
+    ///
+    /// # Variables
+    ///
+    /// * `AZURE_TENANT_ID`
+    /// * `AZURE_CLIENT_ID`
+    pub(crate) fn from_env_exclusive(
+        options: impl Into<TokenCredentialOptions>,
+        assertion: C,
+    ) -> azure_core::Result<Self> {
+        let options = options.into();
+        let http_client = options.http_client();
+        let authority_host = options.authority_host()?;
+        let env = options.env();
+        let tenant_id =
+            env.var(AZURE_TENANT_ID_ENV_KEY)
+                .with_context(ErrorKind::Credential, || {
+                    format!(
+                        "working identity credential requires {} environment variable",
+                        AZURE_TENANT_ID_ENV_KEY
+                    )
+                })?;
+        let client_id =
+            env.var(AZURE_CLIENT_ID_ENV_KEY)
+                .with_context(ErrorKind::Credential, || {
+                    format!(
+                        "working identity credential requires {} environment variable",
+                        AZURE_CLIENT_ID_ENV_KEY
+                    )
+                })?;
+
+        ClientAssertionCredential::new_exclusive(
+            http_client,
+            authority_host,
+            tenant_id,
+            client_id,
+            assertion,
+        )
+    }
+
+    async fn get_token(&self, scopes: &[&str]) -> azure_core::Result<AccessToken> {
+        let token = self.assertion.secret().await?;
+        let res: AccessToken = federated_credentials_flow::authorize(
+            self.http_client.clone(),
+            &self.client_id,
+            &token,
+            scopes,
+            &self.tenant_id,
+            &self.authority_host,
+        )
+        .await
+        .map(|r| {
+            AccessToken::new(
+                r.access_token().clone(),
+                OffsetDateTime::now_utc() + Duration::from_secs(r.expires_in),
+            )
+        })
+        .context(ErrorKind::Credential, "request token error")?;
+        Ok(res)
+    }
+}
+
+#[cfg_attr(target_arch = "wasm32", async_trait::async_trait(?Send))]
+#[cfg_attr(not(target_arch = "wasm32"), async_trait::async_trait)]
+impl<C: ClientAssertion> TokenCredential for ClientAssertionCredential<C> {
+    async fn get_token(&self, scopes: &[&str]) -> azure_core::Result<AccessToken> {
+        self.cache.get_token(scopes, self.get_token(scopes)).await
+    }
+
+    async fn clear_cache(&self) -> azure_core::Result<()> {
+        self.cache.clear().await
+    }
+}

sdk/identity/azure_identity/src/credentials/mod.rs

@@ -12,6 +12,7 @@ mod app_service_managed_identity_credential;
 #[cfg(not(target_arch = "wasm32"))]
 mod azure_cli_credentials;
 mod cache;
+mod client_assertion_credentials;
 #[cfg(feature = "client_certificate")]
 mod client_certificate_credentials;
 mod default_credentials;
@@ -23,6 +24,7 @@ mod workload_identity_credentials;
 pub use app_service_managed_identity_credential::*;
 #[cfg(not(target_arch = "wasm32"))]
 pub use azure_cli_credentials::*;
+pub use client_assertion_credentials::*;
 #[cfg(feature = "client_certificate")]
 pub use client_certificate_credentials::*;
 pub use default_credentials::*;