Add CacheRefreshReason to telemetry and metadata

Author: Avery-Dunn

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AcquireTokenSilentSupplier.java

@@ -57,7 +57,7 @@ AuthenticationResult execute() throws Exception {
 
             shouldRefresh = shouldRefresh(silentRequest.parameters(), res);
 
-            if (shouldRefresh || clientApplication.serviceBundle().getServerSideTelemetry().getCurrentRequest().cacheInfo() == CacheTelemetry.REFRESH_REFRESH_IN.telemetryValue) {
+            if (shouldRefresh) {
                 if (!StringHelper.isBlank(res.refreshToken())) {
                     //There are certain scenarios where the cached authority may differ from the client app's authority,
                     // such as when a request is instance aware. Unless overridden by SilentParameters.authorityUrl, the
@@ -66,7 +66,8 @@ AuthenticationResult execute() throws Exception {
                         requestAuthority = Authority.createAuthority(new URL(requestAuthority.authority().replace(requestAuthority.host(),
                                 res.account().environment())));
                     }
-                    res = makeRefreshRequest(res, requestAuthority);
+
+                    res = makeRefreshRequest(res, requestAuthority, clientApplication.serviceBundle().getServerSideTelemetry().getCurrentRequest().cacheInfo());
                 } else {
                     res = null;
                 }
@@ -81,13 +82,17 @@ AuthenticationResult execute() throws Exception {
         return res;
     }
 
-    private AuthenticationResult makeRefreshRequest(AuthenticationResult cachedResult,  Authority requestAuthority) throws Exception {
+    private AuthenticationResult makeRefreshRequest(AuthenticationResult cachedResult, Authority requestAuthority, CacheRefreshReason refreshReason) throws Exception {
+
         RefreshTokenRequest refreshTokenRequest = new RefreshTokenRequest(
                 RefreshTokenParameters.builder(silentRequest.parameters().scopes(), cachedResult.refreshToken()).build(),
                 silentRequest.application(),
                 silentRequest.requestContext(),
                 silentRequest);
 
+        //The ServiceBundle will have a new CurrentRequest object when the RefreshTokenRequest is made, so the telemetry value needs to be set again
+        setCacheTelemetry(refreshReason);
+
         AcquireTokenByAuthorizationGrantSupplier acquireTokenByAuthorisationGrantSupplier =
                 new AcquireTokenByAuthorizationGrantSupplier(clientApplication, refreshTokenRequest, requestAuthority);
 
@@ -101,7 +106,7 @@ private AuthenticationResult makeRefreshRequest(AuthenticationResult cachedResul
         } catch (MsalServiceException ex) {
             //If the token refresh attempt threw a MsalServiceException but the refresh attempt was done
             // only because of refreshOn, then simply return the existing cached token rather than throw an exception
-            if (clientApplication.serviceBundle().getServerSideTelemetry().getCurrentRequest().cacheInfo() == CacheTelemetry.REFRESH_REFRESH_IN.telemetryValue) {
+            if (refreshReason == CacheRefreshReason.PROACTIVE_REFRESH) {
                 return cachedResult;
             }
             throw ex;
@@ -113,15 +118,15 @@ private boolean shouldRefresh(SilentParameters parameters, AuthenticationResult
 
         //If forceRefresh is true, no reason to check any other option
         if (parameters.forceRefresh()) {
-            setCacheTelemetry(CacheTelemetry.REFRESH_FORCE_REFRESH.telemetryValue);
+            setCacheTelemetry(CacheRefreshReason.FORCE_REFRESH);
             log.debug("Refreshing access token because forceRefresh parameter is true.");
             return true;
         }
 
         //If the request contains claims then the token should be refreshed, to ensure that the returned token has the correct claims
         //  Note: these are the types of claims found in (for example) a claims challenge, and do not include client capabilities
         if (parameters.claims() != null) {
-            setCacheTelemetry(CacheTelemetry.REFRESH_FORCE_REFRESH.telemetryValue);
+            setCacheTelemetry(CacheRefreshReason.FORCE_REFRESH);
             log.debug("Refreshing access token because the claims parameter is not null.");
             return true;
         }
@@ -130,7 +135,7 @@ private boolean shouldRefresh(SilentParameters parameters, AuthenticationResult
 
         //If the access token is expired or within 5 minutes of becoming expired, refresh it
         if (!StringHelper.isBlank(cachedResult.accessToken()) && cachedResult.expiresOn() < (currTimeStampSec + ACCESS_TOKEN_EXPIRE_BUFFER_IN_SEC)) {
-            setCacheTelemetry(CacheTelemetry.REFRESH_ACCESS_TOKEN_EXPIRED.telemetryValue);
+            setCacheTelemetry(CacheRefreshReason.EXPIRED);
             log.debug("Refreshing access token because it is expired.");
             return true;
         }
@@ -139,22 +144,22 @@ private boolean shouldRefresh(SilentParameters parameters, AuthenticationResult
         if (!StringHelper.isBlank(cachedResult.accessToken()) &&
                 cachedResult.refreshOn() != null && cachedResult.refreshOn() > 0 &&
                 cachedResult.refreshOn() < currTimeStampSec && cachedResult.expiresOn() >= (currTimeStampSec + ACCESS_TOKEN_EXPIRE_BUFFER_IN_SEC)){
-            setCacheTelemetry(CacheTelemetry.REFRESH_REFRESH_IN.telemetryValue);
+            setCacheTelemetry(CacheRefreshReason.PROACTIVE_REFRESH);
             log.debug("Attempting to refresh access token because it is after the refreshOn time.");
             return true;
         }
 
         //If there is a refresh token but no access token, we should use the refresh token to get the access token
         if (StringHelper.isBlank(cachedResult.accessToken()) && !StringHelper.isBlank(cachedResult.refreshToken())) {
-            setCacheTelemetry(CacheTelemetry.REFRESH_NO_ACCESS_TOKEN.telemetryValue);
+            setCacheTelemetry(CacheRefreshReason.NO_CACHED_ACCESS_TOKEN);
             log.debug("Refreshing access token because it was missing from the cache.");
             return true;
         }
 
         return false;
     }
 
-    private void setCacheTelemetry(int cacheInfoValue){
+    private void setCacheTelemetry(CacheRefreshReason cacheInfoValue){
         clientApplication.serviceBundle().getServerSideTelemetry().getCurrentRequest().cacheInfo(cacheInfoValue);
     }
 }

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/AuthenticationResultMetadata.java

@@ -20,6 +20,19 @@
 @Builder
 public class AuthenticationResultMetadata implements Serializable {
 
+    /**
+     * The source of the tokens in the {@link AuthenticationResult}, see {@link TokenSource} for possible values
+     */
     private TokenSource tokenSource;
+
+    /**
+     * When the token should be proactively refreshed. May be null or 0 if proactive refresh is not used
+     */
     private Long refreshOn;
+
+    /**
+     * Specifies the reason for refreshing a token, see {@link CacheRefreshReason} for possible values.Will be {@link CacheRefreshReason#NOT_APPLICABLE} if the token was not refreshed
+     */
+    @Builder.Default
+    private CacheRefreshReason cacheRefreshReason = CacheRefreshReason.NOT_APPLICABLE;
 }

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/CacheRefreshReason.java

@@ -0,0 +1,36 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+package com.microsoft.aad.msal4j;
+
+/**
+ * Specifies the reason for fetching the access token from the identity provider when using {@link AbstractClientApplicationBase#acquireTokenSilently(SilentParameters)}
+ */
+public enum CacheRefreshReason {
+    /**
+     * Token did not need to be refreshed, or was retrieved in a non-silent call
+     */
+    NOT_APPLICABLE(0),
+    /**
+     * Silent call was made with the force refresh option
+     */
+    FORCE_REFRESH(1),
+    /**
+     * Access token was missing from the cache, but a valid refresh token was used to retrieve a new access token
+     */
+    NO_CACHED_ACCESS_TOKEN(2),
+    /**
+     * Cached access token was expired and successfully refreshed
+     */
+    EXPIRED(3),
+    /**
+     * Cached access token was not expired but was after the 'refresh_in' value, and was proactively refreshed before the expiration date
+     */
+    PROACTIVE_REFRESH(4);
+
+    final int telemetryValue;
+
+    CacheRefreshReason(int telemetryValue) {
+        this.telemetryValue = telemetryValue;
+    }
+}

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/CacheTelemetry.java

@@ -14,7 +14,7 @@ class CurrentRequest {
     private final PublicApi publicApi;
 
     @Setter
-    private int cacheInfo = -1;
+    private CacheRefreshReason cacheInfo = CacheRefreshReason.NOT_APPLICABLE;
 
     @Setter
     private String regionUsed = StringHelper.EMPTY_STRING;

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/CurrentRequest.java

@@ -67,7 +67,7 @@ private synchronized String buildCurrentRequestHeader() {
         String currentRequestHeader = SCHEMA_VERSION + SCHEMA_PIPE_DELIMITER +
                 currentRequest.publicApi().getApiId() +
                 SCHEMA_COMMA_DELIMITER +
-                (currentRequest.cacheInfo() == -1 ? "" : currentRequest.cacheInfo()) +
+                currentRequest.cacheInfo().telemetryValue +
                 SCHEMA_COMMA_DELIMITER +
                 currentRequest.regionUsed() +
                 SCHEMA_COMMA_DELIMITER +

msal4j-sdk/src/main/java/com/microsoft/aad/msal4j/ServerSideTelemetry.java

@@ -32,7 +32,7 @@ class SilentRequest extends MsalRequest {
 
         if (parameters.forceRefresh()) {
             application.serviceBundle().getServerSideTelemetry().getCurrentRequest().cacheInfo(
-                    CacheTelemetry.REFRESH_FORCE_REFRESH.telemetryValue);
+                    CacheRefreshReason.FORCE_REFRESH);
         }
     }
 }