Add correlation ID support to exception classes and key error paths

Copilot · Avery-Dunn · Copilot · commit 1bbb9cb6849c · 2026-02-11T22:04:54.000Z
Co-authored-by: Avery-Dunn &lt;62066438+Avery-Dunn@users.noreply.github.com&gt;
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AbstractManagedIdentitySource.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AbstractManagedIdentitySource.java
@@ -53,7 +53,12 @@ public ManagedIdentityResponse getManagedIdentityResponse(
             throw new RuntimeException(e);
         } catch (MsalClientException e) {
             if (e.getCause() instanceof SocketException) {
-                throw new MsalServiceException(e.getMessage(), MsalError.MANAGED_IDENTITY_UNREACHABLE_NETWORK, managedIdentitySourceType);
+                String message = e.getMessage();
+                LOG.error(LogHelper.createMessage(
+                        "[Managed Identity] Network unreachable: " + message,
+                        managedIdentityRequest.requestContext().correlationId()));
+                throw new MsalServiceException(message, MsalError.MANAGED_IDENTITY_UNREACHABLE_NETWORK,
+                        managedIdentityRequest.requestContext().correlationId());
             }
 
             throw e;
@@ -74,18 +79,23 @@ public ManagedIdentityResponse handleResponse(
                 return getSuccessfulResponse(response);
             } else {
                 message = getMessageFromErrorResponse(response);
-                LOG.error("[Managed Identity] request failed, HttpStatusCode: {}, Error message: {}",
-                        response.statusCode(), message);
-                throw new MsalServiceException(message, AuthenticationErrorCode.MANAGED_IDENTITY_REQUEST_FAILED, managedIdentitySourceType);
+                LOG.error(LogHelper.createMessage(
+                        String.format("[Managed Identity] request failed, HttpStatusCode: %s, Error message: %s",
+                                response.statusCode(), message),
+                        managedIdentityRequest.requestContext().correlationId()));
+                throw new MsalServiceException(message, AuthenticationErrorCode.MANAGED_IDENTITY_REQUEST_FAILED,
+                        managedIdentityRequest.requestContext().correlationId());
             }
         } catch (Exception e) {
             if (!(e instanceof MsalServiceException)) {
                 message = String.format("[Managed Identity] Unexpected exception occurred when parsing the response, HttpStatusCode: %s, Error message: %s",
                         response.statusCode(), e.getMessage());
+                LOG.error(LogHelper.createMessage(message, managedIdentityRequest.requestContext().correlationId()));
+                throw new MsalServiceException(message, AuthenticationErrorCode.MANAGED_IDENTITY_REQUEST_FAILED,
+                        managedIdentityRequest.requestContext().correlationId());
             } else {
                 throw e;
             }
-            throw new MsalServiceException(message, AuthenticationErrorCode.MANAGED_IDENTITY_REQUEST_FAILED, managedIdentitySourceType);
         }
     }
 
