Authentication errors include HTTP responses (#3302)

Author: chlowell

sdk/identity/azure_identity/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- A `get_token()` error caused by an HTTP response carries that response. See the [troubleshooting guide](https://aka.ms/azsdk/rust/identity/troubleshoot#find-relevant-information-in-errors) for example code showing how to access the response.
+
 ### Breaking Changes
 
 - `ClientCertificateCredential::new()`:

sdk/identity/azure_identity/TROUBLESHOOTING.md

@@ -42,6 +42,37 @@ This error contains several pieces of information:
 
 - __Correlation ID and Timestamp__: The correlation ID and timestamp identify the request in server-side logs. This information can be useful to support engineers diagnosing unexpected Microsoft Entra ID failures.
 
+Many credential errors also carry the HTTP response that caused them. This can help in advanced debugging scenarios, for example when you want to check header values that aren't represented in the error message. The example below demonstrates how to access that response in such a case.
+
+```rust
+use azure_core::error::ErrorKind;
+
+let result = client.method().await;
+if let Err(err) = result {
+    match err.kind() {
+        // ErrorKind::Credential indicates an authentication problem
+        ErrorKind::Credential => {
+            // a credential error may wrap another error having an HTTP response
+            if let Some(inner) = err.downcast_ref::<azure_core::Error>() {
+                if let ErrorKind::HttpResponse {
+                    raw_response: Some(response),
+                    ..
+                } = inner.kind()
+                {
+                    let headers = response.headers();
+                    for (name, value) in headers.iter() {
+                        println!("{}: {}", name.as_str(), value.as_str());
+                    }
+                }
+            }
+        }
+        _ => {
+            todo!("handle other kinds of errors")
+        }
+    }
+}
+```
+
 <a id="client-secret"></a>
 ## Troubleshoot ClientSecretCredential authentication issues
 

sdk/identity/azure_identity/src/azure_cli_credential.rs

@@ -161,7 +161,7 @@ impl TokenCredential for AzureCliCredential {
 
         shell_exec::<CliTokenResponse>(self.executor.clone(), &self.env, &command)
             .await
-            .map_err(authentication_error::<Self>)
+            .map_err(|err| authentication_error(stringify!(AzureCliCredential), err))
     }
 }
 

sdk/identity/azure_identity/src/azure_developer_cli_credential.rs

@@ -131,7 +131,7 @@ impl TokenCredential for AzureDeveloperCliCredential {
         }
         shell_exec::<AzdTokenResponse>(self.executor.clone(), &self.env, &command)
             .await
-            .map_err(authentication_error::<Self>)
+            .map_err(|err| authentication_error(stringify!(AzureDeveloperCliCredential), err))
     }
 }
 

sdk/identity/azure_identity/src/azure_pipelines_credential.rs

@@ -2,8 +2,7 @@
 // Licensed under the MIT License.
 
 use crate::{
-    authentication_error, env::Env, ClientAssertion, ClientAssertionCredential,
-    ClientAssertionCredentialOptions,
+    env::Env, ClientAssertion, ClientAssertionCredential, ClientAssertionCredentialOptions,
 };
 use azure_core::{
     credentials::{AccessToken, Secret, TokenCredential, TokenRequestOptions},
@@ -109,6 +108,7 @@ impl AzurePipelinesCredential {
             tenant_id,
             client_id,
             client,
+            stringify!(AzurePipelinesCredential),
             Some(options.credential_options),
         )?;
 
@@ -124,10 +124,7 @@ impl TokenCredential for AzurePipelinesCredential {
         scopes: &[&str],
         options: Option<TokenRequestOptions<'_>>,
     ) -> azure_core::Result<AccessToken> {
-        self.0
-            .get_token(scopes, options)
-            .await
-            .map_err(authentication_error::<Self>)
+        self.0.get_token(scopes, options).await
     }
 }
 
@@ -163,16 +160,19 @@ impl ClientAssertion for Client {
                 }),
             )
             .await?;
