@azure/msal-common 14.0.1 → 14.0.3

package/src/cache/entities/AccessTokenEntity.ts

@@ -0,0 +1,162 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CredentialEntity } from "./CredentialEntity";
+import { CredentialType, AuthenticationScheme } from "../../utils/Constants";
+import { TimeUtils } from "../../utils/TimeUtils";
+import { ICrypto } from "../../crypto/ICrypto";
+import { TokenClaims } from "../../account/TokenClaims";
+import { ClientAuthError } from "../../error/ClientAuthError";
+import { extractTokenClaims } from "../../account/AuthToken";
+
+/**
+ * ACCESS_TOKEN Credential Type
+ *
+ * Key:Value Schema:
+ *
+ * Key Example: uid.utid-login.microsoftonline.com-accesstoken-clientId-contoso.com-user.read
+ *
+ * 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.
+ *      cachedAt: Absolute device time when entry was created in the cache.
+ *      expiresOn: Token expiry time, calculated based on current UTC time in seconds. Represented as a string.
+ *      extendedExpiresOn: Additional extended expiry time until when token is valid in case of server-side outage. Represented as string in UTC seconds.
+ *      keyId: used for POP and SSH tokenTypes
+ *      tokenType: Type of the token issued. Usually "Bearer"
+ * }
+ */
+export class AccessTokenEntity extends CredentialEntity {
+    realm: string;
+    target: string;
+    cachedAt: string;
+    expiresOn: string;
+    extendedExpiresOn?: string;
+    refreshOn?: string;
+    keyId?: string; // for POP and SSH tokenTypes
+    tokenType?: AuthenticationScheme;
+    requestedClaims?: string;
+    requestedClaimsHash?: string;
+
+    /**
+     * Create AccessTokenEntity
+     * @param homeAccountId
+     * @param environment
+     * @param accessToken
+     * @param clientId
+     * @param tenantId
+     * @param scopes
+     * @param expiresOn
+     * @param extExpiresOn
+     */
+    static createAccessTokenEntity(
+        homeAccountId: string,
+        environment: string,
+        accessToken: string,
+        clientId: string,
+        tenantId: string,
+        scopes: string,
+        expiresOn: number,
+        extExpiresOn: number,
+        cryptoUtils: ICrypto,
+        refreshOn?: number,
+        tokenType?: AuthenticationScheme,
+        userAssertionHash?: string,
+        keyId?: string,
+        requestedClaims?: string,
+        requestedClaimsHash?: string
+    ): AccessTokenEntity {
+        const atEntity: AccessTokenEntity = new AccessTokenEntity();
+
+        atEntity.homeAccountId = homeAccountId;
+        atEntity.credentialType = CredentialType.ACCESS_TOKEN;
+        atEntity.secret = accessToken;
+
+        const currentTime = TimeUtils.nowSeconds();
+        atEntity.cachedAt = currentTime.toString();
+
+        /*
+         * Token expiry time.
+         * This value should be  calculated based on the current UTC time measured locally and the value  expires_in Represented as a string in JSON.
+         */
+        atEntity.expiresOn = expiresOn.toString();
+        atEntity.extendedExpiresOn = extExpiresOn.toString();
+        if (refreshOn) {
+            atEntity.refreshOn = refreshOn.toString();
+        }
+
+        atEntity.environment = environment;
+        atEntity.clientId = clientId;
+        atEntity.realm = tenantId;
+        atEntity.target = scopes;
+        atEntity.userAssertionHash = userAssertionHash;
+
+        atEntity.tokenType = tokenType || AuthenticationScheme.BEARER;
+
+        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,
+                        cryptoUtils.base64Decode
+                    );
+                    if (!tokenClaims?.cnf?.kid) {
+                        throw ClientAuthError.createTokenClaimsRequiredError();
+                    }
+                    atEntity.keyId = tokenClaims.cnf.kid;
+                    break;
+                case AuthenticationScheme.SSH:
+                    atEntity.keyId = keyId;
+            }
+        }
+
+        return atEntity;
+    }
+
+    /**
+     * Validates an entity: checks for all expected params
+     * @param entity
+     */
+    static isAccessTokenEntity(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.hasOwnProperty("target") &&
+            (entity["credentialType"] === CredentialType.ACCESS_TOKEN ||
+                entity["credentialType"] ===
+                    CredentialType.ACCESS_TOKEN_WITH_AUTH_SCHEME)
+        );
+    }
+}