@@ -103,7 +113,10 @@ protected ManagedIdentityResponse getSuccessfulResponse(IHttpResponse response)
         if (managedIdentityResponse == null || managedIdentityResponse.getAccessToken() == null
                 || managedIdentityResponse.getAccessToken().isEmpty() || managedIdentityResponse.getExpiresOn() == null
                 || managedIdentityResponse.getExpiresOn().isEmpty()) {
-            throw new MsalServiceException("[Managed Identity] Response is either null or insufficient for authentication.", MsalError.MANAGED_IDENTITY_REQUEST_FAILED, managedIdentitySourceType);
+            String message = "[Managed Identity] Response is either null or insufficient for authentication.";
+            LOG.error(LogHelper.createMessage(message, managedIdentityRequest.requestContext().correlationId()));
+            throw new MsalServiceException(message, MsalError.MANAGED_IDENTITY_REQUEST_FAILED,
+                    managedIdentityRequest.requestContext().correlationId());
         }
 
         return managedIdentityResponse;
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenByAuthorizationGrantSupplier.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenByAuthorizationGrantSupplier.java
@@ -139,13 +139,21 @@ private Map<String, String> getAuthorizationGrantIntegrated(String userName) thr
 
             params = getSAMLAuthGrantParameters(wsTrustResponse);
         } else if (userRealmResponse.isAccountManaged()) {
+            String message = "Password is required for managed user";
+            clientApplication.log.error(
+                    LogHelper.createMessage(message, msalRequest.requestContext().correlationId()));
             throw new MsalClientException(
-                    "Password is required for managed user",
-                    AuthenticationErrorCode.PASSWORD_REQUIRED_FOR_MANAGED_USER);
+                    message,
+                    AuthenticationErrorCode.PASSWORD_REQUIRED_FOR_MANAGED_USER,
+                    msalRequest.requestContext().correlationId());
         } else {
+            String message = "User Realm request failed";
+            clientApplication.log.error(
+                    LogHelper.createMessage(message, msalRequest.requestContext().correlationId()));
             throw new MsalClientException(
-                    "User Realm request failed",
-                    AuthenticationErrorCode.USER_REALM_DISCOVERY_FAILED);
+                    message,
+                    AuthenticationErrorCode.USER_REALM_DISCOVERY_FAILED,
+                    msalRequest.requestContext().correlationId());
         }
 
         return params;
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenSilentSupplier.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenSilentSupplier.java
@@ -41,7 +41,11 @@ AuthenticationResult execute() throws Exception {
                     clientApplication.clientId());
 
             if (res == null) {
-                throw new MsalClientException(AuthenticationErrorMessage.NO_TOKEN_IN_CACHE, AuthenticationErrorCode.CACHE_MISS);
+                String message = AuthenticationErrorMessage.NO_TOKEN_IN_CACHE;
+                clientApplication.log.info(
+                        LogHelper.createMessage(message, silentRequest.requestContext().correlationId()));
+                throw new MsalClientException(message, AuthenticationErrorCode.CACHE_MISS,
+                        silentRequest.requestContext().correlationId());
             }
 
             //Some cached tokens were found, but this metadata will be overwritten if token needs to be refreshed
@@ -71,7 +75,11 @@ AuthenticationResult execute() throws Exception {
         }
 
         if (res == null || StringHelper.isBlank(res.accessToken())) {
-            throw new MsalClientException(AuthenticationErrorMessage.NO_TOKEN_IN_CACHE, AuthenticationErrorCode.CACHE_MISS);
+            String message = AuthenticationErrorMessage.NO_TOKEN_IN_CACHE;
+            clientApplication.log.info(
+                    LogHelper.createMessage(message, silentRequest.requestContext().correlationId()));
+            throw new MsalClientException(message, AuthenticationErrorCode.CACHE_MISS,
+                    silentRequest.requestContext().correlationId());
         }
 
         LOG.debug("Returning token from cache");
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/HttpHelper.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/HttpHelper.java
@@ -55,6 +55,10 @@ public IHttpResponse executeHttpRequest(HttpRequest httpRequest,
 
             } catch (Exception e) {
                 httpEvent.setOauthErrorCode(AuthenticationErrorCode.UNKNOWN);
+                String message = LogHelper.createMessage(
+                        "HTTP request execution failed: " + e.getMessage(),
+                        requestContext.correlationId());
+                LOG.error(message);
                 throw new MsalClientException(e);
             }
 
@@ -93,6 +97,10 @@ IHttpResponse executeHttpRequest(HttpRequest httpRequest,
 
             } catch (Exception e) {
                 httpEvent.setOauthErrorCode(AuthenticationErrorCode.UNKNOWN);
+                String message = LogHelper.createMessage(
+                        "HTTP request execution failed: " + e.getMessage(),
+                        requestContext.correlationId());
+                LOG.error(message);
                 throw new MsalClientException(e);
             }
 
