@azure/msal-common 14.1.0 → 14.3.0

package/src/cache/entities/CredentialEntity.ts

@@ -3,218 +3,34 @@
  * Licensed under the MIT License.
  */
 
-import {
-    Separators,
-    CredentialType,
-    CacheType,
-    Constants,
-    AuthenticationScheme,
-} from "../../utils/Constants";
-import {
-    ClientAuthErrorCodes,
-    createClientAuthError,
-} from "../../error/ClientAuthError";
+import { CredentialType, AuthenticationScheme } from "../../utils/Constants";
 
 /**
- * Base type for credentials to be stored in the cache: eg: ACCESS_TOKEN, ID_TOKEN etc
- *
- * Key:Value Schema:
- *
- * Key: <home_account_id*>-<environment>-<credential_type>-<client_id>-<realm*>-<target*>-<requestedClaims*>-<scheme*>
- *
- * Value Schema:
- * {
- *      homeAccountId: home account identifier for the auth scheme,
- *      environment: entity that issued the token, represented as a full host
- *      credentialType: Type of credential as a string, can be one of the following: RefreshToken, AccessToken, IdToken, Password, Cookie, Certificate, Other
- *      clientId: client ID of the application
- *      secret: Actual credential as a string
- *      familyId: Family ID identifier, usually only used for refresh tokens
- *      realm: Full tenant or organizational identifier that the account belongs to
- *      target: Permissions that are included in the token, or for refresh tokens, the resource identifier.
- *      tokenType: Matches the authentication scheme for which the token was issued (i.e. Bearer or pop)
- *      requestedClaimsHash: Matches the SHA 256 hash of the claims object included in the token request
- *      userAssertionHash: Matches the SHA 256 hash of the obo_assertion for the OBO flow
- * }
+ * Credential Cache Type
  */
