[Identity] Simple OnBehalfOfCredential

sdk/identity/identity/CHANGELOG.md

@@ -4,6 +4,8 @@
 
 ### Features Added
 
+- Added the `OnBehalfOfCredential`, which allows users to authenticate through the [On-Behalf-Of authentication flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow).
+
 ### Breaking Changes
 
 ### Bugs Fixed

sdk/identity/identity/package.json

@@ -22,6 +22,7 @@
     "./dist-esm/src/credentials/usernamePasswordCredential.js": "./dist-esm/src/credentials/usernamePasswordCredential.browser.js",
     "./dist-esm/src/credentials/azurePowerShellCredential.js": "./dist-esm/src/credentials/azurePowerShellCredential.browser.js",
     "./dist-esm/src/credentials/applicationCredential.js": "./dist-esm/src/credentials/applicationCredential.browser.js",
+    "./dist-esm/src/credentials/onBehalfOfCredential.js": "./dist-esm/src/credentials/onBehalfOfCredential.browser.js",
     "./dist-esm/src/util/authHostEnv.js": "./dist-esm/src/util/authHostEnv.browser.js",
     "./dist-esm/src/tokenCache/TokenCachePersistence.js": "./dist-esm/src/tokenCache/TokenCachePersistence.browser.js",
     "./dist-esm/src/extensions/consumer.js": "./dist-esm/src/extensions/consumer.browser.js",

sdk/identity/identity/review/identity.api.md

@@ -249,6 +249,16 @@ export class ManagedIdentityCredential implements TokenCredential {
     getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
     }
 