@@ -113,6 +121,7 @@ IHttpResponse executeHttpRequest(HttpRequest httpRequest) {
         try {
             httpResponse = executeHttpRequestWithRetries(httpRequest, httpClient);
         } catch (Exception e) {
+            LOG.error("HTTP request execution failed: " + e.getMessage());
             throw new MsalClientException(e);
         }
 
@@ -173,7 +182,11 @@ private void checkForThrottling(RequestContext requestContext) {
             long retryInMs = ThrottlingCache.retryInMs(requestThumbprint);
 
             if (retryInMs > 0) {
-                throw new MsalThrottlingException(retryInMs);
+                String message = LogHelper.createMessage(
+                        "Request throttled, retry after " + retryInMs + " ms",
+                        requestContext.correlationId());
+                LOG.warn(message);
+                throw new MsalThrottlingException(retryInMs, requestContext.correlationId());
             }
         }
     }
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalClientException.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalClientException.java
@@ -25,4 +25,15 @@ public MsalClientException(final Throwable throwable) {
     public MsalClientException(final String message, final String errorCode) {
         super(message, errorCode);
     }
+
+    /**
+     * Initializes a new instance of the exception class with a specified error message and correlation ID
+     *
+     * @param message the error message that explains the reason for the exception
+     * @param errorCode the error code
+     * @param correlationId the correlation ID for request tracking
+     */
+    public MsalClientException(final String message, final String errorCode, final String correlationId) {
+        super(message, errorCode, correlationId);
+    }
 }
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalException.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalException.java
@@ -15,6 +15,11 @@ public class MsalException extends RuntimeException {
      */
     private String errorCode;
 
+    /**
+     * Correlation ID for request tracking
+     */
+    private String correlationId;
+
     /**
      * Initializes a new instance of the exception class
      *
@@ -34,7 +39,24 @@ public MsalException(final String message, String errorCode) {
         this.errorCode = errorCode;
     }
 
+    /**
+     * Initializes a new instance of the exception class with correlation ID
+     *
+     * @param message the error message that explains the reason for the exception
+     * @param errorCode the error code
+     * @param correlationId the correlation ID for request tracking
+     */
+    public MsalException(final String message, String errorCode, String correlationId) {
+        super(LogHelper.createMessage(message, correlationId));
+        this.errorCode = errorCode;
+        this.correlationId = correlationId;
+    }
+
     public String errorCode() {
         return this.errorCode;
     }
+
+    public String correlationId() {
+        return this.correlationId;
+    }
 }
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalServiceException.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalServiceException.java
@@ -14,7 +14,6 @@ public class MsalServiceException extends MsalException {
 
     private Integer statusCode;
     private String statusMessage;
-    private String correlationId;
     private String claims;
     private Map<String, List<String>> headers;
     private String managedIdentitySource;
@@ -30,6 +29,17 @@ public MsalServiceException(final String message, final String error) {
         super(message, error);
     }
 
+    /**
+     * Initializes a new instance of the exception class with a specified error message and correlation ID
+     *
+     * @param message the error message that explains the reason for the exception
+     * @param error a simplified error code from {@link AuthenticationErrorCode} and used for references in documentation
+     * @param correlationId the correlation ID for request tracking
+     */
+    public MsalServiceException(final String message, final String error, final String correlationId) {
+        super(message, error, correlationId);
+    }
+
     /**
      * Initializes a new instance of the exception class
      *
@@ -40,11 +50,10 @@ public MsalServiceException(
             final ErrorResponse errorResponse,
             final Map<String, List<String>> httpHeaders) {
 
-        super(errorResponse.errorDescription, errorResponse.error());
+        super(errorResponse.errorDescription, errorResponse.error(), errorResponse.correlation_id());
         this.statusCode = errorResponse.statusCode();
         this.statusMessage = errorResponse.statusMessage();
         this.subError = errorResponse.subError();
-        this.correlationId = errorResponse.correlation_id();
         this.claims = errorResponse.claims();
         this.headers = Collections.unmodifiableMap(httpHeaders);
     }
@@ -70,9 +79,7 @@ public MsalServiceException(
      * @param discoveryResponse response object from instance discovery network call
      */
     public MsalServiceException(final AadInstanceDiscoveryResponse discoveryResponse) {
-        super(discoveryResponse.errorDescription(), discoveryResponse.error());
-
-        this.correlationId = discoveryResponse.correlationId();
+        super(discoveryResponse.errorDescription(), discoveryResponse.error(), discoveryResponse.correlationId());
     }
 
     /**
@@ -92,8 +99,9 @@ public String statusMessage() {
     /**
      * An ID that can be used to piece up a single authentication flow.
      */
+    @Override
     public String correlationId() {
-        return this.correlationId;
+        return super.correlationId();
     }
 
     /**
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalThrottlingException.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/MsalThrottlingException.java
@@ -20,6 +20,19 @@ public MsalThrottlingException(long retryInMs) {
         this.retryInMs = retryInMs;
     }
 
+    /**
+     * Constructor for MsalThrottlingException class with correlation ID
+     *
+     * @param retryInMs time to wait before retrying in milliseconds
+     * @param correlationId the correlation ID for request tracking
+     */
+    public MsalThrottlingException(long retryInMs, String correlationId) {
+        super("Request was throttled according to instructions from STS. Retry in " + retryInMs + " ms.",
+                AuthenticationErrorCode.THROTTLED_REQUEST, correlationId);
+
+        this.retryInMs = retryInMs;
+    }
+
     /**
      * how long to wait before repeating request
      */
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/RequestContext.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/RequestContext.java
@@ -37,6 +37,11 @@ public RequestContext(AbstractApplicationBase clientApplication,
         this.publicApi = publicApi;
         this.authority = clientApplication.authority();
         this.apiParameters = apiParameters;
+
+        // Log the correlation ID when RequestContext is created
+        clientApplication.log.info(LogHelper.createMessage(
+                "Request initiated with PublicApi: " + publicApi,
+                this.correlationId));
     }
 
     public RequestContext(AbstractApplicationBase clientApplication,
diff --git a/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenRequestExecutor.java b/msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/TokenRequestExecutor.java
@@ -38,8 +38,11 @@ AuthenticationResult executeTokenRequest() throws IOException {
     OAuthHttpRequest createOauthHttpRequest() throws MalformedURLException {
 
         if (requestAuthority.tokenEndpointUrl() == null) {
-            throw new MsalClientException("The endpoint URI is not specified",
-                    AuthenticationErrorCode.INVALID_ENDPOINT_URI);
+            String message = "The endpoint URI is not specified";
+            LOG.error(LogHelper.createMessage(message, msalRequest.requestContext().correlationId()));
+            throw new MsalClientException(message,
+                    AuthenticationErrorCode.INVALID_ENDPOINT_URI,
+                    msalRequest.requestContext().correlationId());
         }
 
         final OAuthHttpRequest oauthHttpRequest = new OAuthHttpRequest(

Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,10 @@ public IHttpResponse executeHttpRequest(HttpRequest httpRequest,`
`55`	`55`
`56`	`56`	`} catch (Exception e) {`
`57`	`57`	`httpEvent.setOauthErrorCode(AuthenticationErrorCode.UNKNOWN);`
	`58`	`+ String message = LogHelper.createMessage(`
	`59`	`+ "HTTP request execution failed: " + e.getMessage(),`
	`60`	`+ requestContext.correlationId());`
	`61`	`+ LOG.error(message);`
`58`	`62`	`throw new MsalClientException(e);`
`59`	`63`	`}`
`60`	`64`
`@@ -93,6 +97,10 @@ IHttpResponse executeHttpRequest(HttpRequest httpRequest,`
`93`	`97`
`94`	`98`	`} catch (Exception e) {`
`95`	`99`	`httpEvent.setOauthErrorCode(AuthenticationErrorCode.UNKNOWN);`
	`100`	`+ String message = LogHelper.createMessage(`
	`101`	`+ "HTTP request execution failed: " + e.getMessage(),`
	`102`	`+ requestContext.correlationId());`
	`103`	`+ LOG.error(message);`
`96`	`104`	`throw new MsalClientException(e);`
`97`	`105`	`}`
`98`	`106`
`@@ -113,6 +121,7 @@ IHttpResponse executeHttpRequest(HttpRequest httpRequest) {`
`113`	`121`	`try {`
`114`	`122`	`httpResponse = executeHttpRequestWithRetries(httpRequest, httpClient);`
`115`	`123`	`} catch (Exception e) {`
	`124`	`+ LOG.error("HTTP request execution failed: " + e.getMessage());`
`116`	`125`	`throw new MsalClientException(e);`
`117`	`126`	`}`
`118`	`127`
`@@ -173,7 +182,11 @@ private void checkForThrottling(RequestContext requestContext) {`
`173`	`182`	`long retryInMs = ThrottlingCache.retryInMs(requestThumbprint);`
`174`	`183`
`175`	`184`	`if (retryInMs > 0) {`
`176`		`- throw new MsalThrottlingException(retryInMs);`
	`185`	`+ String message = LogHelper.createMessage(`
	`186`	`+ "Request throttled, retry after " + retryInMs + " ms",`
	`187`	`+ requestContext.correlationId());`
	`188`	`+ LOG.warn(message);`
	`189`	`+ throw new MsalThrottlingException(retryInMs, requestContext.correlationId());`
`177`	`190`	`}`
`178`	`191`	`}`
`179`	`192`	`}`