Expose headers and subErrors in exceptions

Author: sgonzalezMSFT

src/main/java/com/microsoft/aad/msal4j/AadInstanceDiscovery.java

@@ -86,8 +86,8 @@ private static String getInstanceDiscoveryEndpoint(String host) {
     }
 
     private static void validate(InstanceDiscoveryResponse instanceDiscoveryResponse) {
-        if (StringHelper.isBlank(instanceDiscoveryResponse.getTenantDiscoveryEndpoint())) {
-            throw new AuthenticationException(instanceDiscoveryResponse.getErrorDescription());
+        if (StringHelper.isBlank(instanceDiscoveryResponse.tenantDiscoveryEndpoint())) {
+            throw new AuthenticationServiceException(instanceDiscoveryResponse);
         }
     }
 
@@ -117,8 +117,8 @@ private static void validate(InstanceDiscoveryResponse instanceDiscoveryResponse
     }
 
     private static void cacheInstanceDiscoveryMetadata(String host, InstanceDiscoveryResponse instanceDiscoveryResponse) {
-        if (instanceDiscoveryResponse.getMetadata() != null) {
-            for (InstanceDiscoveryMetadataEntry entry : instanceDiscoveryResponse.getMetadata()) {
+        if (instanceDiscoveryResponse.metadata() != null) {
+            for (InstanceDiscoveryMetadataEntry entry : instanceDiscoveryResponse.metadata()) {
                 for (String alias : entry.aliases) {
                     cache.put(alias, entry);
                 }

src/main/java/com/microsoft/aad/msal4j/AcquireTokenByDeviceCodeFlowSupplier.java

@@ -77,15 +77,15 @@ private AuthenticationResult acquireTokenWithDeviceCode(DeviceCode deviceCode,
             }
             try {
                 return acquireTokenByAuthorisationGrantSupplier.execute();
-            } catch (AuthenticationException ex) {
-                if (ex.getErrorCode().equals(AUTHORIZATION_PENDING)) {
+            } catch (AuthenticationServiceException ex) {
+                if (ex.errorCode().equals(AUTHORIZATION_PENDING)) {
                     TimeUnit.SECONDS.sleep(deviceCode.interval());
                 } else {
                     throw ex;
                 }
             }
         }
-        throw new AuthenticationException("Expired Device code");
+        throw new AuthenticationClientException("Expired Device code");
     }
 
     private Long getCurrentSystemTimeInSeconds(){

src/main/java/com/microsoft/aad/msal4j/ApiEvent.java

@@ -95,7 +95,7 @@ public void setIsConfidentialClient(boolean isConfidentialClient){
         this.put(IS_CONFIDENTIAL_CLIENT_KEY, String.valueOf(isConfidentialClient).toLowerCase(Locale.ROOT));
     }
 
-    public void setApiErrorCode(AuthenticationErrorCode apiErrorCode){
-        this.put(API_ERROR_CODE_KEY, apiErrorCode.toString());
+    public void setApiErrorCode(String apiErrorCode){
+        this.put(API_ERROR_CODE_KEY, apiErrorCode);
     }
 }

src/main/java/com/microsoft/aad/msal4j/AuthenticationClientException.java

@@ -0,0 +1,23 @@
+package com.microsoft.aad.msal4j;
+
+/**
+ *  Exception type thrown when and error occurs that is local to the library or the device.
+ */
+public class AuthenticationClientException extends AuthenticationException{
+
+    /**
+     * Initializes a new instance of the exception class with a specified error message
+     * @param throwable the inner exception that is the cause of the current exception
+     */
+    public AuthenticationClientException(final Throwable throwable){
+        super(throwable);
+    }
+
+    /**
+     * Initializes a new instance of the exception class with a specified error message
+     * @param message the error message that explains the reason for the exception
+     */
+    public AuthenticationClientException(final String message){
+        super(message);
+    }
+}

src/main/java/com/microsoft/aad/msal4j/AuthenticationErrorCode.java

@@ -23,20 +23,10 @@
 
 package com.microsoft.aad.msal4j;
 
-public enum AuthenticationErrorCode {
+public class AuthenticationErrorCode {
 
-    UNKNOWN ("unknown"),
-    AUTHORIZATION_PENDING ("authorization_pending"),
-    INTERACTION_REQUIRED ("interaction_required");
-
-    private String errorCode;
-
-    AuthenticationErrorCode(String errorCode){
-        this.errorCode = errorCode;
-    }
-
-    @Override
-    public String toString(){
-        return errorCode;
-    }
+    public final static String AUTHORIZATION_PENDING = "authorization_pending";
+    public final static String INTERACTION_REQUIRED = "interaction_required";
+    public final static String INVALID_GRANT = "invalid_grant";
+    public final static String UNKNOWN = "unknown";
 }

src/main/java/com/microsoft/aad/msal4j/AuthenticationErrorMessage.java

@@ -23,53 +23,42 @@
 
 package com.microsoft.aad.msal4j;
 
+import lombok.AccessLevel;
+import lombok.Getter;
+import lombok.experimental.Accessors;
+
 /**
- * MSAL generic exception class
+ * Base exception type thrown when an error occurs during token acquisition.
  */
+@Accessors(fluent = true)
+@Getter
 public class AuthenticationException extends RuntimeException {
 
+    @Getter(value = AccessLevel.PRIVATE)
     private static final long serialVersionUID = 1L;
 
-    private AuthenticationErrorCode errorCode;
-
     /**
-     * Constructor
-     *
-     * @param t Throwable object
+     * Initializes a new instance of the exception class
+     * @param throwable the inner exception that is the cause of the current exception
      */
-    public AuthenticationException(final Throwable t) {
-        super(t);
-
-        this.errorCode = AuthenticationErrorCode.UNKNOWN;
+    public AuthenticationException(final Throwable throwable) {
+        super(throwable);
     }
 
     /**
-     * Constructor
-     *
-     * @param message string error message
+     * Initializes a new instance of the exception class
+     * @param message the error message that explains the reason for the exception
      */
     public AuthenticationException(final String message) {
-        this(AuthenticationErrorCode.UNKNOWN, message);
-    }
-
-    public AuthenticationException(AuthenticationErrorCode errorCode, final String message) {
         super(message);
-        this.errorCode = errorCode;
     }
 
     /**
-     * Constructor
-     *
-     * @param message string error message
-     * @param t Throwable object
+     * Initializes a new instance of the exception class
+     * @param message the error message that explains the reason for the exception
+     * @param t the inner exception that is the cause of the current exception
      */
     public AuthenticationException(final String message, final Throwable t) {
         super(message, t);
-
-        this.errorCode = AuthenticationErrorCode.UNKNOWN;
-    }
-
-    public AuthenticationErrorCode getErrorCode() {
-        return errorCode;
     }
 }

src/main/java/com/microsoft/aad/msal4j/AuthenticationException.java

@@ -83,8 +83,8 @@ public IAuthenticationResult get() {
                     apiEvent.setTenantId(result.accountCacheEntity().realm());
                 }
             } catch(Exception ex) {
-                if (ex instanceof AuthenticationException) {
-                    apiEvent.setApiErrorCode(((AuthenticationException) ex).getErrorCode());
+                if (ex instanceof AuthenticationServiceException) {
+                    apiEvent.setApiErrorCode(((AuthenticationServiceException) ex).errorCode());
                 }
                 clientApplication.log.error(
                         LogHelper.createMessage(

src/main/java/com/microsoft/aad/msal4j/AuthenticationResultSupplier.java

@@ -0,0 +1,92 @@
+package com.microsoft.aad.msal4j;
+
+import lombok.Getter;
+import lombok.experimental.Accessors;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Exception type thrown when service returns an error response or other networking errors occur.
+ */
+@Accessors(fluent = true)
+@Getter
+public class AuthenticationServiceException extends AuthenticationException{
+
+    /**
+     * The protocol error code returned by the service
+     */
+    private String errorCode;
+
+    /**
+     * More specific error
+     */
+    private String subError;
+
+    /**
+     * Status code returned from http layer
+     */
+    private Integer statusCode;
+
+    /**
+     * Status message returned from the http layer
+     */
+    private String statusMessage;
+
+    /**
+     * An ID that can used to piece up a single authentication flow.
+     */
+    private String correlationId;
+
+    /**
+     * Claims included in the claims challenge
+     */
+    private String claims;
+
+    /**
+     * Contains the http headers from the server response that indicated an error.
+     * When the server returns a 429 Too Many Requests error, a Retry-After should be set.
+     * It is important to read and respect the time specified in the Retry-After header
+     */
+    private Map<String, List<String>> headers;
+
+    /**
+     * Initializes a new instance of the exception class with a specified error message
+     * @param message the error message that explains the reason for the exception
+     */
+    public AuthenticationServiceException(final String message){
+        super(message);
+    }
+
+    /**
+     * Initializes a new instance of the exception class
+     * @param errorResponse response object contain information about error returned by server
+     * @param httpHeaders http headers from the server response
+     */
+    public AuthenticationServiceException(
+            final ErrorResponse errorResponse,
+            final Map<String, List<String>> httpHeaders) {
+
+        super(errorResponse.errorDescription);
+
+        this.errorCode = errorResponse.error();
+        this.statusCode = errorResponse.statusCode();
+        this.statusMessage = errorResponse.statusMessage();
+        this.subError = errorResponse.subError();
+        this.correlationId = errorResponse.correlation_id();
+        this.claims = errorResponse.claims();
+        this.headers =  httpHeaders;
+    }
+
+    /**
+     * Initializes a new instance of the exception class
+     * @param discoveryResponse response object from instance discovery network call
+     */
+    public AuthenticationServiceException(InstanceDiscoveryResponse discoveryResponse){
+
+        super(discoveryResponse.errorDescription());
+
+        this.errorCode = discoveryResponse.error();
+        this.correlationId = discoveryResponse.correlationId();
+    }
+}

src/main/java/com/microsoft/aad/msal4j/AuthenticationServiceException.java

@@ -61,7 +61,7 @@ static AuthorityType detectAuthorityType(URL authorityUrl) {
         final String path = authorityUrl.getPath().substring(1);
         if (StringHelper.isBlank(path)) {
             throw new IllegalArgumentException(
-                    AuthenticationErrorMessage.AUTHORITY_URI_INVALID_PATH);
+                    "authority Uri should have at least one segment in the path (i.e. https://<host>/<path>/...)");
         }
 
         final String firstPath = path.substring(0, path.indexOf("/"));
@@ -79,7 +79,7 @@ static AuthorityType detectAuthorityType(URL authorityUrl) {
     void validateAuthorityUrl() {
         if (!this.canonicalAuthorityUrl.getProtocol().equalsIgnoreCase("https")) {
             throw new IllegalArgumentException(
-                    AuthenticationErrorMessage.AUTHORITY_URI_INSECURE);
+                    "authority should use the 'https' scheme");
         }
 
         if (this.canonicalAuthorityUrl.toString().contains("#")) {