@azure/msal-browser 3.0.1 → 3.1.0

package/src/crypto/BrowserCrypto.ts

@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { BrowserStringUtils } from "../utils/BrowserStringUtils";
+import {
+    createBrowserAuthError,
+    BrowserAuthErrorCodes,
+} from "../error/BrowserAuthError";
+import { ISubtleCrypto } from "./ISubtleCrypto";
+import { ModernBrowserCrypto } from "./ModernBrowserCrypto";
+import { Logger } from "@azure/msal-common";
+/**
+ * See here for more info on RsaHashedKeyGenParams: https://developer.mozilla.org/en-US/docs/Web/API/RsaHashedKeyGenParams
+ */
+// RSA KeyGen Algorithm
+const PKCS1_V15_KEYGEN_ALG = "RSASSA-PKCS1-v1_5";
+// SHA-256 hashing algorithm
+const S256_HASH_ALG = "SHA-256";
+// MOD length for PoP tokens
+const MODULUS_LENGTH = 2048;
+// Public Exponent
+const PUBLIC_EXPONENT: Uint8Array = new Uint8Array([0x01, 0x00, 0x01]);
+
+/**
+ * This class implements functions used by the browser library to perform cryptography operations such as
+ * hashing and encoding. It also has helper functions to validate the availability of specific APIs.
+ */
+export class BrowserCrypto {
+    private keygenAlgorithmOptions: RsaHashedKeyGenParams;
+    private subtleCrypto: ISubtleCrypto;
+    private logger: Logger;
+
+    constructor(logger: Logger) {
+        this.logger = logger;
+
+        if (this.hasBrowserCrypto()) {
+            // Use standard modern web crypto if available
+            this.logger.verbose(
+                "BrowserCrypto: modern crypto interface available"
+            );
+            this.subtleCrypto = new ModernBrowserCrypto();
+        } else {
+            this.logger.error("BrowserCrypto: crypto interface is unavailable");
+            throw createBrowserAuthError(
+                BrowserAuthErrorCodes.cryptoNonExistent
+            );
+        }
+
+        this.keygenAlgorithmOptions = {
+            name: PKCS1_V15_KEYGEN_ALG,
+            hash: S256_HASH_ALG,
+            modulusLength: MODULUS_LENGTH,
+            publicExponent: PUBLIC_EXPONENT,
+        };
+    }
+
+    /**
+     * Check whether browser crypto is available.
+     */
+    private hasBrowserCrypto(): boolean {
+        return "crypto" in window;
+    }
+
+    /**
+     * Returns a sha-256 hash of the given dataString as an ArrayBuffer.
+     * @param dataString
+     */
+    async sha256Digest(dataString: string): Promise<ArrayBuffer> {
+        const data = BrowserStringUtils.stringToUtf8Arr(dataString);
+        // MSR Crypto wants object with name property, instead of string
+        return this.subtleCrypto.digest({ name: S256_HASH_ALG }, data);
+    }
+
+    /**
+     * Populates buffer with cryptographically random values.
+     * @param dataBuffer
+     */
+    getRandomValues(dataBuffer: Uint8Array): Uint8Array {
+        return this.subtleCrypto.getRandomValues(dataBuffer);
+    }
+
+    /**
+     * Generates a keypair based on current keygen algorithm config.
+     * @param extractable
+     * @param usages
+     */
+    async generateKeyPair(
+        extractable: boolean,
+        usages: Array<KeyUsage>
+    ): Promise<CryptoKeyPair> {
+        return this.subtleCrypto.generateKey(
+            this.keygenAlgorithmOptions,
+            extractable,
+            usages
+        );
+    }
+
+    /**
+     * Export key as Json Web Key (JWK)
+     * @param key
+     */
+    async exportJwk(key: CryptoKey): Promise<JsonWebKey> {
+        return this.subtleCrypto.exportKey(key);
+    }
+
+    /**
+     * Imports key as Json Web Key (JWK), can set extractable and usages.
+     * @param key
+     * @param extractable
+     * @param usages
+     */
+    async importJwk(
+        key: JsonWebKey,
+        extractable: boolean,
+        usages: Array<KeyUsage>
+    ): Promise<CryptoKey> {
+        return this.subtleCrypto.importKey(
+            key,
+            this.keygenAlgorithmOptions,
+            extractable,
+            usages
+        );
+    }
+
+    /**
+     * Signs given data with given key
+     * @param key
+     * @param data
+     */
+    async sign(key: CryptoKey, data: ArrayBuffer): Promise<ArrayBuffer> {
+        return this.subtleCrypto.sign(this.keygenAlgorithmOptions, key, data);
+    }
+}