-export class CredentialEntity {
+export type CredentialEntity = {
+    /** Identifier for the user in their home tenant*/
     homeAccountId: string;
+    /** Entity that issued the token, represented as a full host */
     environment: string;
+    /** Type of credential */
     credentialType: CredentialType;
+    /** Client ID of the application */
     clientId: string;
+    /** Actual credential as a string */
     secret: string;
+    /** Family ID identifier, usually only used for refresh tokens */
     familyId?: string;
+    /** Full tenant or organizational identifier that the account belongs to */
     realm?: string;
+    /** Permissions that are included in the token, or for refresh tokens, the resource identifier. */
     target?: string;
+    /** Matches the SHA 256 hash of the obo_assertion for the OBO flow */
     userAssertionHash?: string;
+    /** Matches the authentication scheme for which the token was issued (i.e. Bearer or pop) */
     tokenType?: AuthenticationScheme;
+    /** KeyId for PoP and SSH tokens stored in the kid claim */
     keyId?: string;
+    /** Matches the SHA 256 hash of the claims object included in the token request */
     requestedClaimsHash?: string;
-
-    /**
-     * Generate Account Id key component as per the schema: <home_account_id>-<environment>
-     */
-    generateAccountId(): string {
-        return CredentialEntity.generateAccountIdForCacheKey(
-            this.homeAccountId,
-            this.environment
-        );
-    }
-
-    /**
-     * Generate Credential Id key component as per the schema: <credential_type>-<client_id>-<realm>
-     */
-    generateCredentialId(): string {
-        return CredentialEntity.generateCredentialIdForCacheKey(
-            this.credentialType,
-            this.clientId,
-            this.realm,
-            this.familyId
-        );
-    }
-
-    /**
-     * Generate target key component as per schema: <target>
-     */
-    generateTarget(): string {
-        return CredentialEntity.generateTargetForCacheKey(this.target);
-    }
-
-    /**
-     * generates credential key
-     */
-    generateCredentialKey(): string {
-        return CredentialEntity.generateCredentialCacheKey(
-            this.homeAccountId,
-            this.environment,
-            this.credentialType,
-            this.clientId,
-            this.realm,
-            this.target,
-            this.familyId,
-            this.tokenType,
-            this.requestedClaimsHash
-        );
-    }
-
-    /**
-     * returns the type of the cache (in this case credential)
-     */
-    generateType(): number {
-        switch (this.credentialType) {
-            case CredentialType.ID_TOKEN:
-                return CacheType.ID_TOKEN;
-            case CredentialType.ACCESS_TOKEN:
-            case CredentialType.ACCESS_TOKEN_WITH_AUTH_SCHEME:
-                return CacheType.ACCESS_TOKEN;
-            case CredentialType.REFRESH_TOKEN:
-                return CacheType.REFRESH_TOKEN;
-            default: {
-                throw createClientAuthError(
-                    ClientAuthErrorCodes.unexpectedCredentialType
-                );
-            }
-        }
-    }
-
-    /**
-     * generates credential key
-     * <home_account_id*>-\<environment>-<credential_type>-<client_id>-<realm\*>-<target\*>-<scheme\*>
-     */
-    static generateCredentialCacheKey(
-        homeAccountId: string,
-        environment: string,
-        credentialType: CredentialType,
-        clientId: string,
-        realm?: string,
-        target?: string,
-        familyId?: string,
-        tokenType?: AuthenticationScheme,
-        requestedClaimsHash?: string
-    ): string {
-        const credentialKey = [
-            this.generateAccountIdForCacheKey(homeAccountId, environment),
-            this.generateCredentialIdForCacheKey(
-                credentialType,
-                clientId,
-                realm,
-                familyId
-            ),
-            this.generateTargetForCacheKey(target),
-            this.generateClaimsHashForCacheKey(requestedClaimsHash),
-            this.generateSchemeForCacheKey(tokenType),
-        ];
-
-        return credentialKey.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
-    }
-
-    /**
-     * generates Account Id for keys
-     * @param homeAccountId
-     * @param environment
-     */
-    private static generateAccountIdForCacheKey(
-        homeAccountId: string,
-        environment: string
-    ): string {
-        const accountId: Array<string> = [homeAccountId, environment];
-        return accountId.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
-    }
-
-    /**
-     * Generates Credential Id for keys
-     * @param credentialType
-     * @param realm
-     * @param clientId
-     * @param familyId
-     */
-    private static generateCredentialIdForCacheKey(
-        credentialType: CredentialType,
-        clientId: string,
-        realm?: string,
-        familyId?: string
-    ): string {
-        const clientOrFamilyId =
-            credentialType === CredentialType.REFRESH_TOKEN
-                ? familyId || clientId
-                : clientId;
-        const credentialId: Array<string> = [
-            credentialType,
-            clientOrFamilyId,
-            realm || Constants.EMPTY_STRING,
-        ];
-
-        return credentialId.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
-    }
-
-    /**
-     * Generate target key component as per schema: <target>
-     */
-    private static generateTargetForCacheKey(scopes?: string): string {
-        return (scopes || Constants.EMPTY_STRING).toLowerCase();
-    }
-
-    /**
-     * Generate requested claims key component as per schema: <requestedClaims>
-     */
-    private static generateClaimsHashForCacheKey(
-        requestedClaimsHash?: string
-    ): string {
-        return (requestedClaimsHash || Constants.EMPTY_STRING).toLowerCase();
-    }
-
-    /**
-     * Generate scheme key componenet as per schema: <scheme>
-     */
-    private static generateSchemeForCacheKey(tokenType?: string): string {
-        /*
-         * PoP Tokens and SSH certs include scheme in cache key
-         * Cast to lowercase to handle "bearer" from ADFS
-         */
-        return tokenType &&
-            tokenType.toLowerCase() !==
-                AuthenticationScheme.BEARER.toLowerCase()
-            ? tokenType.toLowerCase()
-            : Constants.EMPTY_STRING;
-    }
-}
+};

package/src/cache/entities/IdTokenEntity.ts

@@ -4,71 +4,11 @@
  */
 
 import { CredentialEntity } from "./CredentialEntity";
-import { CredentialType } from "../../utils/Constants";
 
 /**
- * ID_TOKEN Cache
- *
- * Key:Value Schema:
- *
- * Key Example: uid.utid-login.microsoftonline.com-idtoken-clientId-contoso.com-
- *
- * Value Schema:
- * {
- *      homeAccountId: home account identifier for the auth scheme,
- *      environment: entity that issued the token, represented as a full host
- *      credentialType: Type of credential as a string, can be one of the following: RefreshToken, AccessToken, IdToken, Password, Cookie, Certificate, Other
- *      clientId: client ID of the application
- *      secret: Actual credential as a string
- *      realm: Full tenant or organizational identifier that the account belongs to
- * }
+ * Id Token Cache Type
  */
