@azure/msal-browser 3.0.2 → 3.2.0

package/src/crypto/BrowserCrypto.ts

@@ -0,0 +1,151 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import { BrowserStringUtils } from "../utils/BrowserStringUtils";
+import {
+    createBrowserAuthError,
+    BrowserAuthErrorCodes,
+} from "../error/BrowserAuthError";
+import {
+    IPerformanceClient,
+    Logger,
+    PerformanceEvents,
+} from "@azure/msal-common";
+import { KEY_FORMAT_JWK } from "../utils/BrowserConstants";
+
+/**
+ * This file defines 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.
+ */
+
+/**
+ * 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]);
+
+const keygenAlgorithmOptions: RsaHashedKeyGenParams = {
+    name: PKCS1_V15_KEYGEN_ALG,
+    hash: S256_HASH_ALG,
+    modulusLength: MODULUS_LENGTH,
+    publicExponent: PUBLIC_EXPONENT,
+};
+
+/**
+ * Check whether browser crypto is available.
+ */
+export function validateCryptoAvailable(logger: Logger): void {
+    if ("crypto" in window) {
+        logger.verbose("BrowserCrypto: modern crypto interface available");
+    } else {
+        logger.error("BrowserCrypto: crypto interface is unavailable");
+        throw createBrowserAuthError(BrowserAuthErrorCodes.cryptoNonExistent);
+    }
+}
+
+/**
+ * Returns a sha-256 hash of the given dataString as an ArrayBuffer.
+ * @param dataString
+ */
+export async function sha256Digest(
+    dataString: string,
+    performanceClient?: IPerformanceClient,
+    correlationId?: string
+): Promise<ArrayBuffer> {
+    performanceClient?.addQueueMeasurement(
+        PerformanceEvents.Sha256Digest,
+        correlationId
+    );
+    const data = BrowserStringUtils.stringToUtf8Arr(dataString);
+    return window.crypto.subtle.digest(
+        S256_HASH_ALG,
+        data
+    ) as Promise<ArrayBuffer>;
+}
+
+/**
+ * Populates buffer with cryptographically random values.
+ * @param dataBuffer
+ */
+export function getRandomValues(dataBuffer: Uint8Array): Uint8Array {
+    return window.crypto.getRandomValues(dataBuffer);
+}
+
+/**
+ * Creates a new random GUID
+ * @returns
+ */
+export function createNewGuid(): string {
+    return window.crypto.randomUUID();
+}
+
+/**
+ * Generates a keypair based on current keygen algorithm config.
+ * @param extractable
+ * @param usages
+ */
+export async function generateKeyPair(
+    extractable: boolean,
+    usages: Array<KeyUsage>
+): Promise<CryptoKeyPair> {
+    return window.crypto.subtle.generateKey(
+        keygenAlgorithmOptions,
+        extractable,
+        usages
+    ) as Promise<CryptoKeyPair>;
+}
+
+/**
+ * Export key as Json Web Key (JWK)
+ * @param key
+ */
+export async function exportJwk(key: CryptoKey): Promise<JsonWebKey> {
+    return window.crypto.subtle.exportKey(
+        KEY_FORMAT_JWK,
+        key
+    ) as Promise<JsonWebKey>;
+}
+
+/**
+ * Imports key as Json Web Key (JWK), can set extractable and usages.
+ * @param key
+ * @param extractable
+ * @param usages
+ */
+export async function importJwk(
+    key: JsonWebKey,
+    extractable: boolean,
+    usages: Array<KeyUsage>
+): Promise<CryptoKey> {
+    return window.crypto.subtle.importKey(
+        KEY_FORMAT_JWK,
+        key,
+        keygenAlgorithmOptions,
+        extractable,
+        usages
+    ) as Promise<CryptoKey>;
+}
+
+/**
+ * Signs given data with given key
+ * @param key
+ * @param data
+ */
+export async function sign(
+    key: CryptoKey,
+    data: ArrayBuffer
+): Promise<ArrayBuffer> {
+    return window.crypto.subtle.sign(
+        keygenAlgorithmOptions,
+        key,
+        data
+    ) as Promise<ArrayBuffer>;
+}

package/src/crypto/CryptoOps.ts