package/src/crypto/CryptoOps.ts

@@ -0,0 +1,247 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    ICrypto,
+    IPerformanceClient,
+    JoseHeader,
+    Logger,
+    PerformanceEvents,
+    PkceCodes,
+    SignedHttpRequest,
+    SignedHttpRequestParameters,
+} from "@azure/msal-common";
+import { base64Encode, urlEncode, urlEncodeArr } from "../encode/Base64Encode";
+import { base64Decode } from "../encode/Base64Decode";
+import { PkceGenerator } from "./PkceGenerator";
+import { BrowserCrypto } from "./BrowserCrypto";
+import { BrowserStringUtils } from "../utils/BrowserStringUtils";
+import {
+    createBrowserAuthError,
+    BrowserAuthErrorCodes,
+} from "../error/BrowserAuthError";
+import { CryptoKeyStore } from "../cache/CryptoKeyStore";
+
+export type CachedKeyPair = {
+    publicKey: CryptoKey;
+    privateKey: CryptoKey;
+    requestMethod?: string;
+    requestUri?: string;
+};
+
+/**
+ * This class implements MSAL's crypto interface, which allows it to perform base64 encoding and decoding, generating cryptographically random GUIDs and
+ * implementing Proof Key for Code Exchange specs for the OAuth Authorization Code Flow using PKCE (rfc here: https://tools.ietf.org/html/rfc7636).
+ */
+export class CryptoOps implements ICrypto {
+    private browserCrypto: BrowserCrypto;
+    private pkceGenerator: PkceGenerator;
+    private logger: Logger;
+
+    /**
+     * CryptoOps can be used in contexts outside a PCA instance,
+     * meaning there won't be a performance manager available.
+     */
+    private performanceClient: IPerformanceClient | undefined;
+
+    private static POP_KEY_USAGES: Array<KeyUsage> = ["sign", "verify"];
+    private static EXTRACTABLE: boolean = true;
+    private cache: CryptoKeyStore;
+
+    constructor(logger: Logger, performanceClient?: IPerformanceClient) {
+        this.logger = logger;
+        // Browser crypto needs to be validated first before any other classes can be set.
+        this.browserCrypto = new BrowserCrypto(this.logger);
+        this.pkceGenerator = new PkceGenerator(this.browserCrypto);
+        this.cache = new CryptoKeyStore(this.logger);
+        this.performanceClient = performanceClient;
+    }
+
+    /**
+     * Creates a new random GUID - used to populate state and nonce.
+     * @returns string (GUID)
+     */
+    createNewGuid(): string {
+        return window.crypto.randomUUID();
+    }
+
+    /**
+     * Encodes input string to base64.
+     * @param input
+     */
+    base64Encode(input: string): string {
+        return base64Encode(input);
+    }
+
+    /**
+     * Decodes input string from base64.
+     * @param input
+     */
+    base64Decode(input: string): string {
+        return base64Decode(input);
+    }
+
+    /**
+     * Generates PKCE codes used in Authorization Code Flow.
+     */
+    async generatePkceCodes(): Promise<PkceCodes> {
+        return this.pkceGenerator.generateCodes();
+    }
+
+    /**
+     * Generates a keypair, stores it and returns a thumbprint
+     * @param request
+     */
+    async getPublicKeyThumbprint(
+        request: SignedHttpRequestParameters
+    ): Promise<string> {
+        const publicKeyThumbMeasurement =
+            this.performanceClient?.startMeasurement(
+                PerformanceEvents.CryptoOptsGetPublicKeyThumbprint,
+                request.correlationId
+            );
+
+        // Generate Keypair
+        const keyPair: CryptoKeyPair = await this.browserCrypto.generateKeyPair(
+            CryptoOps.EXTRACTABLE,
+            CryptoOps.POP_KEY_USAGES
+        );
+
+        // Generate Thumbprint for Public Key
+        const publicKeyJwk: JsonWebKey = await this.browserCrypto.exportJwk(
+            keyPair.publicKey
+        );
+
+        const pubKeyThumprintObj: JsonWebKey = {
+            e: publicKeyJwk.e,
+            kty: publicKeyJwk.kty,
+            n: publicKeyJwk.n,
+        };
+
+        const publicJwkString: string =
+            BrowserStringUtils.getSortedObjectString(pubKeyThumprintObj);
+        const publicJwkHash = await this.hashString(publicJwkString);
+
+        // Generate Thumbprint for Private Key
+        const privateKeyJwk: JsonWebKey = await this.browserCrypto.exportJwk(
+            keyPair.privateKey
+        );
+        // Re-import private key to make it unextractable
+        const unextractablePrivateKey: CryptoKey =
+            await this.browserCrypto.importJwk(privateKeyJwk, false, ["sign"]);
+
+        // Store Keypair data in keystore
+        await this.cache.asymmetricKeys.setItem(publicJwkHash, {
+            privateKey: unextractablePrivateKey,
+            publicKey: keyPair.publicKey,
+            requestMethod: request.resourceRequestMethod,
+            requestUri: request.resourceRequestUri,
+        });
+
+        if (publicKeyThumbMeasurement) {
+            publicKeyThumbMeasurement.end({
+                success: true,
+            });
+        }
+
+        return publicJwkHash;
+    }
+
+    /**
+     * Removes cryptographic keypair from key store matching the keyId passed in
+     * @param kid
+     */
+    async removeTokenBindingKey(kid: string): Promise<boolean> {
+        await this.cache.asymmetricKeys.removeItem(kid);
+        const keyFound = await this.cache.asymmetricKeys.containsKey(kid);
+        return !keyFound;
+    }
+
+    /**
+     * Removes all cryptographic keys from IndexedDB storage
+     */
+    async clearKeystore(): Promise<boolean> {
+        return await this.cache.clear();
+    }
+
+    /**
+     * Signs the given object as a jwt payload with private key retrieved by given kid.
+     * @param payload
+     * @param kid
+     */
+    async signJwt(
+        payload: SignedHttpRequest,
+        kid: string,
+        correlationId?: string
+    ): Promise<string> {
+        const signJwtMeasurement = this.performanceClient?.startMeasurement(
+            PerformanceEvents.CryptoOptsSignJwt,
+            correlationId
+        );
+        const cachedKeyPair = await this.cache.asymmetricKeys.getItem(kid);
+
+        if (!cachedKeyPair) {
+            throw createBrowserAuthError(
+                BrowserAuthErrorCodes.cryptoKeyNotFound
+            );
+        }
+
+        // Get public key as JWK
+        const publicKeyJwk = await this.browserCrypto.exportJwk(
+            cachedKeyPair.publicKey
+        );
+        const publicKeyJwkString =
+            BrowserStringUtils.getSortedObjectString(publicKeyJwk);
+
+        // Base64URL encode public key thumbprint with keyId only: BASE64URL({ kid: "FULL_PUBLIC_KEY_HASH" })
+        const encodedKeyIdThumbprint = urlEncode(JSON.stringify({ kid: kid }));
+
+        // Generate header
+        const shrHeader = JoseHeader.getShrHeaderString({
+            kid: encodedKeyIdThumbprint,
+            alg: publicKeyJwk.alg,
+        });
+        const encodedShrHeader = urlEncode(shrHeader);
+
+        // Generate payload
+        payload.cnf = {
+            jwk: JSON.parse(publicKeyJwkString),
+        };
+        const encodedPayload = urlEncode(JSON.stringify(payload));
+
+        // Form token string
+        const tokenString = `${encodedShrHeader}.${encodedPayload}`;
+
+        // Sign token
+        const tokenBuffer = BrowserStringUtils.stringToUtf8Arr(tokenString);
+        const signatureBuffer = await this.browserCrypto.sign(
+            cachedKeyPair.privateKey,
+            tokenBuffer
+        );
+        const encodedSignature = urlEncodeArr(new Uint8Array(signatureBuffer));
+
+        const signedJwt = `${tokenString}.${encodedSignature}`;
+
+        if (signJwtMeasurement) {
+            signJwtMeasurement.end({
+                success: true,
+            });
+        }
+
+        return signedJwt;
+    }
+
+    /**
+     * Returns the SHA-256 hash of an input string
+     * @param plainText
+     */
+    async hashString(plainText: string): Promise<string> {
+        const hashBuffer: ArrayBuffer = await this.browserCrypto.sha256Digest(
+            plainText
+        );
+        const hashBytes = new Uint8Array(hashBuffer);
+        return urlEncodeArr(hashBytes);
+    }
+}