+// @public
+export class OnBehalfOfCredential implements TokenCredential {
+    constructor(tenantId: string, clientId: string, clientSecret: string, userAssertionToken: string, options?: OnBehalfOfCredentialOptions);
+    getToken(scopes: string | string[], options?: GetTokenOptions): Promise<AccessToken>;
+    }
+
+// @public
+export interface OnBehalfOfCredentialOptions extends TokenCredentialOptions, CredentialPersistenceOptions {
+}
+
 // @public
 export enum RegionalAuthority {
     AsiaEast = "eastasia",

sdk/identity/identity/src/credentials/onBehalfOfCredential.browser.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { TokenCredential, AccessToken } from "@azure/core-auth";
+
+import { credentialLogger, formatError } from "../util/logging";
+
+const BrowserNotSupportedError = new Error("OnBehalfOfCredential is not supported in the browser.");
+const logger = credentialLogger("OnBehalfOfCredential");
+
+export class OnBehalfOfCredential implements TokenCredential {
+  constructor() {
+    logger.info(formatError("", BrowserNotSupportedError));
+    throw BrowserNotSupportedError;
+  }
+
+  public getToken(): Promise<AccessToken | null> {
+    logger.getToken.info(formatError("", BrowserNotSupportedError));
+    throw BrowserNotSupportedError;
+  }
+}

sdk/identity/identity/src/credentials/onBehalfOfCredential.ts

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { AccessToken, GetTokenOptions, TokenCredential } from "@azure/core-auth";
+
+import { MsalOnBehalfOf } from "../msal/nodeFlows/msalOnBehalfOf";
+import { credentialLogger } from "../util/logging";
+import { trace } from "../util/tracing";
+import { MsalFlow } from "../msal/flows";
+import { OnBehalfOfCredentialOptions } from "./onBehalfOfCredentialOptions";
+
+const logger = credentialLogger("OnBehalfOfCredential");
+
+/**
+ * Enables authentication to Azure Active Directory using the [On Behalf Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow).
+ */
+export class OnBehalfOfCredential implements TokenCredential {
+  private msalFlow: MsalFlow;
+
+  /**
+   * Creates an instance of the {@link OnBehalfOfCredential} with the details
+   * needed to authenticate against Azure Active Directory with a client
+   * secret, and an user assertion.
+   *
+   * Example using the `KeyClient` from [\@azure/keyvault-keys](https://www.npmjs.com/package/\@azure/keyvault-keys):
+   *
+   * ```ts
+   * const tokenCredential = new OnBehalfOfCredential(tenantId, clientId, clientSecret, "access-token");
+   * const client = new KeyClient("vault-url", tokenCredential);
+   *
+   * await client.getKey("key-name", { authenticationOptions: { userAssertion } });
+   * ```
+   *
+   * @param tenantId - The Azure Active Directory tenant (directory) ID.
+   * @param clientId - The client (application) ID of an App Registration in the tenant.
+   * @param clientSecret - A client secret that was generated for the App Registration.
+   * @param options - Options for configuring the client which makes the authentication request.
+   */
+  constructor(
+    private tenantId: string,
+    private clientId: string,
+    private clientSecret: string,
+    private userAssertionToken: string,
+    private options: OnBehalfOfCredentialOptions = {}
+  ) {
+    this.msalFlow = new MsalOnBehalfOf({
+      ...this.options,
+      logger,
+      clientId: this.clientId,
+      tenantId: this.tenantId,
+      clientSecret: this.clientSecret,
+      userAssertionToken: this.userAssertionToken,
+      tokenCredentialOptions: this.options
+    });
+  }
+
+  /**
+   * Authenticates with Azure Active Directory and returns an access token if successful.
+   * If authentication fails, a {@link CredentialUnavailableError} will be thrown with the details of the failure.
+   *
+   * @param scopes - The list of scopes for which the token will have access.
+   * @param options - The options used to configure any requests this
+   *                TokenCredential implementation might make.
+   */
+  async getToken(scopes: string | string[], options: GetTokenOptions = {}): Promise<AccessToken> {
+    return trace(`${this.constructor.name}.getToken`, options, async (newOptions) => {
+      const arrayScopes = Array.isArray(scopes) ? scopes : [scopes];
+      return this.msalFlow.getToken(arrayScopes, newOptions);
+    });
+  }
+}

sdk/identity/identity/src/credentials/onBehalfOfCredentialOptions.ts

@@ -0,0 +1,12 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { TokenCredentialOptions } from "../client/identityClient";
+import { CredentialPersistenceOptions } from "./credentialPersistenceOptions";
+
+/**
+ * Optional parameters for the {@link OnBehalfOfCredential} class.
+ */
+export interface OnBehalfOfCredentialOptions
+  extends TokenCredentialOptions,
+    CredentialPersistenceOptions {}

sdk/identity/identity/src/index.ts

@@ -59,6 +59,9 @@ export {
   VisualStudioCodeCredentialOptions
 } from "./credentials/visualStudioCodeCredential";
 
+export { OnBehalfOfCredential } from "./credentials/onBehalfOfCredential";
+export { OnBehalfOfCredentialOptions } from "./credentials/onBehalfOfCredentialOptions";
+
 export { TokenCachePersistenceOptions } from "./msal/nodeFlows/tokenCachePersistenceOptions";
 
 export {

sdk/identity/identity/src/msal/nodeFlows/msalOnBehalfOf.ts

@@ -0,0 +1,49 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT license.
+
+import { AccessToken } from "@azure/core-auth";
+
+import { CredentialFlowGetTokenOptions } from "../credentials";
+import { MsalNodeOptions, MsalNode } from "./nodeCommon";
+
+/**
+ * Options that can be passed to configure MSAL to handle On-Behalf-Of authentication requests.
+ * @internal
+ */
+export interface MSALOnBehalfOfOptions extends MsalNodeOptions {
+  clientSecret: string;
+  userAssertionToken: string;
+}
+
+/**
+ * MSAL on behalf of flow. Calls to MSAL's confidential application's `acquireTokenOnBehalfOf` during `doGetToken`.
+ * @internal
+ */
+export class MsalOnBehalfOf extends MsalNode {
+  private userAssertionToken: string;
+
+  constructor(options: MSALOnBehalfOfOptions) {
+    super(options);
+    this.logger.info("Initialized MSAL's On-Behalf-Of flow");
+    this.requiresConfidential = true;
+    this.msalConfig.auth.clientSecret = options.clientSecret;
+    this.userAssertionToken = options.userAssertionToken;
+  }
+
+  protected async doGetToken(
+    scopes: string[],
+    options: CredentialFlowGetTokenOptions = {}
+  ): Promise<AccessToken> {
+    try {
+      const result = await this.confidentialApp!.acquireTokenOnBehalfOf({
+        scopes,
+        correlationId: options.correlationId,
+        authority: options.authority,
+        oboAssertion: this.userAssertionToken
+      });
+      return this.handleResult(scopes, this.clientId, result || undefined);
+    } catch (err) {
+      throw this.handleError(scopes, err, options);
+    }
+  }
+}