@azure/msal-common 14.0.1 → 14.0.3

package/src/cache/entities/CacheRecord.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { IdTokenEntity } from "./IdTokenEntity";
+import { AccessTokenEntity } from "./AccessTokenEntity";
+import { RefreshTokenEntity } from "./RefreshTokenEntity";
+import { AccountEntity } from "./AccountEntity";
+import { AppMetadataEntity } from "./AppMetadataEntity";
+
+/** @internal */
+export class CacheRecord {
+    account: AccountEntity | null;
+    idToken: IdTokenEntity | null;
+    accessToken: AccessTokenEntity | null;
+    refreshToken: RefreshTokenEntity | null;
+    appMetadata: AppMetadataEntity | null;
+
+    constructor(
+        accountEntity?: AccountEntity | null,
+        idTokenEntity?: IdTokenEntity | null,
+        accessTokenEntity?: AccessTokenEntity | null,
+        refreshTokenEntity?: RefreshTokenEntity | null,
+        appMetadataEntity?: AppMetadataEntity | null
+    ) {
+        this.account = accountEntity || null;
+        this.idToken = idTokenEntity || null;
+        this.accessToken = accessTokenEntity || null;
+        this.refreshToken = refreshTokenEntity || null;
+        this.appMetadata = appMetadataEntity || null;
+    }
+}

package/src/cache/entities/CredentialEntity.ts

@@ -0,0 +1,215 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    Separators,
+    CredentialType,
+    CacheType,
+    Constants,
+    AuthenticationScheme,
+} from "../../utils/Constants";
+import { ClientAuthError } from "../../error/ClientAuthError";
+
+/**
+ * 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
+ * }
+ */
+export class CredentialEntity {
+    homeAccountId: string;
+    environment: string;
+    credentialType: CredentialType;
+    clientId: string;
+    secret: string;
+    familyId?: string;
+    realm?: string;
+    target?: string;
+    userAssertionHash?: string;
+    tokenType?: AuthenticationScheme;
+    keyId?: string;
+    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 ClientAuthError.createUnexpectedCredentialTypeError();
+            }
+        }
+    }
+
+    /**
+     * 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

@@ -0,0 +1,74 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+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
+ * }
+ */
+export class IdTokenEntity extends CredentialEntity {
+    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

@@ -0,0 +1,78 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+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.
+ * }
+ */
+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
+        );
+    }
+}

package/src/cache/entities/ServerTelemetryEntity.ts

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { SERVER_TELEM_CONSTANTS } from "../../utils/Constants";
+
+export class ServerTelemetryEntity {
+    failedRequests: Array<string | number>;
+    errors: string[];
+    cacheHits: number;
+
+    constructor() {
+        this.failedRequests = [];
+        this.errors = [];
+        this.cacheHits = 0;
+    }
+
+    /**
+     * validates if a given cache entry is "Telemetry", parses <key,value>
+     * @param key
+     * @param entity
+     */
+    static isServerTelemetryEntity(key: string, entity?: object): boolean {
+        const validateKey: boolean =
+            key.indexOf(SERVER_TELEM_CONSTANTS.CACHE_KEY) === 0;
+        let validateEntity: boolean = true;
+
+        if (entity) {
+            validateEntity =
+                entity.hasOwnProperty("failedRequests") &&
+                entity.hasOwnProperty("errors") &&
+                entity.hasOwnProperty("cacheHits");
+        }
+
+        return validateKey && validateEntity;
+    }
+}

package/src/cache/entities/ThrottlingEntity.ts

@@ -0,0 +1,36 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { ThrottlingConstants } from "../../utils/Constants";
+
+export class ThrottlingEntity {
+    // Unix-time value representing the expiration of the throttle
+    throttleTime: number;
+    // Information provided by the server
+    error?: string;
+    errorCodes?: Array<string>;
+    errorMessage?: string;
+    subError?: string;
+
+    /**
+     * validates if a given cache entry is "Throttling", parses <key,value>
+     * @param key
+     * @param entity
+     */
+    static isThrottlingEntity(key: string, entity?: object): boolean {
+        let validateKey: boolean = false;
+        if (key) {
+            validateKey =
+                key.indexOf(ThrottlingConstants.THROTTLING_PREFIX) === 0;
+        }
+
+        let validateEntity: boolean = true;
+        if (entity) {
+            validateEntity = entity.hasOwnProperty("throttleTime");
+        }
+
+        return validateKey && validateEntity;
+    }
+}

package/src/cache/interface/ICacheManager.ts