package/src/crypto/ISubtleCrypto.ts

@@ -0,0 +1,30 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+export interface ISubtleCrypto {
+    initPrng?(entropy: Uint8Array): void;
+    getRandomValues(dataBuffer: Uint8Array): Uint8Array;
+    generateKey(
+        algorithm: RsaHashedKeyGenParams,
+        extractable: boolean,
+        keyUsages: KeyUsage[]
+    ): Promise<CryptoKeyPair>;
+    exportKey(key: CryptoKey): Promise<JsonWebKey>;
+    importKey(
+        keyData: JsonWebKey,
+        algorithm: RsaHashedImportParams,
+        extractable: boolean,
+        keyUsages: KeyUsage[]
+    ): Promise<CryptoKey>;
+    sign(
+        algorithm: AlgorithmIdentifier,
+        key: CryptoKey,
+        data: ArrayBuffer
+    ): Promise<ArrayBuffer>;
+    digest(
+        algorithm: AlgorithmIdentifier,
+        data: Uint8Array
+    ): Promise<ArrayBuffer>;
+}

package/src/crypto/ModernBrowserCrypto.ts

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { KEY_FORMAT_JWK } from "../utils/BrowserConstants";
+import { ISubtleCrypto } from "./ISubtleCrypto";
+
+export class ModernBrowserCrypto implements ISubtleCrypto {
+    getRandomValues(dataBuffer: Uint8Array): Uint8Array {
+        return window.crypto.getRandomValues(dataBuffer);
+    }
+
+    async generateKey(
+        algorithm: RsaHashedKeyGenParams,
+        extractable: boolean,
+        keyUsages: KeyUsage[]
+    ): Promise<CryptoKeyPair> {
+        return window.crypto.subtle.generateKey(
+            algorithm,
+            extractable,
+            keyUsages
+        ) as Promise<CryptoKeyPair>;
+    }
+
+    async exportKey(key: CryptoKey): Promise<JsonWebKey> {
+        return window.crypto.subtle.exportKey(
+            KEY_FORMAT_JWK,
+            key
+        ) as Promise<JsonWebKey>;
+    }
+
+    async importKey(
+        keyData: JsonWebKey,
+        algorithm: RsaHashedImportParams,
+        extractable: boolean,
+        keyUsages: KeyUsage[]
+    ): Promise<CryptoKey> {
+        return window.crypto.subtle.importKey(
+            KEY_FORMAT_JWK,
+            keyData,
+            algorithm,
+            extractable,
+            keyUsages
+        ) as Promise<CryptoKey>;
+    }
+
+    async sign(
+        algorithm: AlgorithmIdentifier,
+        key: CryptoKey,
+        data: ArrayBuffer
+    ): Promise<ArrayBuffer> {
+        return window.crypto.subtle.sign(
+            algorithm,
+            key,
+            data
+        ) as Promise<ArrayBuffer>;
+    }
+
+    async digest(
+        algorithm: AlgorithmIdentifier,
+        data: Uint8Array
+    ): Promise<ArrayBuffer> {
+        return window.crypto.subtle.digest(
+            algorithm,
+            data
+        ) as Promise<ArrayBuffer>;
+    }
+}