package/src/cache/entities/AccountEntity.ts

@@ -0,0 +1,309 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { Separators, CacheAccountType, Constants } from "../../utils/Constants";
+import { Authority } from "../../authority/Authority";
+import { ICrypto } from "../../crypto/ICrypto";
+import { buildClientInfo } from "../../account/ClientInfo";
+import { AccountInfo } from "../../account/AccountInfo";
+import { ClientAuthError } from "../../error/ClientAuthError";
+import { AuthorityType } from "../../authority/AuthorityType";
+import { Logger } from "../../logger/Logger";
+import { TokenClaims } from "../../account/TokenClaims";
+import { ProtocolMode } from "../../authority/ProtocolMode";
+
+/**
+ * Type that defines required and optional parameters for an Account field (based on universal cache schema implemented by all MSALs).
+ *
+ * Key : Value Schema
+ *
+ * Key: <home_account_id>-<environment>-<realm*>
+ *
+ * Value Schema:
+ * {
+ *      homeAccountId: home account identifier for the auth scheme,
+ *      environment: entity that issued the token, represented as a full host
+ *      realm: Full tenant or organizational identifier that the account belongs to
+ *      localAccountId: Original tenant-specific accountID, usually used for legacy cases
+ *      username: primary username that represents the user, usually corresponds to preferred_username in the v2 endpt
+ *      authorityType: Accounts authority type as a string
+ *      name: Full name for the account, including given name and family name,
+ *      lastModificationTime: last time this entity was modified in the cache
+ *      lastModificationApp:
+ *      idTokenClaims: Object containing claims parsed from ID token
+ *      nativeAccountId: Account identifier on the native device
+ * }
+ * @internal
+ */
+export class AccountEntity {
+    homeAccountId: string;
+    environment: string;
+    realm: string;
+    localAccountId: string;
+    username: string;
+    authorityType: string;
+    clientInfo?: string;
+    name?: string;
+    lastModificationTime?: string;
+    lastModificationApp?: string;
+    cloudGraphHostName?: string;
+    msGraphHost?: string;
+    idTokenClaims?: TokenClaims;
+    nativeAccountId?: string;
+
+    /**
+     * Generate Account Id key component as per the schema: <home_account_id>-<environment>
+     */
+    generateAccountId(): string {
+        const accountId: Array<string> = [this.homeAccountId, this.environment];
+        return accountId.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
+    }
+
+    /**
+     * Generate Account Cache Key as per the schema: <home_account_id>-<environment>-<realm*>
+     */
+    generateAccountKey(): string {
+        return AccountEntity.generateAccountCacheKey({
+            homeAccountId: this.homeAccountId,
+            environment: this.environment,
+            tenantId: this.realm,
+            username: this.username,
+            localAccountId: this.localAccountId,
+        });
+    }
+
+    /**
+     * Returns the AccountInfo interface for this account.
+     */
+    getAccountInfo(): AccountInfo {
+        return {
+            homeAccountId: this.homeAccountId,
+            environment: this.environment,
+            tenantId: this.realm,
+            username: this.username,
+            localAccountId: this.localAccountId,
+            name: this.name,
+            idTokenClaims: this.idTokenClaims,
+            nativeAccountId: this.nativeAccountId,
+            authorityType: this.authorityType,
+        };
+    }
+
+    /**
+     * Generates account key from interface
+     * @param accountInterface
+     */
+    static generateAccountCacheKey(accountInterface: AccountInfo): string {
+        const accountKey = [
+            accountInterface.homeAccountId,
+            accountInterface.environment || Constants.EMPTY_STRING,
+            accountInterface.tenantId || Constants.EMPTY_STRING,
+        ];
+
+        return accountKey.join(Separators.CACHE_KEY_SEPARATOR).toLowerCase();
+    }
+
+    /**
+     * Build Account cache from IdToken, clientInfo and authority/policy. Associated with AAD.
+     * @param accountDetails
+     */
+    static createAccount(
+        accountDetails: {
+            homeAccountId: string;
+            idTokenClaims: TokenClaims;
+            clientInfo?: string;
+            cloudGraphHostName?: string;
+            msGraphHost?: string;
+            environment?: string;
+            nativeAccountId?: string;
+        },
+        authority: Authority
+    ): AccountEntity {
+        const account: AccountEntity = new AccountEntity();
+
+        if (authority.authorityType === AuthorityType.Adfs) {
+            account.authorityType = CacheAccountType.ADFS_ACCOUNT_TYPE;
+        } else if (authority.protocolMode === ProtocolMode.AAD) {
+            account.authorityType = CacheAccountType.MSSTS_ACCOUNT_TYPE;
+        } else {
+            account.authorityType = CacheAccountType.GENERIC_ACCOUNT_TYPE;
+        }
+
+        account.clientInfo = accountDetails.clientInfo;
+        account.homeAccountId = accountDetails.homeAccountId;
+        account.nativeAccountId = accountDetails.nativeAccountId;
+
+        const env =
+            accountDetails.environment ||
+            (authority && authority.getPreferredCache());
+
+        if (!env) {
+            throw ClientAuthError.createInvalidCacheEnvironmentError();
+        }
+
+        account.environment = env;
+        // non AAD scenarios can have empty realm
+        account.realm =
+            accountDetails.idTokenClaims.tid || Constants.EMPTY_STRING;
+
+        account.idTokenClaims = accountDetails.idTokenClaims;
+
+        // How do you account for MSA CID here?
+        account.localAccountId =
+            accountDetails.idTokenClaims.oid ||
+            accountDetails.idTokenClaims.sub ||
+            Constants.EMPTY_STRING;
+
+        /*
+         * In B2C scenarios the emails claim is used instead of preferred_username and it is an array.
+         * In most cases it will contain a single email. This field should not be relied upon if a custom
+         * policy is configured to return more than 1 email.
+         */
+        const preferredUsername =
+            accountDetails.idTokenClaims.preferred_username ||
+            accountDetails.idTokenClaims.upn;
+        const email = accountDetails.idTokenClaims.emails
+            ? accountDetails.idTokenClaims.emails[0]
+            : null;
+
+        account.username = preferredUsername || email || Constants.EMPTY_STRING;
+        account.name = accountDetails.idTokenClaims.name;
+
+        account.cloudGraphHostName = accountDetails.cloudGraphHostName;
+        account.msGraphHost = accountDetails.msGraphHost;
+
+        return account;
+    }
+
+    /**
+     * Creates an AccountEntity object from AccountInfo
+     * @param accountInfo
+     * @param cloudGraphHostName
+     * @param msGraphHost
+     * @returns
+     */
+    static createFromAccountInfo(
+        accountInfo: AccountInfo,
+        cloudGraphHostName?: string,
+        msGraphHost?: string
+    ): AccountEntity {
+        const account: AccountEntity = new AccountEntity();
+
+        account.authorityType =
+            accountInfo.authorityType || CacheAccountType.GENERIC_ACCOUNT_TYPE;
+        account.homeAccountId = accountInfo.homeAccountId;
+        account.localAccountId = accountInfo.localAccountId;
+        account.nativeAccountId = accountInfo.nativeAccountId;
+
+        account.realm = accountInfo.tenantId;
+        account.environment = accountInfo.environment;
+
+        account.username = accountInfo.username;
+        account.name = accountInfo.name;
+        account.idTokenClaims = accountInfo.idTokenClaims;
+
+        account.cloudGraphHostName = cloudGraphHostName;
+        account.msGraphHost = msGraphHost;
+
+        return account;
+    }
+
+    /**
+     * Generate HomeAccountId from server response
+     * @param serverClientInfo
+     * @param authType
+     */
+    static generateHomeAccountId(
+        serverClientInfo: string,
+        authType: AuthorityType,
+        logger: Logger,
+        cryptoObj: ICrypto,
+        idTokenClaims?: TokenClaims
+    ): string {
+        const accountId = idTokenClaims?.sub
+            ? idTokenClaims.sub
+            : Constants.EMPTY_STRING;
+
+        // since ADFS does not have tid and does not set client_info
+        if (
+            authType === AuthorityType.Adfs ||
+            authType === AuthorityType.Dsts
+        ) {
+            return accountId;
+        }
+
+        // for cases where there is clientInfo
+        if (serverClientInfo) {
+            try {
+                const clientInfo = buildClientInfo(serverClientInfo, cryptoObj);
+                if (clientInfo.uid && clientInfo.utid) {
+                    return `${clientInfo.uid}${Separators.CLIENT_INFO_SEPARATOR}${clientInfo.utid}`;
+                }
+            } catch (e) {}
+        }
+
+        // default to "sub" claim
+        logger.verbose("No client info in response");
+        return accountId;
+    }
+
+    /**
+     * Validates an entity: checks for all expected params
+     * @param entity
+     */
+    static isAccountEntity(entity: object): boolean {
+        if (!entity) {
+            return false;
+        }
+
+        return (
+            entity.hasOwnProperty("homeAccountId") &&
+            entity.hasOwnProperty("environment") &&
+            entity.hasOwnProperty("realm") &&
+            entity.hasOwnProperty("localAccountId") &&
+            entity.hasOwnProperty("username") &&
+            entity.hasOwnProperty("authorityType")
+        );
+    }
+
+    /**
+     * Helper function to determine whether 2 accountInfo objects represent the same account
+     * @param accountA
+     * @param accountB
+     * @param compareClaims - If set to true idTokenClaims will also be compared to determine account equality
+     */
+    static accountInfoIsEqual(
+        accountA: AccountInfo | null,
+        accountB: AccountInfo | null,
+        compareClaims?: boolean
+    ): boolean {
+        if (!accountA || !accountB) {
+            return false;
+        }
+
+        let claimsMatch = true; // default to true so as to not fail comparison below if compareClaims: false
+        if (compareClaims) {
+            const accountAClaims = (accountA.idTokenClaims ||
+                {}) as TokenClaims;
+            const accountBClaims = (accountB.idTokenClaims ||
+                {}) as TokenClaims;
+
+            // issued at timestamp and nonce are expected to change each time a new id token is acquired
+            claimsMatch =
+                accountAClaims.iat === accountBClaims.iat &&
+                accountAClaims.nonce === accountBClaims.nonce;
+        }
+
+        return (
+            accountA.homeAccountId === accountB.homeAccountId &&
+            accountA.localAccountId === accountB.localAccountId &&
+            accountA.username === accountB.username &&
+            accountA.tenantId === accountB.tenantId &&
+            accountA.environment === accountB.environment &&
+            accountA.nativeAccountId === accountB.nativeAccountId &&
+            claimsMatch
+        );
+    }
+}

