feat(impersonated): add impersonated credentials auth

src/auth/googleauth.ts

@@ -30,6 +30,7 @@ import {GCPEnv, getEnv} from './envDetect';
 import {JWT, JWTOptions} from './jwtclient';
 import {Headers, OAuth2ClientOptions, RefreshOptions} from './oauth2client';
 import {UserRefreshClient, UserRefreshClientOptions} from './refreshclient';
+import {Impersonated, ImpersonatedOptions} from './impersonated';
 import {
   ExternalAccountClient,
   ExternalAccountClientOptions,
@@ -44,7 +45,11 @@ import {AuthClient} from './authclient';
  * Defines all types of explicit clients that are determined via ADC JSON
  * config file.
  */
-export type JSONClient = JWT | UserRefreshClient | BaseExternalAccountClient;
+export type JSONClient =
+  | JWT
+  | UserRefreshClient
+  | BaseExternalAccountClient
+  | Impersonated;
 
 export interface ProjectIdCallback {
   (err?: Error | null, projectId?: string | null): void;
@@ -86,7 +91,11 @@ export interface GoogleAuthOptions {
   /**
    * Options object passed to the constructor of the client
    */
-  clientOptions?: JWTOptions | OAuth2ClientOptions | UserRefreshClientOptions;
+  clientOptions?:
+    | JWTOptions
+    | OAuth2ClientOptions
+    | UserRefreshClientOptions
+    | ImpersonatedOptions;
 
   /**
    * Required scopes for the desired API request
@@ -126,14 +135,13 @@ export class GoogleAuth {
   // To save the contents of the JSON credential file
   jsonContent: JWTInput | ExternalAccountClientOptions | null = null;
 
-  cachedCredential: JSONClient | Compute | null = null;
+  cachedCredential: JSONClient | Impersonated | Compute | null = null;
 
   /**
    * Scopes populated by the client library by default. We differentiate between
    * these and user defined scopes when deciding whether to use a self-signed JWT.
    */
   defaultScopes?: string | string[];
-
   private keyFilename?: string;
   private scopes?: string | string[];
   private clientOptions?: RefreshOptions;

src/auth/impersonated.ts

@@ -0,0 +1,194 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import {GaxiosError, GaxiosOptions, GaxiosPromise} from 'gaxios';
+import {
+  GetTokenResponse,
+  Headers,
+  OAuth2Client,
+  RefreshOptions,
+  RequestMetadataResponse,
+} from './oauth2client';
+
+export interface ImpersonatedOptions extends RefreshOptions {
+  sourceClient?: OAuth2Client;
+  targetPrincipal?: string;
+  targetScopes?: string[];
+  delegates?: string[];
+  lifetime?: number | 3600;
+  endpoint?: string | 'https://iamcredentials.googleapis.com';
+}
+
+export interface TokenResponse {
+  accessToken: string;
+  expireTime: string;
+}
+
+export class Impersonated extends OAuth2Client {
+  private sourceClient: OAuth2Client;
+  private targetPrincipal: string;
+  private targetScopes: string[];
+  private delegates: string[];
+  private lifetime: number;
+  private endpoint: string;
+
+  /**
+   * Impersonated service account credentials.
+   *
+   * Create a new access token by impersonating another service account.
+   *
+   * Impersonated Credentials allowing credentials issued to a user or
+   * service account to impersonate another. The source project using
+   * Impersonated Credentials must enable the "IAMCredentials" API.
+   * Also, the target service account must grant the orginating principal
+   * the "Service Account Token Creator" IAM role.
+   *
+   * @param credentials the service account email address.
+   * @param sourceClient the source credential used as to acquire the
+   * impersonated credentials
+   * @param targetPrincipal the service account to impersonate.
+   * @param delegates the chained list of delegates required to grant the
+   *  final access_token. If set, the sequence of identities must have
+   * "Service Account Token Creator" capability granted to the preceding
+   * identity. For example, if set to [serviceAccountB, serviceAccountC],
+   * the sourceCredential must have the Token Creator role on serviceAccountB.
+   * serviceAccountB must have the Token Creator on serviceAccountC.
+   * Finally, C must have Token Creator on target_principal.
+   * If left unset, sourceCredential must have that role on targetPrincipal.
+   * @param targetScopes scopes to request during the authorization grant.
+   * @param lifetime number of seconds the delegated credential should be
+   * valid for (up to 3600).
+   * @param endpoint api endpoint override.
+   */
+  constructor(options: ImpersonatedOptions = {}) {
+    super(options);
+    this.credentials = {
+      expiry_date: 1,
+      refresh_token: 'impersonated-placeholder',
+    };
+    this.sourceClient = options.sourceClient || new OAuth2Client();
+    this.targetPrincipal = options.targetPrincipal || '';
+    this.delegates = options.delegates || [];
+    this.targetScopes = options.targetScopes || [];
+    this.lifetime = options.lifetime || 3600;
+    this.endpoint = options.endpoint || 'https://iamcredentials.googleapis.com';
+  }
+
+  /**
+   * Refreshes the access token.
+   * @param refreshToken Unused parameter
+   */
+  protected async refreshToken(
+    refreshToken?: string | null
+  ): Promise<GetTokenResponse> {
+    const iat = Date.now();
+    if (this.credentials.expiry_date) {
+      if (this.credentials.expiry_date <= iat) {
+        try {
+          await this.sourceClient.getAccessToken();
+          const name = 'projects/-/serviceAccounts/' + this.targetPrincipal;
+          const u = `${this.endpoint}/v1/${name}:generateAccessToken`;
+          const body = {
+            delegates: this.delegates,
+            scope: this.targetScopes,
+            lifetime: this.lifetime + 's',
+          };
+          const res = await this.sourceClient.request({
+            url: u,
+            data: body,
+            method: 'POST',
+          });
+          const tokenResponse = res.data as TokenResponse;
+          this.credentials.access_token = tokenResponse.accessToken;
+          this.credentials.expiry_date =
+            Date.parse(tokenResponse.expireTime) / 1000;
+          return {
+            tokens: this.credentials,
+            res,
+          };
+        } catch (error) {
+          if (error.status === 403) {
+            if (error.message === 'The caller does not have permission') {
+              throw new Error(
+                'Error: Unable to impersonate: sourceCredential lacks IAM Token Creator role on targetCredential'
+              );
+            }
+            if (
+              error.message ===
+              'Request had insufficient authentication scopes.'
+            ) {
+              throw new Error(
+                'Error: Unable to impersonate: sourceCredential lacks cloud-platform or IAM scope'
+              );
+            }
+          }
+          throw new Error('Error: Unable to impersonate: ' + error);
+        }
+      }
+      return {tokens: this.credentials, res: null};
+    }
+    throw new Error('Error: Root credentials.expiry_date not set ');
+  }
+
+  protected requestAsync<T>(
+    opts: GaxiosOptions,
+    retry = false
+  ): GaxiosPromise<T> {
+    try {
+      return super.requestAsync<T>(opts, retry);
+    } catch (err) {
+      let helpfulMessage = null;
+      if (err.status === 403) {
+        helpfulMessage =
+          'A Forbidden error was returned while attempting access the target Resource as ' +
+          'the Impersonated Account.';
+      } else if (err.status === 404) {
+        helpfulMessage = 'Target Resource was not found.';
+      }
+      if (helpfulMessage) {
+        if (!retry) {
+          helpfulMessage += ' ' + err.message;
+        }
+        err.message = helpfulMessage;
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Get a non-expired access token, after refreshing if necessary.
+   *
+   * @param url The URI being authorized.
+   * @returns An object that includes the authorization header.
+   */
+  async getRequestHeaders(): Promise<Headers> {
+    const res = await this.getRequestMetadataAsync();
+    return res.headers;
+  }
+
+  protected async getRequestMetadataAsync(
+    url?: string | null
+  ): Promise<RequestMetadataResponse> {
+    if (this.isTokenExpiring()) {
+      await this.getAccessToken();
+    }
+
+    const headers = {
+      Authorization: 'Bearer ' + this.credentials.access_token,
+    };
+    return {headers};
+  }
+}

src/index.ts

@@ -27,6 +27,7 @@ export {IAMAuth, RequestMetadata} from './auth/iam';
 export {IdTokenClient, IdTokenProvider} from './auth/idtokenclient';
 export {Claims, JWTAccess} from './auth/jwtaccess';
 export {JWT, JWTOptions} from './auth/jwtclient';
+export {Impersonated, ImpersonatedOptions} from './auth/impersonated';
 export {
   Certificates,
   CodeChallengeMethod,

test/test.impersonated.ts

@@ -0,0 +1,72 @@
+/**
+ * Copyright 2019 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import * as assert from 'assert';
+import * as nock from 'nock';
+import {describe, it, afterEach} from 'mocha';
+import {Impersonated, JWT} from '../src';
+import {CredentialRequest} from '../src/auth/credentials';
+
+const PEM_PATH = './test/fixtures/private.pem';
+
+nock.disableNetConnect();
+
+const url = 'http://example.com';
+
+function createGTokenMock(body: CredentialRequest) {
+  return nock('https://www.googleapis.com')
+    .post('/oauth2/v4/token')
+    .reply(200, body);
+}
+
+describe('impersonated', () => {
+  afterEach(() => {
+    nock.cleanAll();
+  });
+  it('should request impersonated credentials on first request');
+  it.only('should refresh if access token has expired', async () => {
+    const scopes = [
+      nock(url).get('/').reply(200),
+      createGTokenMock({
+        access_token: 'abc123',
+      }),
+    ];
+    const jwt = new JWT(
+      'foo@serviceaccount.com',
+      PEM_PATH,
+      undefined,
+      ['http://bar', 'http://foo'],
+      'bar@subjectaccount.com'
+    );
+    await jwt.authorize();
+    const impersonated = new Impersonated({
+      sourceClient: jwt,
+      targetPrincipal: 'target@project.iam.gserviceaccount.com',
+      lifetime: 30,
+      delegates: [],
+      targetScopes: ['https://www.googleapis.com/auth/cloud-platform'],
+    });
+    impersonated.credentials.access_token = 'initial-access-token';
+    impersonated.credentials.expiry_date = Date.now() - 10000;
+    await impersonated.request({url});
+    assert.strictEqual(impersonated.credentials.access_token, 'abc123');
+    scopes.forEach(s => s.done());
+  });
+  it(
+    'should throw appropriate exception when 403 occurs refreshing impersonated credentials'
+  );
+  it('should throw appropriate exception when 403 occurs during request');
+});