package/src/crypto/PkceGenerator.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { PkceCodes } from "@azure/msal-common";
+import {
+    createBrowserAuthError,
+    BrowserAuthErrorCodes,
+} from "../error/BrowserAuthError";
+import { urlEncodeArr } from "../encode/Base64Encode";
+import { BrowserCrypto } from "./BrowserCrypto";
+
+// Constant byte array length
+const RANDOM_BYTE_ARR_LENGTH = 32;
+
+/**
+ * Class which exposes APIs to generate PKCE codes and code verifiers.
+ */
+export class PkceGenerator {
+    private cryptoObj: BrowserCrypto;
+
+    constructor(cryptoObj: BrowserCrypto) {
+        this.cryptoObj = cryptoObj;
+    }
+
+    /**
+     * Generates PKCE Codes. See the RFC for more information: https://tools.ietf.org/html/rfc7636
+     */
+    async generateCodes(): Promise<PkceCodes> {
+        const codeVerifier = this.generateCodeVerifier();
+        const codeChallenge = await this.generateCodeChallengeFromVerifier(
+            codeVerifier
+        );
+        return {
+            verifier: codeVerifier,
+            challenge: codeChallenge,
+        };
+    }
+
+    /**
+     * Generates a random 32 byte buffer and returns the base64
+     * encoded string to be used as a PKCE Code Verifier
+     */
+    private generateCodeVerifier(): string {
+        try {
+            // Generate random values as utf-8
+            const buffer: Uint8Array = new Uint8Array(RANDOM_BYTE_ARR_LENGTH);
+            this.cryptoObj.getRandomValues(buffer);
+            // encode verifier as base64
+            const pkceCodeVerifierB64: string = urlEncodeArr(buffer);
+            return pkceCodeVerifierB64;
+        } catch (e) {
+            throw createBrowserAuthError(BrowserAuthErrorCodes.pkceNotCreated);
+        }
+    }
+
+    /**
+     * Creates a base64 encoded PKCE Code Challenge string from the
+     * hash created from the PKCE Code Verifier supplied
+     */
+    private async generateCodeChallengeFromVerifier(
+        pkceCodeVerifier: string
+    ): Promise<string> {
+        try {
+            // hashed verifier
+            const pkceHashedCodeVerifier = await this.cryptoObj.sha256Digest(
+                pkceCodeVerifier
+            );
+            // encode hash as base64
+            return urlEncodeArr(new Uint8Array(pkceHashedCodeVerifier));
+        } catch (e) {
+            throw createBrowserAuthError(BrowserAuthErrorCodes.pkceNotCreated);
+        }
+    }
+}