-export class IdTokenEntity extends CredentialEntity {
+export type IdTokenEntity = CredentialEntity & {
+    /**  Full tenant or organizational identifier that the account belongs to */
     realm: string;
-
-    /**
-     * Create IdTokenEntity
-     * @param homeAccountId
-     * @param authenticationResult
-     * @param clientId
-     * @param authority
-     */
-    static createIdTokenEntity(
-        homeAccountId: string,
-        environment: string,
-        idToken: string,
-        clientId: string,
-        tenantId: string
-    ): IdTokenEntity {
-        const idTokenEntity = new IdTokenEntity();
-
-        idTokenEntity.credentialType = CredentialType.ID_TOKEN;
-        idTokenEntity.homeAccountId = homeAccountId;
-        idTokenEntity.environment = environment;
-        idTokenEntity.clientId = clientId;
-        idTokenEntity.secret = idToken;
-        idTokenEntity.realm = tenantId;
-
-        return idTokenEntity;
-    }
-
-    /**
-     * Validates an entity: checks for all expected params
-     * @param entity
-     */
-    static isIdTokenEntity(entity: object): boolean {
-        if (!entity) {
-            return false;
-        }
-
-        return (
-            entity.hasOwnProperty("homeAccountId") &&
-            entity.hasOwnProperty("environment") &&
-            entity.hasOwnProperty("credentialType") &&
-            entity.hasOwnProperty("realm") &&
-            entity.hasOwnProperty("clientId") &&
-            entity.hasOwnProperty("secret") &&
-            entity["credentialType"] === CredentialType.ID_TOKEN
-        );
-    }
-}
+};

package/src/cache/entities/RefreshTokenEntity.ts

@@ -4,75 +4,8 @@
  */
 
 import { CredentialEntity } from "./CredentialEntity";
-import { CredentialType } from "../../utils/Constants";
 
 /**
- * REFRESH_TOKEN Cache
- *
- * Key:Value Schema:
- *
- * Key Example: uid.utid-login.microsoftonline.com-refreshtoken-clientId--
- *
- * Value:
- * {
- *      homeAccountId: home account identifier for the auth scheme,
- *      environment: entity that issued the token, represented as a full host
- *      credentialType: Type of credential as a string, can be one of the following: RefreshToken, AccessToken, IdToken, Password, Cookie, Certificate, Other
- *      clientId: client ID of the application
- *      secret: Actual credential as a string
- *      familyId: Family ID identifier, '1' represents Microsoft Family
- *      realm: Full tenant or organizational identifier that the account belongs to
- *      target: Permissions that are included in the token, or for refresh tokens, the resource identifier.
- * }
+ * Refresh Token Cache Type
  */
-export class RefreshTokenEntity extends CredentialEntity {
-    familyId?: string;
-
-    /**
-     * Create RefreshTokenEntity
-     * @param homeAccountId
-     * @param authenticationResult
-     * @param clientId
-     * @param authority
-     */
-    static createRefreshTokenEntity(
-        homeAccountId: string,
-        environment: string,
-        refreshToken: string,
-        clientId: string,
-        familyId?: string,
-        userAssertionHash?: string
-    ): RefreshTokenEntity {
-        const rtEntity = new RefreshTokenEntity();
-
-        rtEntity.clientId = clientId;
-        rtEntity.credentialType = CredentialType.REFRESH_TOKEN;
-        rtEntity.environment = environment;
-        rtEntity.homeAccountId = homeAccountId;
-        rtEntity.secret = refreshToken;
-        rtEntity.userAssertionHash = userAssertionHash;
-
-        if (familyId) rtEntity.familyId = familyId;
-
-        return rtEntity;
-    }
-
-    /**
-     * Validates an entity: checks for all expected params
-     * @param entity
-     */
-    static isRefreshTokenEntity(entity: object): boolean {
-        if (!entity) {
-            return false;
-        }
-
-        return (
-            entity.hasOwnProperty("homeAccountId") &&
-            entity.hasOwnProperty("environment") &&
-            entity.hasOwnProperty("credentialType") &&
-            entity.hasOwnProperty("clientId") &&
-            entity.hasOwnProperty("secret") &&
-            entity["credentialType"] === CredentialType.REFRESH_TOKEN
-        );
-    }
-}
+export type RefreshTokenEntity = CredentialEntity;

package/src/cache/utils/CacheHelpers.ts