@@ -0,0 +1,218 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { AccountFilter } from "../utils/CacheTypes";
+import { CacheRecord } from "../entities/CacheRecord";
+import { AccountEntity } from "../entities/AccountEntity";
+import { AccountInfo } from "../../account/AccountInfo";
+import { AppMetadataEntity } from "../entities/AppMetadataEntity";
+import { ServerTelemetryEntity } from "../entities/ServerTelemetryEntity";
+import { ThrottlingEntity } from "../entities/ThrottlingEntity";
+import { IdTokenEntity } from "../entities/IdTokenEntity";
+import { AccessTokenEntity } from "../entities/AccessTokenEntity";
+import { RefreshTokenEntity } from "../entities/RefreshTokenEntity";
+import { AuthorityMetadataEntity } from "../entities/AuthorityMetadataEntity";
+import { StoreInCache } from "../../request/StoreInCache";
+
+export interface ICacheManager {
+    /**
+     * fetch the account entity from the platform cache
+     * @param accountKey
+     */
+    getAccount(accountKey: string): AccountEntity | null;
+
+    /**
+     * set account entity in the platform cache
+     * @param account
+     */
+    setAccount(account: AccountEntity): void;
+
+    /**
+     * Returns true if the given key matches our account key schema. Also matches homeAccountId and/or tenantId if provided
+     * @param key
+     * @param homeAccountId
+     * @param tenantId
+     * @returns
+     */
+    isAccountKey(
+        key: string,
+        homeAccountId?: string,
+        tenantId?: string
+    ): boolean;
+
+    /**
+     * fetch the idToken entity from the platform cache
+     * @param idTokenKey
+     */
+    getIdTokenCredential(idTokenKey: string): IdTokenEntity | null;
+
+    /**
+     * set idToken entity to the platform cache
+     * @param idToken
+     */
+    setIdTokenCredential(idToken: IdTokenEntity): void;
+
+    /**
+     * fetch the idToken entity from the platform cache
+     * @param accessTokenKey
+     */
+    getAccessTokenCredential(accessTokenKey: string): AccessTokenEntity | null;
+
+    /**
+     * set idToken entity to the platform cache
+     * @param accessToken
+     */
+    setAccessTokenCredential(accessToken: AccessTokenEntity): void;
+
+    /**
+     * fetch the idToken entity from the platform cache
+     * @param refreshTokenKey
+     */
+    getRefreshTokenCredential(
+        refreshTokenKey: string
+    ): RefreshTokenEntity | null;
+
+    /**
+     * set idToken entity to the platform cache
+     * @param refreshToken
+     */
+    setRefreshTokenCredential(refreshToken: RefreshTokenEntity): void;
+
+    /**
+     * fetch appMetadata entity from the platform cache
+     * @param appMetadataKey
+     */
+    getAppMetadata(appMetadataKey: string): AppMetadataEntity | null;
+
+    /**
+     * set appMetadata entity to the platform cache
+     * @param appMetadata
+     */
+    setAppMetadata(appMetadata: AppMetadataEntity): void;
+
+    /**
+     * fetch server telemetry entity from the platform cache
+     * @param serverTelemetryKey
+     */
+    getServerTelemetry(
+        serverTelemetryKey: string
+    ): ServerTelemetryEntity | null;
+
+    /**
+     * set server telemetry entity to the platform cache
+     * @param serverTelemetryKey
+     * @param serverTelemetry
+     */
+    setServerTelemetry(
+        serverTelemetryKey: string,
+        serverTelemetry: ServerTelemetryEntity
+    ): void;
+
+    /**
+     * fetch cloud discovery metadata entity from the platform cache
+     * @param key
+     */
+    getAuthorityMetadata(key: string): AuthorityMetadataEntity | null;
+
+    /**
+     * Get cache keys for authority metadata
+     */
+    getAuthorityMetadataKeys(): Array<string>;
+
+    /**
+     * set cloud discovery metadata entity to the platform cache
+     * @param key
+     * @param value
+     */
+    setAuthorityMetadata(key: string, value: AuthorityMetadataEntity): void;
+
+    /**
+     * Provide an alias to find a matching AuthorityMetadataEntity in cache
+     * @param host
+     */
+    getAuthorityMetadataByAlias(host: string): AuthorityMetadataEntity | null;
+
+    /**
+     * given an authority generates the cache key for authorityMetadata
+     * @param authority
+     */
+    generateAuthorityMetadataCacheKey(authority: string): string;
+
+    /**
+     * fetch throttling entity from the platform cache
+     * @param throttlingCacheKey
+     */
+    getThrottlingCache(throttlingCacheKey: string): ThrottlingEntity | null;
+
+    /**
+     * set throttling entity to the platform cache
+     * @param throttlingCacheKey
+     * @param throttlingCache
+     */
+    setThrottlingCache(
+        throttlingCacheKey: string,
+        throttlingCache: ThrottlingEntity
+    ): void;
+
+    /**
+     * Returns all accounts in cache
+     */
+    getAllAccounts(): AccountInfo[];
+
+    /**
+     * saves a cache record
+     * @param cacheRecord
+     */
+    saveCacheRecord(
+        cacheRecord: CacheRecord,
+        storeInCache?: StoreInCache
+    ): Promise<void>;
+
+    /**
+     * retrieve accounts matching all provided filters; if no filter is set, get all accounts
+     * @param homeAccountId
+     * @param environment
+     * @param realm
+     */
+    getAccountsFilteredBy(filter: AccountFilter): AccountEntity[];
+
+    /**
+     * Get AccountInfo object based on provided filters
+     * @param filter
+     */
+    getAccountInfoFilteredBy(filter: AccountFilter): AccountInfo | null;
+
+    /**
+     * Removes all accounts and related tokens from cache.
+     */
+    removeAllAccounts(): Promise<void>;
+
+    /**
+     * returns a boolean if the given account is removed
+     * @param account
+     */
+    removeAccount(accountKey: string): Promise<void>;
+
+    /**
+     * returns a boolean if the given account is removed
+     * @param account
+     */
+    removeAccountContext(account: AccountEntity): Promise<void>;
+
+    /**
+     * @param key
+     */
+    removeIdToken(key: string): void;
+
+    /**
+     * @param key
+     */
+    removeAccessToken(key: string): Promise<void>;
+
+    /**
+     * @param key
+     */
+    removeRefreshToken(key: string): void;
+}

package/src/cache/interface/ICachePlugin.ts

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { TokenCacheContext } from "../persistence/TokenCacheContext";
+
+export interface ICachePlugin {
+    beforeCacheAccess: (tokenCacheContext: TokenCacheContext) => Promise<void>;
+    afterCacheAccess: (tokenCacheContext: TokenCacheContext) => Promise<void>;
+}