package/src/cache/entities/AppMetadataEntity.ts

@@ -0,0 +1,91 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { APP_METADATA, Separators } from "../../utils/Constants";
+
+/**
+ * APP_METADATA Cache
+ *
+ * Key:Value Schema:
+ *
+ * Key: appmetadata-<environment>-<client_id>
+ *
+ * Value:
+ * {
+ *      clientId: client ID of the application
+ *      environment: entity that issued the token, represented as a full host
+ *      familyId: Family ID identifier, '1' represents Microsoft Family
+ * }
+ */
+export class AppMetadataEntity {
+    clientId: string;
+    environment: string;
+    familyId?: string;
+
+    /**
+     * Generate AppMetadata Cache Key as per the schema: appmetadata-<environment>-<client_id>
+     */
+    generateAppMetadataKey(): string {
+        return AppMetadataEntity.generateAppMetadataCacheKey(
+            this.environment,
+            this.clientId
+        );
+    }
+
+    /**
+     * Generate AppMetadata Cache Key
+     */
+    static generateAppMetadataCacheKey(
+        environment: string,
+        clientId: string
+    ): string {
+        const appMetaDataKeyArray: Array<string> = [
+            APP_METADATA,
+            environment,
+            clientId,
+        ];
+        return appMetaDataKeyArray
+            .join(Separators.CACHE_KEY_SEPARATOR)
+            .toLowerCase();
+    }
+
+    /**
+     * Creates AppMetadataEntity
+     * @param clientId
+     * @param environment
+     * @param familyId
+     */
+    static createAppMetadataEntity(
+        clientId: string,
+        environment: string,
+        familyId?: string
+    ): AppMetadataEntity {
+        const appMetadata = new AppMetadataEntity();
+
+        appMetadata.clientId = clientId;
+        appMetadata.environment = environment;
+        if (familyId) {
+            appMetadata.familyId = familyId;
+        }
+
+        return appMetadata;
+    }
+
+    /**
+     * Validates an entity: checks for all expected params
+     * @param entity
+     */
+    static isAppMetadataEntity(key: string, entity: object): boolean {
+        if (!entity) {
+            return false;
+        }
+
+        return (
+            key.indexOf(APP_METADATA) === 0 &&
+            entity.hasOwnProperty("clientId") &&
+            entity.hasOwnProperty("environment")
+        );
+    }
+}