package/src/crypto/SignedHttpRequest.ts

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { CryptoOps } from "./CryptoOps";
+import {
+    Logger,
+    LoggerOptions,
+    PopTokenGenerator,
+    SignedHttpRequestParameters,
+} from "@azure/msal-common";
+import { version, name } from "../packageMetadata";
+
+export type SignedHttpRequestOptions = {
+    loggerOptions: LoggerOptions;
+};
+
+export class SignedHttpRequest {
+    private popTokenGenerator: PopTokenGenerator;
+    private cryptoOps: CryptoOps;
+    private shrParameters: SignedHttpRequestParameters;
+    private logger: Logger;
+
+    constructor(
+        shrParameters: SignedHttpRequestParameters,
+        shrOptions?: SignedHttpRequestOptions
+    ) {
+        const loggerOptions = (shrOptions && shrOptions.loggerOptions) || {};
+        this.logger = new Logger(loggerOptions, name, version);
+        this.cryptoOps = new CryptoOps(this.logger);
+        this.popTokenGenerator = new PopTokenGenerator(this.cryptoOps);
+        this.shrParameters = shrParameters;
+    }
+
+    /**
+     * Generates and caches a keypair for the given request options.
+     * @returns Public key digest, which should be sent to the token issuer.
+     */
+    async generatePublicKeyThumbprint(): Promise<string> {
+        const { kid } = await this.popTokenGenerator.generateKid(
+            this.shrParameters
+        );
+
+        return kid;
+    }
+
+    /**
+     * Generates a signed http request for the given payload with the given key.
+     * @param payload Payload to sign (e.g. access token)
+     * @param publicKeyThumbprint Public key digest (from generatePublicKeyThumbprint API)
+     * @param claims Additional claims to include/override in the signed JWT
+     * @returns Pop token signed with the corresponding private key
+     */
+    async signRequest(
+        payload: string,
+        publicKeyThumbprint: string,
+        claims?: object
+    ): Promise<string> {
+        return this.popTokenGenerator.signPayload(
+            payload,
+            publicKeyThumbprint,
+            this.shrParameters,
+            claims
+        );
+    }
+
+    /**
+     * Removes cached keys from browser for given public key thumbprint
+     * @param publicKeyThumbprint Public key digest (from generatePublicKeyThumbprint API)
+     * @returns If keys are properly deleted
+     */
+    async removeKeys(publicKeyThumbprint: string): Promise<boolean> {
+        return await this.cryptoOps.removeTokenBindingKey(publicKeyThumbprint);
+    }
+}

package/src/encode/Base64Decode.ts

@@ -0,0 +1,26 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Class which exposes APIs to decode base64 strings to plaintext. See here for implementation details:
+ * https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem
+ */
+
+/**
+ * Returns a URL-safe plaintext decoded string from b64 encoded input.
+ * @param input
+ */
+export function base64Decode(input: string): string {
+    return new TextDecoder().decode(base64DecToArr(input));
+}
+
+/**
+ * Decodes base64 into Uint8Array
+ * @param base64String
+ */
+function base64DecToArr(base64String: string): Uint8Array {
+    const binString = atob(base64String);
+    return Uint8Array.from(binString, (m) => m.codePointAt(0) || 0);
+}