docs(auth): add idtoken samples (#3819)

Splitting work on
#3762 that can
already be merged.

Author: alvarowolfx

Cargo.lock

@@ -30,7 +30,9 @@ name = "getting_started"
 [dependencies]
 anyhow.workspace                        = true
 crc32c.workspace                        = true
+httptest.workspace                      = true
 futures.workspace                       = true
+reqwest.workspace                       = true
 google-cloud-aiplatform-v1              = { workspace = true, default-features = false, features = ["prediction-service"] }
 google-cloud-auth.workspace             = true
 google-cloud-gax                        = { workspace = true, features = ["unstable-stream"] }
@@ -68,3 +70,6 @@ test-case.workspace         = true
 run-integration-tests = []
 log-integration-tests = []
 run-large-downloads   = []
+
+[lints]
+workspace = true

guide/samples/Cargo.toml

@@ -15,3 +15,7 @@
 pub mod adc;
 pub mod api_key;
 pub mod impersonation;
+#[cfg(google_cloud_unstable_id_token)]
+pub mod request_id_token;
+#[cfg(google_cloud_unstable_id_token)]
+pub mod verify_id_token;

guide/samples/src/authentication.rs

@@ -0,0 +1,53 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START rust_auth_request_id_token] ANCHOR: all
+// [START rust_auth_request_id_token_parameters] ANCHOR: request_id_token_parameters
+// # Parameters
+// * `audience`: The audience for the ID token.
+pub async fn sample(audience: &str) -> anyhow::Result<String> {
+    // [END rust_auth_request_id_token_parameters] ANCHOR_END: request_id_token_parameters
+    // [START rust_auth_request_id_token_use] ANCHOR: request_id_token_use
+    use google_cloud_auth::credentials::idtoken::Builder;
+    // [END rust_auth_request_id_token_use] ANCHOR_END: request_id_token_use
+
+    // [START rust_auth_request_id_token_credentials] ANCHOR: request_id_token_credentials
+    let credentials = Builder::new(audience).build()?;
+    // [END rust_auth_request_id_token_credentials] ANCHOR_END: request_id_token_credentials
+
+    // [START rust_auth_request_id_token_call] ANCHOR: request_id_token_call
+    let id_token = credentials.id_token().await?;
+    println!("ID Token: {id_token:?}");
+    // [END rust_auth_request_id_token_call] ANCHOR_END: request_id_token_call
+    Ok(id_token)
+}
+
+// [START request_id_token_send] ANCHOR: request_id_token_send
+// # Parameters
+// * `target_url`: The receiving service target URL.
+// * `credentials`: The IDTokenCredentials to use for authentication.
+pub async fn api_call_with_id_token(
+    target_url: &str,
+    credentials: &google_cloud_auth::credentials::idtoken::IDTokenCredentials,
+) -> anyhow::Result<()> {
+    use reqwest;
+
+    let id_token = credentials.id_token().await?;
+    let client = reqwest::Client::new();
+    client.get(target_url).bearer_auth(id_token).send().await?;
+
+    Ok(())
+}
+// [END request_id_token_send] ANCHOR_END: request_id_token_send
+// [END rust_auth_request_id_token] ANCHOR_END: all

guide/samples/src/authentication/request_id_token.rs

@@ -0,0 +1,36 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// [START rust_auth_verify_id_token] ANCHOR: all
+// [START rust_auth_id_verify_token_parameters] ANCHOR: verify_id_token_parameters
+// # Parameters
+// * `token`: The ID token string to verify.
+// * `audience`: The expected audience of the ID token.
+pub async fn sample(token: &str, audience: &str) -> anyhow::Result<()> {
+    // [END rust_auth_id_verify_token_parameters] ANCHOR_END: verify_id_token_parameters
+    // [START rust_auth_verify_id_token_use] ANCHOR: verify_id_token_use
+    use google_cloud_auth::credentials::idtoken::verifier::Builder as IdTokenVerifierBuilder;
+    // [END rust_auth_verify_id_token_use] ANCHOR_END: verify_id_token_use
+
+    // [START rust_auth_id_verify_token_verifier] ANCHOR: verify_id_token_verifier
+    let verifier = IdTokenVerifierBuilder::new([audience]).build();
+    // [END rust_auth_id_verify_token_verifier] ANCHOR_END: verify_id_token_verifier
+
+    // [START rust_auth_id_verify_token_verify_call] ANCHOR: verify_id_token_verify_call
+    let claims = verifier.verify(token).await?;
+    println!("Hello {}", claims["sub"]);
+    // [END rust_auth_id_verify_token_verify_call] ANCHOR_END: verify_id_token_verify_call
+    Ok(())
+}
+// [END rust_auth_id_verify_token] ANCHOR_END: all

guide/samples/src/authentication/verify_id_token.rs

@@ -24,6 +24,40 @@ mod driver {
         Ok(())
     }
 
+    #[cfg(all(test, google_cloud_unstable_id_token))]
+    #[tokio::test(flavor = "multi_thread")]
+    async fn id_token() -> anyhow::Result<()> {
+        use google_cloud_auth::credentials::idtoken::Builder;
+        use httptest::{Expectation, Server, matchers::*, responders::*};
+
+        let audience = "https://my-service.a.run.app";
+        let id_token =
+            user_guide_samples::authentication::request_id_token::sample(audience).await?;
+        user_guide_samples::authentication::verify_id_token::sample(&id_token, audience).await?;
+
+        let credentials = Builder::new(audience).build()?;
+        let id_token = credentials.id_token().await?;
+
+        let server = Server::run();
+        server.expect(
+            Expectation::matching(all_of![
+                request::method_path("GET", "/"),
+                request::headers(contains(("authorization", format!("Bearer {}", id_token)))),
+            ])
+            .respond_with(status_code(200)),
+        );
+
+        let target_url = server.url("/").to_string();
+
+        user_guide_samples::authentication::request_id_token::api_call_with_id_token(
+            &target_url,
+            &credentials,
+        )
+        .await?;
+
+        Ok(())
+    }
+
     #[tokio::test(flavor = "multi_thread")]
     async fn endpoint() -> anyhow::Result<()> {
         let project_id = std::env::var("GOOGLE_CLOUD_PROJECT").unwrap();