package/src/cache/entities/AuthorityMetadataEntity.ts

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CloudDiscoveryMetadata } from "../../authority/CloudDiscoveryMetadata";
+import { OpenIdConfigResponse } from "../../authority/OpenIdConfigResponse";
+import { AUTHORITY_METADATA_CONSTANTS } from "../../utils/Constants";
+import { TimeUtils } from "../../utils/TimeUtils";
+
+/** @internal */
+export class AuthorityMetadataEntity {
+    aliases: Array<string>;
+    preferred_cache: string;
+    preferred_network: string;
+    canonical_authority: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    end_session_endpoint?: string;
+    issuer: string;
+    aliasesFromNetwork: boolean;
+    endpointsFromNetwork: boolean;
+    expiresAt: number;
+    jwks_uri: string;
+
+    constructor() {
+        this.expiresAt =
+            TimeUtils.nowSeconds() +
+            AUTHORITY_METADATA_CONSTANTS.REFRESH_TIME_SECONDS;
+    }
+
+    /**
+     * Update the entity with new aliases, preferred_cache and preferred_network values
+     * @param metadata
+     * @param fromNetwork
+     */
+    updateCloudDiscoveryMetadata(
+        metadata: CloudDiscoveryMetadata,
+        fromNetwork: boolean
+    ): void {
+        this.aliases = metadata.aliases;
+        this.preferred_cache = metadata.preferred_cache;
+        this.preferred_network = metadata.preferred_network;
+        this.aliasesFromNetwork = fromNetwork;
+    }
+
+    /**
+     * Update the entity with new endpoints
+     * @param metadata
+     * @param fromNetwork
+     */
+    updateEndpointMetadata(
+        metadata: OpenIdConfigResponse,
+        fromNetwork: boolean
+    ): void {
+        this.authorization_endpoint = metadata.authorization_endpoint;
+        this.token_endpoint = metadata.token_endpoint;
+        this.end_session_endpoint = metadata.end_session_endpoint;
+        this.issuer = metadata.issuer;
+        this.endpointsFromNetwork = fromNetwork;
+        this.jwks_uri = metadata.jwks_uri;
+    }
+
+    /**
+     * Save the authority that was used to create this cache entry
+     * @param authority
+     */
+    updateCanonicalAuthority(authority: string): void {
+        this.canonical_authority = authority;
+    }
+
+    /**
+     * Reset the exiresAt value
+     */
+    resetExpiresAt(): void {
+        this.expiresAt =
+            TimeUtils.nowSeconds() +
+            AUTHORITY_METADATA_CONSTANTS.REFRESH_TIME_SECONDS;
+    }
+
+    /**
+     * Returns whether or not the data needs to be refreshed
+     */
+    isExpired(): boolean {
+        return this.expiresAt <= TimeUtils.nowSeconds();
+    }
+
+    /**
+     * Validates an entity: checks for all expected params
+     * @param entity
+     */
+    static isAuthorityMetadataEntity(key: string, entity: object): boolean {
+        if (!entity) {
+            return false;
+        }
+
+        return (
+            key.indexOf(AUTHORITY_METADATA_CONSTANTS.CACHE_KEY) === 0 &&
+            entity.hasOwnProperty("aliases") &&
+            entity.hasOwnProperty("preferred_cache") &&
+            entity.hasOwnProperty("preferred_network") &&
+            entity.hasOwnProperty("canonical_authority") &&
+            entity.hasOwnProperty("authorization_endpoint") &&
+            entity.hasOwnProperty("token_endpoint") &&
+            entity.hasOwnProperty("issuer") &&
+            entity.hasOwnProperty("aliasesFromNetwork") &&
+            entity.hasOwnProperty("endpointsFromNetwork") &&
+            entity.hasOwnProperty("expiresAt") &&
+            entity.hasOwnProperty("jwks_uri")
+        );
+    }
+}