-        if resp.status() != StatusCode::Ok {
-            let status_code = resp.status();
+        let status = resp.status();
+        if status != StatusCode::Ok {
             let err_headers: ErrorHeaders = resp.headers().get()?;
-
-            return Err(
-                azure_core::Error::with_message(
-                    ErrorKind::HttpResponse { status: status_code, error_code: Some(status_code.canonical_reason().to_string()), raw_response: None },
-                     format!("{status_code} response from the OIDC endpoint. Check service connection ID and pipeline configuration. {err_headers}"),
-                )
-            );
+            return Err(azure_core::Error::with_message(
+                ErrorKind::HttpResponse {
+                    status,
+                    error_code: Some(status.canonical_reason().to_string()),
+                    raw_response: Some(Box::new(resp)),
+                },
+                format!(
+                "{status} response from the OIDC endpoint. Check service connection ID and pipeline configuration. {err_headers}"
+            ),
+            ));
         }
 
         let assertion: Assertion = resp.into_body().json()?;
@@ -226,9 +226,9 @@ impl fmt::Display for ErrorHeaders {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::{env::Env, TSG_LINK_ERROR_TEXT};
+    use crate::env::Env;
     use azure_core::{
-        http::{AsyncRawResponse, ClientOptions, Transport},
+        http::{AsyncRawResponse, ClientOptions, RawResponse, Transport},
         Bytes,
     };
     use azure_core_test::http::MockHttpClient;
@@ -254,24 +254,25 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn error_headers() {
-        let mock_client = MockHttpClient::new(|req| {
+    async fn error_response() {
+        let expected_status = StatusCode::Forbidden;
+        let body = Bytes::from_static(b"content");
+        let mut headers = Headers::new();
+        headers.insert(MSEDGE_REF, "foo");
+        headers.insert(VSS_E2EID, "bar");
+        let expected_response =
+            RawResponse::from_bytes(expected_status, headers.clone(), body.clone());
+        let headers_for_mock = headers.clone();
+        let body_for_mock = body.clone();
+        let mock_client = MockHttpClient::new(move |req| {
             assert_eq!(
                 req.url().as_str(),
                 "http://localhost/get_token?api-version=7.1&serviceConnectionId=c"
             );
-            let mut headers = Headers::new();
-            headers.insert(MSEDGE_REF, "foo");
-            headers.insert(VSS_E2EID, "bar");
+            let headers = headers_for_mock.clone();
+            let body = body_for_mock.clone();
 
-            async move {
-                Ok(AsyncRawResponse::from_bytes(
-                    StatusCode::Forbidden,
-                    headers,
-                    Vec::new(),
-                ))
-            }
-            .boxed()
+            async move { Ok(AsyncRawResponse::from_bytes(expected_status, headers, body)) }.boxed()
         });
         let options = AzurePipelinesCredentialOptions {
             credential_options: ClientAssertionCredentialOptions {
@@ -285,25 +286,35 @@ mod tests {
                 &[(OIDC_VARIABLE_NAME, "http://localhost/get_token")][..],
             )),
         };
-        let credential =
-            AzurePipelinesCredential::new("a".into(), "b".into(), "c", "d", Some(options))
-                .expect("valid AzurePipelinesCredential");
-        let err = credential
+        let err = AzurePipelinesCredential::new("a".into(), "b".into(), "c", "d", Some(options))
+            .expect("credential")
             .get_token(&["default"], None)
             .await
             .expect_err("expected error");
-        assert!(matches!(
-            err.kind(),
-            ErrorKind::HttpResponse { status, .. }
-                if *status == StatusCode::Forbidden &&
-                    err.to_string().contains("foo") &&
-                    err.to_string().contains("bar"),
-        ));
-        assert!(
-            err.to_string()
-                .contains(&format!("{TSG_LINK_ERROR_TEXT}#apc")),
-            "expected error to contain a link to the troubleshooting guide, got '{err}'",
+
+        assert!(matches!(err.kind(), ErrorKind::Credential));
+        assert_eq!(
+            r#"AzurePipelinesCredential authentication failed. 403 response from the OIDC endpoint. Check service connection ID and pipeline configuration. Headers { x-msedge-ref: "foo", x-vss-e2eid: "bar" }
+To troubleshoot, visit https://aka.ms/azsdk/rust/identity/troubleshoot#apc"#,
+            err.to_string(),
         );
+        match err
+            .downcast_ref::<azure_core::Error>()
+            .expect("returned error should wrap an azure_core::Error")
+            .kind()
+        {
+            ErrorKind::HttpResponse {
+                error_code: Some(reason),
+                raw_response: Some(response),
+                status,
+                ..
+            } => {
+                assert_eq!(status.canonical_reason(), reason.as_str());
+                assert_eq!(&expected_response, response.as_ref());
+                assert_eq!(expected_status, *status);
+            }
+            err => panic!("unexpected {:?}", err),
+        };
     }
 
     #[tokio::test]