@@ -0,0 +1,306 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { extractTokenClaims } from "../../account/AuthToken";
+import { TokenClaims } from "../../account/TokenClaims";
+import {
+    ClientAuthErrorCodes,
+    createClientAuthError,
+} from "../../error/ClientAuthError";
+import {
+    AuthenticationScheme,
+    CredentialType,
+    Separators,
+} from "../../utils/Constants";
+import { TimeUtils } from "../../utils/TimeUtils";
+import { AccessTokenEntity } from "../entities/AccessTokenEntity";
+import { CredentialEntity } from "../entities/CredentialEntity";
+import { IdTokenEntity } from "../entities/IdTokenEntity";
+import { RefreshTokenEntity } from "../entities/RefreshTokenEntity";
+
+/**
+ * Cache Key: <home_account_id>-<environment>-<credential_type>-<client_id or familyId>-<realm>-<scopes>-<claims hash>-<scheme>
+ * IdToken Example: uid.utid-login.microsoftonline.com-idtoken-app_client_id-contoso.com
+ * AccessToken Example: uid.utid-login.microsoftonline.com-accesstoken-app_client_id-contoso.com-scope1 scope2--pop
+ * RefreshToken Example: uid.utid-login.microsoftonline.com-refreshtoken-1-contoso.com
+ * @param credentialEntity
+ * @returns
+ */
+export function generateCredentialKey(
+    credentialEntity: CredentialEntity
+): string {
+    const credentialKey = [
+        generateAccountId(credentialEntity),
+        generateCredentialId(credentialEntity),
+        generateTarget(credentialEntity),
+        generateClaimsHash(credentialEntity),
+        generateScheme(credentialEntity),
+    ];
+
+    return credentialKey.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
+}
+
+/**
+ * Create IdTokenEntity
+ * @param homeAccountId
+ * @param authenticationResult
+ * @param clientId
+ * @param authority
+ */
+export function createIdTokenEntity(
+    homeAccountId: string,
+    environment: string,
+    idToken: string,
+    clientId: string,
+    tenantId: string
+): IdTokenEntity {
+    const idTokenEntity: IdTokenEntity = {
+        credentialType: CredentialType.ID_TOKEN,
+        homeAccountId: homeAccountId,
+        environment: environment,
+        clientId: clientId,
+        secret: idToken,
+        realm: tenantId,
+    };
+
+    return idTokenEntity;
+}
+
+/**
+ * Create AccessTokenEntity
+ * @param homeAccountId
+ * @param environment
+ * @param accessToken
+ * @param clientId
+ * @param tenantId
+ * @param scopes
+ * @param expiresOn
+ * @param extExpiresOn
+ */
+export function createAccessTokenEntity(
+    homeAccountId: string,
+    environment: string,
+    accessToken: string,
+    clientId: string,
+    tenantId: string,
+    scopes: string,
+    expiresOn: number,
+    extExpiresOn: number,
+    base64Decode: (input: string) => string,
+    refreshOn?: number,
+    tokenType?: AuthenticationScheme,
+    userAssertionHash?: string,
+    keyId?: string,
+    requestedClaims?: string,
+    requestedClaimsHash?: string
+): AccessTokenEntity {
+    const atEntity: AccessTokenEntity = {
+        homeAccountId: homeAccountId,
+        credentialType: CredentialType.ACCESS_TOKEN,
+        secret: accessToken,
+        cachedAt: TimeUtils.nowSeconds().toString(),
+        expiresOn: expiresOn.toString(),
+        extendedExpiresOn: extExpiresOn.toString(),
+        environment: environment,
+        clientId: clientId,
+        realm: tenantId,
+        target: scopes,
+        tokenType: tokenType || AuthenticationScheme.BEARER,
+    };
+
+    if (userAssertionHash) {
+        atEntity.userAssertionHash = userAssertionHash;
+    }
+
+    if (refreshOn) {
+        atEntity.refreshOn = refreshOn.toString();
+    }
+
+    if (requestedClaims) {
+        atEntity.requestedClaims = requestedClaims;
+        atEntity.requestedClaimsHash = requestedClaimsHash;
+    }
+
+    /*
+     * Create Access Token With Auth Scheme instead of regular access token
+     * Cast to lower to handle "bearer" from ADFS
+     */
+    if (
+        atEntity.tokenType?.toLowerCase() !==
+        AuthenticationScheme.BEARER.toLowerCase()
+    ) {
+        atEntity.credentialType = CredentialType.ACCESS_TOKEN_WITH_AUTH_SCHEME;
+        switch (atEntity.tokenType) {
+            case AuthenticationScheme.POP:
+                // Make sure keyId is present and add it to credential
+                const tokenClaims: TokenClaims | null = extractTokenClaims(
+                    accessToken,
+                    base64Decode
+                );
+                if (!tokenClaims?.cnf?.kid) {
+                    throw createClientAuthError(
+                        ClientAuthErrorCodes.tokenClaimsCnfRequiredForSignedJwt
+                    );
+                }
+                atEntity.keyId = tokenClaims.cnf.kid;
+                break;
+            case AuthenticationScheme.SSH:
+                atEntity.keyId = keyId;
+        }
+    }
+
+    return atEntity;
+}
+
+/**
+ * Create RefreshTokenEntity
+ * @param homeAccountId
+ * @param authenticationResult
+ * @param clientId
+ * @param authority
+ */
+export function createRefreshTokenEntity(
+    homeAccountId: string,
+    environment: string,
+    refreshToken: string,
+    clientId: string,
+    familyId?: string,
+    userAssertionHash?: string
+): RefreshTokenEntity {
+    const rtEntity: RefreshTokenEntity = {
+        credentialType: CredentialType.REFRESH_TOKEN,
+        homeAccountId: homeAccountId,
+        environment: environment,
+        clientId: clientId,
+        secret: refreshToken,
+    };
+
+    if (userAssertionHash) {
+        rtEntity.userAssertionHash = userAssertionHash;
+    }
+
+    if (familyId) {
+        rtEntity.familyId = familyId;
+    }
+
+    return rtEntity;
+}
+
+export function isCredentialEntity(entity: object): boolean {
+    return (
+        entity.hasOwnProperty("homeAccountId") &&
+        entity.hasOwnProperty("environment") &&
+        entity.hasOwnProperty("credentialType") &&
+        entity.hasOwnProperty("clientId") &&
+        entity.hasOwnProperty("secret")
+    );
+}
+
+/**
+ * Validates an entity: checks for all expected params
+ * @param entity
+ */
+export function isAccessTokenEntity(entity: object): boolean {
+    if (!entity) {
+        return false;
+    }
+
+    return (
+        isCredentialEntity(entity) &&
+        entity.hasOwnProperty("realm") &&
+        entity.hasOwnProperty("target") &&
+        (entity["credentialType"] === CredentialType.ACCESS_TOKEN ||
+            entity["credentialType"] ===
+                CredentialType.ACCESS_TOKEN_WITH_AUTH_SCHEME)
+    );
+}
+
+/**
+ * Validates an entity: checks for all expected params
+ * @param entity
+ */
+export function isIdTokenEntity(entity: object): boolean {
+    if (!entity) {
+        return false;
+    }
+
+    return (
+        isCredentialEntity(entity) &&
+        entity.hasOwnProperty("realm") &&
+        entity["credentialType"] === CredentialType.ID_TOKEN
+    );
+}
+
+/**
+ * Validates an entity: checks for all expected params
+ * @param entity
+ */
+export function isRefreshTokenEntity(entity: object): boolean {
+    if (!entity) {
+        return false;
+    }
+
+    return (
+        isCredentialEntity(entity) &&
+        entity["credentialType"] === CredentialType.REFRESH_TOKEN
+    );
+}
+
+/**
+ * Generate Account Id key component as per the schema: <home_account_id>-<environment>
+ */
+function generateAccountId(credentialEntity: CredentialEntity): string {
+    const accountId: Array<string> = [
+        credentialEntity.homeAccountId,
+        credentialEntity.environment,
+    ];
+    return accountId.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
+}
+
+/**
+ * Generate Credential Id key component as per the schema: <credential_type>-<client_id>-<realm>
+ */
+function generateCredentialId(credentialEntity: CredentialEntity): string {
+    const clientOrFamilyId =
+        credentialEntity.credentialType === CredentialType.REFRESH_TOKEN
+            ? credentialEntity.familyId || credentialEntity.clientId
+            : credentialEntity.clientId;
+    const credentialId: Array<string> = [
+        credentialEntity.credentialType,
+        clientOrFamilyId,
+        credentialEntity.realm || "",
+    ];
+
+    return credentialId.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
+}
+
+/**
+ * Generate target key component as per schema: <target>
+ */
+function generateTarget(credentialEntity: CredentialEntity): string {
+    return (credentialEntity.target || "").toLowerCase();
+}
+
+/**
+ * Generate requested claims key component as per schema: <requestedClaims>
+ */
+function generateClaimsHash(credentialEntity: CredentialEntity): string {
+    return (credentialEntity.requestedClaimsHash || "").toLowerCase();
+}
+
+/**
+ * Generate scheme key componenet as per schema: <scheme>
+ */
+function generateScheme(credentialEntity: CredentialEntity): string {
+    /*
+     * PoP Tokens and SSH certs include scheme in cache key
+     * Cast to lowercase to handle "bearer" from ADFS
+     */
+    return credentialEntity.tokenType &&
+        credentialEntity.tokenType.toLowerCase() !==
+            AuthenticationScheme.BEARER.toLowerCase()
+        ? credentialEntity.tokenType.toLowerCase()
+        : "";
+}

package/src/cache/utils/CacheTypes.ts

@@ -59,6 +59,7 @@ export type AccountFilter = Omit<
 > & {
     realm?: string;
     loginHint?: string;
+    sid?: string;
 };
 
 /**