@@ -0,0 +1,235 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    ICrypto,
+    IPerformanceClient,
+    JoseHeader,
+    Logger,
+    PerformanceEvents,
+    SignedHttpRequest,
+    SignedHttpRequestParameters,
+} from "@azure/msal-common";
+import { base64Encode, urlEncode, urlEncodeArr } from "../encode/Base64Encode";
+import { base64Decode } from "../encode/Base64Decode";
+import * as 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 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.
+        BrowserCrypto.validateCryptoAvailable(logger);
+        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 BrowserCrypto.createNewGuid();
+    }
+
+    /**
+     * 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 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 BrowserCrypto.generateKeyPair(
+            CryptoOps.EXTRACTABLE,
+            CryptoOps.POP_KEY_USAGES
+        );
+
+        // Generate Thumbprint for Public Key
+        const publicKeyJwk: JsonWebKey = await 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 BrowserCrypto.exportJwk(
+            keyPair.privateKey
+        );
+        // Re-import private key to make it unextractable
+        const unextractablePrivateKey: CryptoKey =
+            await 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 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 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 BrowserCrypto.sha256Digest(
+            plainText
+        );
+        const hashBytes = new Uint8Array(hashBuffer);
+        return urlEncodeArr(hashBytes);
+    }
+}

package/src/crypto/PkceGenerator.ts

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    IPerformanceClient,
+    Logger,
+    PerformanceEvents,
+    PkceCodes,
+    invoke,
+    invokeAsync,
+} from "@azure/msal-common";
+import {
+    createBrowserAuthError,
+    BrowserAuthErrorCodes,
+} from "../error/BrowserAuthError";
+import { urlEncodeArr } from "../encode/Base64Encode";
+import { getRandomValues, sha256Digest } from "./BrowserCrypto";
+
+// Constant byte array length
+const RANDOM_BYTE_ARR_LENGTH = 32;
+
+/**
+ * This file defines APIs to generate PKCE codes and code verifiers.
+ */
+
+/**
+ * Generates PKCE Codes. See the RFC for more information: https://tools.ietf.org/html/rfc7636
+ */
+export async function generatePkceCodes(
+    performanceClient: IPerformanceClient,
+    logger: Logger,
+    correlationId: string
+): Promise<PkceCodes> {
+    performanceClient.addQueueMeasurement(
+        PerformanceEvents.GeneratePkceCodes,
+        correlationId
+    );
+    const codeVerifier = invoke(
+        generateCodeVerifier,
+        PerformanceEvents.GenerateCodeVerifier,
+        logger,
+        performanceClient,
+        correlationId
+    )(performanceClient, logger, correlationId);
+    const codeChallenge = await invokeAsync(
+        generateCodeChallengeFromVerifier,
+        PerformanceEvents.GenerateCodeChallengeFromVerifier,
+        logger,
+        performanceClient,
+        correlationId
+    )(codeVerifier, performanceClient, logger, correlationId);
+    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
+ */
+function generateCodeVerifier(
+    performanceClient: IPerformanceClient,
+    logger: Logger,
+    correlationId: string
+): string {
+    try {
+        // Generate random values as utf-8
+        const buffer: Uint8Array = new Uint8Array(RANDOM_BYTE_ARR_LENGTH);
+        invoke(
+            getRandomValues,
+            PerformanceEvents.GetRandomValues,
+            logger,
+            performanceClient,
+            correlationId
+        )(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
+ */
+async function generateCodeChallengeFromVerifier(
+    pkceCodeVerifier: string,
+    performanceClient: IPerformanceClient,
+    logger: Logger,
+    correlationId: string
+): Promise<string> {
+    performanceClient.addQueueMeasurement(
+        PerformanceEvents.GenerateCodeChallengeFromVerifier,
+        correlationId
+    );
+    try {
+        // hashed verifier
+        const pkceHashedCodeVerifier = await invokeAsync(
+            sha256Digest,
+            PerformanceEvents.Sha256Digest,
+            logger,
+            performanceClient,
+            correlationId
+        )(pkceCodeVerifier, performanceClient, correlationId);
+        // 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,46 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+import {
+    BrowserAuthErrorCodes,
+    createBrowserAuthError,
+} from "../error/BrowserAuthError";
+
+/**
+ * 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 {
+    let encodedString = base64String.replace(/-/g, "+").replace(/_/g, "/");
+    switch (encodedString.length % 4) {
+        case 0:
+            break;
+        case 2:
+            encodedString += "==";
+            break;
+        case 3:
+            encodedString += "=";
+            break;
+        default:
+            throw createBrowserAuthError(
+                BrowserAuthErrorCodes.invalidBase64String
+            );
+    }
+    const binString = atob(encodedString);
+    return Uint8Array.from(binString, (m) => m.codePointAt(0) || 0);
+}

package/src/encode/Base64Encode.ts

@@ -0,0 +1,52 @@
+/*
+ * Copyright (c) Microsoft Corporation. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Class which exposes APIs to encode plaintext to base64 encoded string. See here for implementation details:
+ * https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding#Solution_2_%E2%80%93_JavaScript's_UTF-16_%3E_UTF-8_%3E_base64
+ */
+
+/**
+ * Returns URL Safe b64 encoded string from a plaintext string.
+ * @param input
+ */
+export function urlEncode(input: string): string {
+    return encodeURIComponent(
+        base64Encode(input)
+            .replace(/=/g, "")
+            .replace(/\+/g, "-")
+            .replace(/\//g, "_")
+    );
+}
+
+/**
+ * Returns URL Safe b64 encoded string from an int8Array.
+ * @param inputArr
+ */
+export function urlEncodeArr(inputArr: Uint8Array): string {
+    return base64EncArr(inputArr)
+        .replace(/=/g, "")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_");
+}
+
+/**
+ * Returns b64 encoded string from plaintext string.
+ * @param input
+ */
+export function base64Encode(input: string): string {
+    return base64EncArr(new TextEncoder().encode(input));
+}
+
+/**
+ * Base64 encode byte array
+ * @param aBytes
+ */
+function base64EncArr(aBytes: Uint8Array): string {
+    const binString = Array.from(aBytes, (x) => String.fromCodePoint(x)).join(
+        ""
+    );
+    return btoa(binString);
+}