From c67e15bb83ce9e1e94a0fc0681f813df6ec3fd30 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Thu, 11 Jul 2024 15:13:04 -0700 Subject: [PATCH 01/21] feat: Extend API Key Support --- .readme-partials.yaml | 20 ++++++++++++++++++++ src/auth/oauth2client.ts | 5 +++++ test/test.googleauth.ts | 4 +++- test/test.oauth2.ts | 7 +++++++ 4 files changed, 35 insertions(+), 1 deletion(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index cce6a02f..8e574123 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -220,6 +220,26 @@ body: |- This method will throw if the token is invalid. + #### Using an API Key + + An API key can be provided to the constructor: + ```js + const client = new OAuth2Client({ + apiKey: 'my-api-key' + }); + ``` + + Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. + + Additionally, an API key it can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: + ```js + const auth = new GoogleAuth({ + clientOptions: { + apiKey: 'my-api-key' + } + }) + ``` + ## JSON Web Tokens The Google Developers Console provides a `.json` file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account. diff --git a/src/auth/oauth2client.ts b/src/auth/oauth2client.ts index 4c60c5f9..5ec801b8 100644 --- a/src/auth/oauth2client.ts +++ b/src/auth/oauth2client.ts @@ -487,6 +487,10 @@ export interface OAuth2ClientEndpoints { } export interface OAuth2ClientOptions extends AuthClientOptions { + /** + * An API key to use, optional. + */ + apiKey?: string; clientId?: string; clientSecret?: string; redirectUri?: string; @@ -559,6 +563,7 @@ export class OAuth2Client extends AuthClient { this._clientId = opts.clientId; this._clientSecret = opts.clientSecret; this.redirectUri = opts.redirectUri; + this.apiKey = opts.apiKey; this.endpoints = { tokenInfoUrl: 'https://oauth2.googleapis.com/tokeninfo', diff --git a/test/test.googleauth.ts b/test/test.googleauth.ts index 3bb2ce95..3906bff7 100644 --- a/test/test.googleauth.ts +++ b/test/test.googleauth.ts @@ -1423,12 +1423,14 @@ describe('googleauth', () => { }); it('should pass options to the JWT constructor via constructor', async () => { + const apiKey = 'my-api-key'; const subject = 'science!'; const auth = new GoogleAuth({ keyFilename: './test/fixtures/private.json', - clientOptions: {subject}, + clientOptions: {apiKey, subject}, }); const client = (await auth.getClient()) as JWT; + assert.strictEqual(client.apiKey, apiKey); assert.strictEqual(client.subject, subject); }); diff --git a/test/test.oauth2.ts b/test/test.oauth2.ts index ebd42ef0..7c4d3446 100644 --- a/test/test.oauth2.ts +++ b/test/test.oauth2.ts @@ -74,6 +74,13 @@ describe('oauth2', () => { sandbox.restore(); }); + it('should accept and set an `apiKey`', () => { + const API_KEY = 'TEST_API_KEY'; + const client = new OAuth2Client({apiKey: API_KEY}); + + assert.equal(client.apiKey, API_KEY); + }); + it('should generate a valid consent page url', done => { const opts = { access_type: ACCESS_TYPE, From cfcc2a21eb0ec6ab3cc3c738ec20ec643e32b3bf Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Thu, 11 Jul 2024 22:16:59 +0000 Subject: [PATCH 02/21] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20?= =?UTF-8?q?post-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/README.md b/README.md index 55d86876..b0403046 100644 --- a/README.md +++ b/README.md @@ -264,6 +264,26 @@ console.log(tokenInfo.scopes); This method will throw if the token is invalid. +#### Using an API Key + +An API key can be provided to the constructor: +```js +const client = new OAuth2Client({ + apiKey: 'my-api-key' +}); +``` + +Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. + +Additionally, an API key it can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: +```js +const auth = new GoogleAuth({ + clientOptions: { + apiKey: 'my-api-key' + } +}) +``` + ## JSON Web Tokens The Google Developers Console provides a `.json` file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account. From 0b1710e03c98f54e5ac207382f1ed2881819e683 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Thu, 11 Jul 2024 15:37:18 -0700 Subject: [PATCH 03/21] feat: Support `apiKey` as an ADC fallback --- src/auth/googleauth.ts | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index 40b71d2f..f48411ae 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -395,7 +395,7 @@ export class GoogleAuth { } private async getApplicationDefaultAsync( - options: AuthClientOptions = {} + options: AuthClientOptions | OAuth2ClientOptions = {} ): Promise { // If we've already got a cached credential, return it. // This will also preserve one's configured quota project, in case they @@ -451,6 +451,13 @@ export class GoogleAuth { ); } + // No ADC, but perhaps there's an API key available... + if ('apiKey' in options && options.apiKey) { + const client = await this.fromAPIKey(options.apiKey, options); + client.scopes = this.scopes; + return await this.prepareAndCacheADC(client, quotaProjectIdOverride); + } + throw new Error( 'Could not load the default credentials. Browse to https://cloud.google.com/docs/authentication/getting-started for more information.' ); From d6c51f909bb4476142ba38da0988e6428c9f897b Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:17:47 -0700 Subject: [PATCH 04/21] refactor: Move `apiKey` to base client options --- src/auth/authclient.ts | 6 ++++++ src/auth/oauth2client.ts | 7 ------- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/src/auth/authclient.ts b/src/auth/authclient.ts index 69301db8..2f2b384c 100644 --- a/src/auth/authclient.ts +++ b/src/auth/authclient.ts @@ -72,6 +72,10 @@ interface AuthJSONOptions { */ export interface AuthClientOptions extends Partial> { + /** + * An API key to use, optional. + */ + apiKey?: string; credentials?: Credentials; /** @@ -170,6 +174,7 @@ export abstract class AuthClient extends EventEmitter implements CredentialsClient { + apiKey?: string; projectId?: string | null; /** * The quota project ID. The quota project can be used by client libraries for the billing purpose. @@ -188,6 +193,7 @@ export abstract class AuthClient const options = originalOrCamelOptions(opts); // Shared auth options + this.apiKey = opts.apiKey; this.projectId = options.get('project_id') ?? null; this.quotaProjectId = options.get('quota_project_id'); this.credentials = options.get('credentials') ?? {}; diff --git a/src/auth/oauth2client.ts b/src/auth/oauth2client.ts index 5ec801b8..fb813a7f 100644 --- a/src/auth/oauth2client.ts +++ b/src/auth/oauth2client.ts @@ -487,10 +487,6 @@ export interface OAuth2ClientEndpoints { } export interface OAuth2ClientOptions extends AuthClientOptions { - /** - * An API key to use, optional. - */ - apiKey?: string; clientId?: string; clientSecret?: string; redirectUri?: string; @@ -532,8 +528,6 @@ export class OAuth2Client extends AuthClient { // TODO: refactor tests to make this private _clientSecret?: string; - apiKey?: string; - refreshHandler?: GetRefreshHandlerCallback; /** @@ -563,7 +557,6 @@ export class OAuth2Client extends AuthClient { this._clientId = opts.clientId; this._clientSecret = opts.clientSecret; this.redirectUri = opts.redirectUri; - this.apiKey = opts.apiKey; this.endpoints = { tokenInfoUrl: 'https://oauth2.googleapis.com/tokeninfo', From 7a5c54c859cac0d63c52a831a4dbea6ff5d37476 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:20:40 -0700 Subject: [PATCH 05/21] docs: clarity --- .readme-partials.yaml | 4 +- README.md | 341 +++++++++++++++++++++++------------------- 2 files changed, 192 insertions(+), 153 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index 8e574123..5fb3e97e 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -231,7 +231,7 @@ body: |- Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. - Additionally, an API key it can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: + Additionally, an API key can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: ```js const auth = new GoogleAuth({ clientOptions: { @@ -240,6 +240,8 @@ body: |- }) ``` + Availability varies by API. + ## JSON Web Tokens The Google Developers Console provides a `.json` file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account. diff --git a/README.md b/README.md index b0403046..763b1c1c 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,6 @@ -[//]: # "This README.md file is auto-generated, all changes to this file will be lost." -[//]: # "To regenerate it, use `python -m synthtool`." +[//]: # 'This README.md file is auto-generated, all changes to this file will be lost.' +[//]: # 'To regenerate it, use `python -m synthtool`.' + Google Cloud Platform logo # [Google Auth Library: Node.js Client](https://github.com/googleapis/google-auth-library-nodejs) @@ -7,18 +8,14 @@ [![release level](https://img.shields.io/badge/release%20level-stable-brightgreen.svg?style=flat)](https://cloud.google.com/terms/launch-stages) [![npm version](https://img.shields.io/npm/v/google-auth-library.svg)](https://www.npmjs.org/package/google-auth-library) - - - This is Google's officially supported [node.js](http://nodejs.org/) client library for using OAuth 2.0 authorization and authentication with Google APIs. - A comprehensive list of changes in each version may be found in [the CHANGELOG](https://github.com/googleapis/google-auth-library-nodejs/blob/main/CHANGELOG.md). -* [Google Auth Library Node.js Client API Reference][client-docs] -* [Google Auth Library Documentation][product-docs] -* [github.com/googleapis/google-auth-library-nodejs](https://github.com/googleapis/google-auth-library-nodejs) +- [Google Auth Library Node.js Client API Reference][client-docs] +- [Google Auth Library Documentation][product-docs] +- [github.com/googleapis/google-auth-library-nodejs](https://github.com/googleapis/google-auth-library-nodejs) Read more about the client libraries for Cloud APIs, including the older Google APIs Client Libraries, in [Client Libraries Explained][explained]. @@ -27,15 +24,14 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained]. **Table of contents:** +- [Quickstart](#quickstart) -* [Quickstart](#quickstart) - - * [Installing the client library](#installing-the-client-library) + - [Installing the client library](#installing-the-client-library) -* [Samples](#samples) -* [Versioning](#versioning) -* [Contributing](#contributing) -* [License](#license) +- [Samples](#samples) +- [Versioning](#versioning) +- [Contributing](#contributing) +- [License](#license) ## Quickstart @@ -46,7 +42,9 @@ npm install google-auth-library ``` ## Ways to authenticate + This library provides a variety of ways to authenticate to your Google services. + - [Application Default Credentials](#choosing-the-correct-credential-type-automatically) - Use Application Default Credentials when you use a single identity for all users in your application. Especially useful for applications running on Google Cloud. Application Default Credentials also support workload identity federation to access Google Cloud resources from non-Google Cloud platforms. - [OAuth 2](#oauth2) - Use OAuth2 when you need to perform actions on behalf of the end user. - [JSON Web Tokens](#json-web-tokens) - Use JWT when you are using a single identity for all users. Especially useful for server->server or server->API communication. @@ -57,6 +55,7 @@ This library provides a variety of ways to authenticate to your Google services. - [Downscoped Client](#downscoped-client) - Use Downscoped Client with Credential Access Boundary to generate a short-lived credential with downscoped, restricted IAM permissions that can use for Cloud Storage. ## Application Default Credentials + This library provides an implementation of [Application Default Credentials](https://cloud.google.com/docs/authentication/getting-started) for Node.js. The [Application Default Credentials](https://cloud.google.com/docs/authentication/getting-started) provide a simple way to get authorization credentials for use in calling Google APIs. They are best suited for cases when the call needs to have the same identity and authorization level for the application independent of the user. This is the recommended approach to authorize calls to Cloud APIs, particularly when you're building an application that uses Google Cloud Platform. @@ -67,7 +66,7 @@ Application Default Credentials also support workload identity federation to acc To use Application Default Credentials, You first need to download a set of JSON credentials for your project. Go to **APIs & Auth** > **Credentials** in the [Google Developers Console](https://console.cloud.google.com/) and select **Service account** from the **Add credentials** dropdown. -> This file is your *only copy* of these credentials. It should never be +> This file is your _only copy_ of these credentials. It should never be > committed with your source code, and should be stored securely. Once downloaded, store the path to this file in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. @@ -76,7 +75,6 @@ Once downloaded, store the path to this file in the `GOOGLE_APPLICATION_CREDENTI Before making your API call, you must be sure the API you're calling has been enabled. Go to **APIs & Auth** > **APIs** in the [Google Developers Console](https://console.cloud.google.com/) and enable the APIs you'd like to call. For the example below, you must enable the `DNS API`. - #### Choosing the correct credential type automatically Rather than manually creating an OAuth2 client, JWT client, or Compute client, the auth library can create the correct credential type for you, depending upon the environment your code is running under. @@ -89,17 +87,17 @@ The code below shows how to retrieve a default credential type, depending upon t const {GoogleAuth} = require('google-auth-library'); /** -* Instead of specifying the type of client you'd like to use (JWT, OAuth2, etc) -* this library will automatically choose the right client based on the environment. -*/ + * Instead of specifying the type of client you'd like to use (JWT, OAuth2, etc) + * this library will automatically choose the right client based on the environment. + */ async function main() { const auth = new GoogleAuth({ - scopes: 'https://www.googleapis.com/auth/cloud-platform' + scopes: 'https://www.googleapis.com/auth/cloud-platform', }); const client = await auth.getClient(); const projectId = await auth.getProjectId(); const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`; - const res = await client.request({ url }); + const res = await client.request({url}); console.log(res.data); } @@ -118,7 +116,7 @@ For more information about OAuth2 and how it works, [see here](https://developer Let's take a look at a complete example. -``` js +```js const {OAuth2Client} = require('google-auth-library'); const http = require('http'); const url = require('url'); @@ -129,8 +127,8 @@ const destroyer = require('server-destroy'); const keys = require('./oauth2.keys.json'); /** -* Start by acquiring a pre-authenticated oAuth2 client. -*/ + * Start by acquiring a pre-authenticated oAuth2 client. + */ async function main() { const oAuth2Client = await getAuthenticatedClient(); // Make a simple request to the People API using our pre-authenticated client. The `request()` method @@ -148,9 +146,9 @@ async function main() { } /** -* Create a new OAuth2Client, and go through the OAuth2 content -* workflow. Return the full client to the callback. -*/ + * Create a new OAuth2Client, and go through the OAuth2 content + * workflow. Return the full client to the callback. + */ function getAuthenticatedClient() { return new Promise((resolve, reject) => { // create an oAuth client to authorize the API call. Secrets are kept in a `keys.json` file, @@ -205,12 +203,12 @@ main().catch(console.error); #### Handling token events -This library will automatically obtain an `access_token`, and automatically refresh the `access_token` if a `refresh_token` is present. The `refresh_token` is only returned on the [first authorization](https://github.com/googleapis/google-api-nodejs-client/issues/750#issuecomment-304521450), so if you want to make sure you store it safely. An easy way to make sure you always store the most recent tokens is to use the `tokens` event: +This library will automatically obtain an `access_token`, and automatically refresh the `access_token` if a `refresh_token` is present. The `refresh_token` is only returned on the [first authorization](https://github.com/googleapis/google-api-nodejs-client/issues/750#issuecomment-304521450), so if you want to make sure you store it safely. An easy way to make sure you always store the most recent tokens is to use the `tokens` event: ```js const client = await auth.getClient(); -client.on('tokens', (tokens) => { +client.on('tokens', tokens => { if (tokens.refresh_token) { // store the refresh_token in my database! console.log(tokens.refresh_token); @@ -219,21 +217,23 @@ client.on('tokens', (tokens) => { }); const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`; -const res = await client.request({ url }); +const res = await client.request({url}); // The `tokens` event would now be raised if this was the first request ``` #### Retrieve access token + With the code returned, you can ask for an access token as shown below: -``` js +```js const tokens = await oauth2Client.getToken(code); // Now tokens contains an access_token and an optional refresh_token. Save them. oauth2Client.setCredentials(tokens); ``` #### Obtaining a new Refresh Token -If you need to obtain a new `refresh_token`, ensure the call to `generateAuthUrl` sets the `access_type` to `offline`. The refresh token will only be returned for the first authorization by the user. To force consent, set the `prompt` property to `consent`: + +If you need to obtain a new `refresh_token`, ensure the call to `generateAuthUrl` sets the `access_type` to `offline`. The refresh token will only be returned for the first authorization by the user. To force consent, set the `prompt` property to `consent`: ```js // Generate the url that will be used for the consent dialog. @@ -246,13 +246,14 @@ const authorizeUrl = oAuth2Client.generateAuthUrl({ // consents to providing access. For illustration purposes, // setting the prompt to 'consent' will force this consent // every time, forcing a refresh_token to be returned. - prompt: 'consent' + prompt: 'consent', }); ``` #### Checking `access_token` information + After obtaining and storing an `access_token`, at a later time you may want to go check the expiration date, -original scopes, or audience for the token. To get the token info, you can use the `getTokenInfo` method: +original scopes, or audience for the token. To get the token info, you can use the `getTokenInfo` method: ```js // after acquiring an oAuth2Client... @@ -267,27 +268,30 @@ This method will throw if the token is invalid. #### Using an API Key An API key can be provided to the constructor: + ```js const client = new OAuth2Client({ - apiKey: 'my-api-key' + apiKey: 'my-api-key', }); ``` Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. -Additionally, an API key it can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: +Additionally, an API key can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: + ```js const auth = new GoogleAuth({ clientOptions: { - apiKey: 'my-api-key' - } -}) + apiKey: 'my-api-key', + }, +}); ``` ## JSON Web Tokens + The Google Developers Console provides a `.json` file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account. -``` js +```js const {JWT} = require('google-auth-library'); const keys = require('./jwt.keys.json'); @@ -308,7 +312,8 @@ main().catch(console.error); The parameters for the JWT auth client including how to use it with a `.pem` file are explained in [samples/jwt.js](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js). #### Loading credentials from environment variables -Instead of loading credentials from a key file, you can also provide them using an environment variable and the `GoogleAuth.fromJSON()` method. This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc). + +Instead of loading credentials from a key file, you can also provide them using an environment variable and the `GoogleAuth.fromJSON()` method. This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc). Start by exporting your credentials: @@ -326,6 +331,7 @@ $ export CREDS='{ "client_x509_cert_url": "your-cert-url" }' ``` + Now you can create a new client from the credentials: ```js @@ -351,20 +357,22 @@ main().catch(console.error); ``` #### Using a Proxy + You can set the `HTTPS_PROXY` or `https_proxy` environment variables to proxy HTTPS requests. When `HTTPS_PROXY` or `https_proxy` are set, they will be used to proxy SSL requests that do not have an explicit proxy configuration option present. ## Compute + If your application is running on Google Cloud Platform, you can authenticate using the default service account or by specifying a specific service account. -**Note**: In most cases, you will want to use [Application Default Credentials](#choosing-the-correct-credential-type-automatically). Direct use of the `Compute` class is for very specific scenarios. +**Note**: In most cases, you will want to use [Application Default Credentials](#choosing-the-correct-credential-type-automatically). Direct use of the `Compute` class is for very specific scenarios. -``` js +```js const {auth, Compute} = require('google-auth-library'); async function main() { const client = new Compute({ // Specifying the service account email is optional. - serviceAccountEmail: 'my-service-account@example.com' + serviceAccountEmail: 'my-service-account@example.com', }); const projectId = await auth.getProjectId(); const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`; @@ -385,6 +393,7 @@ This lets you access Google Cloud resources directly, eliminating the maintenanc ### Accessing resources from AWS In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed: + - A workload identity pool needs to be created. - AWS needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS). - Permission to impersonate a service account needs to be granted to the external identity. @@ -407,6 +416,7 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: + - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$AWS_PROVIDER_ID`: The AWS provider ID. @@ -423,6 +433,7 @@ You can now [start using the Auth library](#using-external-identities) to call G ### Accessing resources from AWS using a custom AWS security credentials supplier. In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed: + - A workload identity pool needs to be created. - AWS needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS). - Permission to impersonate a service account needs to be granted to the external identity. @@ -450,10 +461,11 @@ class AwsSupplier implements AwsSecurityCredentialsSupplier { } const clientOptions = { - audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. + audience: + '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request', // Set the subject token type. - aws_security_credentials_supplier: new AwsSupplier() // Set the custom supplier. -} + aws_security_credentials_supplier: new AwsSupplier(), // Set the custom supplier. +}; const client = new AwsClient(clientOptions); ``` @@ -462,16 +474,16 @@ Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using- Where the following variables need to be substituted: -* `$PROJECT_NUMBER`: The Google Cloud project number. -* `$WORKLOAD_POOL_ID`: The workload pool ID. -* `$PROVIDER_ID`: The provider ID. - +- `$PROJECT_NUMBER`: The Google Cloud project number. +- `$WORKLOAD_POOL_ID`: The workload pool ID. +- `$PROVIDER_ID`: The provider ID. The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config). ### Access resources from Microsoft Azure In order to access Google Cloud resources from Microsoft Azure, the following requirements are needed: + - A workload identity pool needs to be created. - Azure needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from Azure). - The Azure tenant needs to be configured for identity federation. @@ -495,6 +507,7 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: + - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$AZURE_PROVIDER_ID`: The Azure provider ID. @@ -507,6 +520,7 @@ You can now [start using the Auth library](#using-external-identities) to call G ### Accessing resources from an OIDC identity provider In order to access Google Cloud resources from an identity provider that supports [OpenID Connect (OIDC)](https://openid.net/connect/), the following requirements are needed: + - A workload identity pool needs to be created. - An OIDC identity provider needs to be added in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from the identity provider). - Permission to impersonate a service account needs to be granted to the external identity. @@ -540,6 +554,7 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: + - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$OIDC_PROVIDER_ID`: The OIDC provider ID. @@ -570,6 +585,7 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: + - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$OIDC_PROVIDER_ID`: The OIDC provider ID. @@ -597,10 +613,11 @@ class CustomSupplier implements SubjectTokenSupplier { } const clientOptions = { - audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. + audience: + '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type. - subject_token_supplier: new CustomSupplier() // Set the custom supplier. -} + subject_token_supplier: new CustomSupplier(), // Set the custom supplier. +}; const client = new CustomSupplier(clientOptions); ``` @@ -609,9 +626,9 @@ Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using- Where the following variables need to be substituted: -* `$PROJECT_NUMBER`: The Google Cloud project number. -* `$WORKLOAD_POOL_ID`: The workload pool ID. -* `$PROVIDER_ID`: The provider ID. +- `$PROJECT_NUMBER`: The Google Cloud project number. +- `$WORKLOAD_POOL_ID`: The workload pool ID. +- `$PROVIDER_ID`: The provider ID. The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config). @@ -627,8 +644,9 @@ gcloud auth application-default login --login-config=$LOGIN_CONFIG ``` Where the following variable needs to be substituted: + - `$LOGIN_CONFIG`: The login config file generated with the cloud console or - [gcloud iam workforce-pools create-login-config](https://cloud.google.com/sdk/gcloud/reference/iam/workforce-pools/create-login-config) + [gcloud iam workforce-pools create-login-config](https://cloud.google.com/sdk/gcloud/reference/iam/workforce-pools/create-login-config) This will open a browser flow for you to sign in via the configured third party identity provider and then will store the external account authorized user configuration at the well known ADC location. @@ -666,7 +684,9 @@ gcloud iam workload-identity-pools create-cred-config \ # --executable-output-file=$EXECUTABLE_OUTPUT_FILE \ --output-file /path/to/generated/config.json ``` + Where the following variables need to be substituted: + - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$PROVIDER_ID`: The OIDC or SAML provider ID. @@ -694,6 +714,7 @@ using the command specified. The executable's output must adhere to the response specified below. It must output the response to stdout. A sample successful executable OIDC response: + ```json { "version": 1, @@ -705,6 +726,7 @@ A sample successful executable OIDC response: ``` A sample successful executable SAML response: + ```json { "version": 1, @@ -714,10 +736,12 @@ A sample successful executable SAML response: "expiration_time": 1620499962 } ``` + For successful responses, the `expiration_time` field is only required when an output file is specified in the credential configuration. A sample executable error response: + ```json { "version": 1, @@ -726,41 +750,47 @@ A sample executable error response: "message": "Caller not authorized." } ``` + These are all required fields for an error response. The code and message fields will be used by the library as part of the thrown exception. Response format fields summary: -* `version`: The version of the JSON output. Currently, only version 1 is supported. -* `success`: The status of the response. When true, the response must contain the 3rd party token - and token type. The response must also contain the expiration time if an output file was specified in the credential configuration. - The executable must also exit with exit code 0. - When false, the response must contain the error code and message fields and exit with a non-zero value. -* `token_type`: The 3rd party subject token type. Must be *urn:ietf:params:oauth:token-type:jwt*, -*urn:ietf:params:oauth:token-type:id_token*, or *urn:ietf:params:oauth:token-type:saml2*. -* `id_token`: The 3rd party OIDC token. -* `saml_response`: The 3rd party SAML response. -* `expiration_time`: The 3rd party subject token expiration time in seconds (unix epoch time). -* `code`: The error code string. -* `message`: The error message. + +- `version`: The version of the JSON output. Currently, only version 1 is supported. +- `success`: The status of the response. When true, the response must contain the 3rd party token + and token type. The response must also contain the expiration time if an output file was specified in the credential configuration. + The executable must also exit with exit code 0. + When false, the response must contain the error code and message fields and exit with a non-zero value. +- `token_type`: The 3rd party subject token type. Must be _urn:ietf:params:oauth:token-type:jwt_, + _urn:ietf:params:oauth:token-type:id_token_, or _urn:ietf:params:oauth:token-type:saml2_. +- `id_token`: The 3rd party OIDC token. +- `saml_response`: The 3rd party SAML response. +- `expiration_time`: The 3rd party subject token expiration time in seconds (unix epoch time). +- `code`: The error code string. +- `message`: The error message. All response types must include both the `version` and `success` fields. -* Successful responses must include the `token_type` and one of -`id_token` or `saml_response`. The `expiration_time` field must also be present if an output file was specified in -the credential configuration. -* Error responses must include both the `code` and `message` fields. + +- Successful responses must include the `token_type` and one of + `id_token` or `saml_response`. The `expiration_time` field must also be present if an output file was specified in + the credential configuration. +- Error responses must include both the `code` and `message` fields. The library will populate the following environment variables when the executable is run: -* `GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE`: The audience field from the credential configuration. Always present. -* `GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL`: The service account email. Only present when service account impersonation is used. -* `GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE`: The output file location from the credential configuration. Only present when specified in the credential configuration. -* `GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE`: This expected subject token type. Always present. + +- `GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE`: The audience field from the credential configuration. Always present. +- `GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL`: The service account email. Only present when service account impersonation is used. +- `GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE`: The output file location from the credential configuration. Only present when specified in the credential configuration. +- `GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE`: This expected subject token type. Always present. These environment variables can be used by the executable to avoid hard-coding these values. ##### Security considerations + The following security practices are highly recommended: -* Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. -* The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. + +- Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. +- The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. Given the complexity of using executable-sourced credentials, it is recommended to use the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party @@ -770,6 +800,7 @@ You can now [use the Auth library](#using-external-identities) to call Google Cl resources from an OIDC or SAML provider. #### Configurable Token Lifetime + When creating a credential configuration with workload identity federation using service account impersonation, you can provide an optional argument to configure the service account access token lifetime. To generate the configuration with configurable token lifetime, run the following command (this example uses an AWS configuration, but the token lifetime can be configured for all workload identity federation providers): @@ -784,7 +815,8 @@ gcloud iam workload-identity-pools create-cred-config \ --service-account-token-lifetime-seconds $TOKEN_LIFETIME ``` - Where the following variables need to be substituted: +Where the following variables need to be substituted: + - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$AWS_PROVIDER_ID`: The AWS provider ID. @@ -812,6 +844,7 @@ Active Directory Federation Services (AD FS), Okta, and others. In order to access Google Cloud resources from an identity provider that supports [OpenID Connect (OIDC)](https://openid.net/connect/), the following requirements are needed: + - A workforce identity pool needs to be created. - An OIDC or SAML 2.0 identity provider needs to be added in the workforce pool. @@ -849,7 +882,9 @@ gcloud iam workforce-pools create-cred-config \ # --credential-source-field-name "id_token" \ --output-file=/path/to/generated/config.json ``` + Where the following variables need to be substituted: + - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$PATH_TO_OIDC_ID_TOKEN`: The file path used to retrieve the OIDC token. @@ -868,6 +903,7 @@ gcloud iam workforce-pools create-cred-config \ ``` Where the following variables need to be substituted: + - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$PATH_TO_SAML_ASSERTION`: The file path used to retrieve the base64-encoded SAML assertion. @@ -894,11 +930,12 @@ gcloud iam workforce-pools create-cred-config \ ``` Where the following variables need to be substituted: + - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$URL_TO_RETURN_OIDC_ID_TOKEN`: The URL of the local server endpoint. - `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to - `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`. + `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`. - `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project). To generate a URL-sourced SAML configuration, run the following command: @@ -917,11 +954,12 @@ gcloud iam workforce-pools create-cred-config \ These commands generate the configuration file in the specified output file. Where the following variables need to be substituted: + - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$URL_TO_GET_SAML_ASSERTION`: The URL of the local server endpoint. - `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to - `$URL_TO_GET_SAML_ASSERTION`, e.g. `Metadata-Flavor=Google`. + `$URL_TO_GET_SAML_ASSERTION`, e.g. `Metadata-Flavor=Google`. - `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project). ### Using Executable-sourced workforce credentials with OIDC and SAML @@ -952,7 +990,9 @@ gcloud iam workforce-pools create-cred-config \ --workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \ --output-file /path/to/generated/config.json ``` + Where the following variables need to be substituted: + - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$SUBJECT_TOKEN_TYPE`: The subject token type. @@ -982,9 +1022,11 @@ Refer to the [using executable-sourced credentials with Workload Identity Federa above for the executable response specification. ##### Security considerations + The following security practices are highly recommended: -* Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. -* The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. + +- Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. +- The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. Given the complexity of using executable-sourced credentials, it is recommended to use the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party @@ -1013,10 +1055,11 @@ class CustomSupplier implements SubjectTokenSupplier { } const clientOptions = { - audience: '//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. + audience: + '//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type. - subject_token_supplier: new CustomSupplier() // Set the custom supplier. -} + subject_token_supplier: new CustomSupplier(), // Set the custom supplier. +}; const client = new CustomSupplier(clientOptions); ``` @@ -1025,8 +1068,8 @@ Where the audience is: `//iam.googleapis.com/locations/global/workforcePools/$WO Where the following variables need to be substituted: -* `WORKFORCE_POOL_ID`: The worforce pool ID. -* `$PROVIDER_ID`: The provider ID. +- `WORKFORCE_POOL_ID`: The worforce pool ID. +- `$PROVIDER_ID`: The provider ID. and the workforce pool user project is the project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project). @@ -1047,13 +1090,13 @@ The library can now automatically choose the right type of client and initialize ```js async function main() { const auth = new GoogleAuth({ - scopes: 'https://www.googleapis.com/auth/cloud-platform' + scopes: 'https://www.googleapis.com/auth/cloud-platform', }); const client = await auth.getClient(); const projectId = await auth.getProjectId(); // List all buckets in a project. const url = `https://storage.googleapis.com/storage/v1/b?project=${projectId}`; - const res = await client.request({ url }); + const res = await client.request({url}); console.log(res.data); } ``` @@ -1089,10 +1132,13 @@ async function main() { ``` #### Security Considerations + Note that this library does not perform any validation on the token_url, token_info_url, or service_account_impersonation_url fields of the credential configuration. It is not recommended to use a credential configuration that you did not generate with the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain. ## Working with ID Tokens + ### Fetching ID Tokens + If your application is running on Cloud Run or Cloud Functions, or using Cloud Identity-Aware Proxy (IAP), you will need to fetch an ID token to access your application. For this, use the method `getIdTokenClient` on the `GoogleAuth` client. @@ -1105,7 +1151,7 @@ For invoking Cloud Functions, your service account will need the [`Function Invoker`](https://cloud.google.com/functions/docs/securing/authenticating#function-to-function) IAM permission. -``` js +```js // Make a request to a protected Cloud Run service. const {GoogleAuth} = require('google-auth-library'); @@ -1125,7 +1171,7 @@ A complete example can be found in [`samples/idtokens-serverless.js`](https://gi For invoking Cloud Identity-Aware Proxy, you will need to pass the Client ID used when you set up your protected resource as the target audience. -``` js +```js // Make a request to a protected Cloud Identity-Aware Proxy (IAP) resource const {GoogleAuth} = require('google-auth-library'); @@ -1165,7 +1211,7 @@ const ticket = await oAuth2Client.verifySignedJwtWithCertsAsync( ); // Print out the info contained in the IAP ID token -console.log(ticket) +console.log(ticket); ``` A complete example can be found in [`samples/verifyIdToken-iap.js`](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken-iap.js). @@ -1187,11 +1233,10 @@ set of scopes. ### Sample Usage ```javascript -const { GoogleAuth, Impersonated } = require('google-auth-library'); -const { SecretManagerServiceClient } = require('@google-cloud/secret-manager'); +const {GoogleAuth, Impersonated} = require('google-auth-library'); +const {SecretManagerServiceClient} = require('@google-cloud/secret-manager'); async function main() { - // Acquire source credentials: const auth = new GoogleAuth(); const client = await auth.getClient(); @@ -1202,7 +1247,7 @@ async function main() { targetPrincipal: 'impersonated-account@projectID.iam.gserviceaccount.com', lifetime: 30, delegates: [], - targetScopes: ['https://www.googleapis.com/auth/cloud-platform'] + targetScopes: ['https://www.googleapis.com/auth/cloud-platform'], }); // Get impersonated credentials: @@ -1210,8 +1255,9 @@ async function main() { // Do something with `authHeaders.Authorization`. // Use impersonated credentials: - const url = 'https://www.googleapis.com/storage/v1/b?project=anotherProjectID' - const resp = await targetClient.request({ url }); + const url = + 'https://www.googleapis.com/storage/v1/b?project=anotherProjectID'; + const resp = await targetClient.request({url}); for (const bucket of resp.data.items) { console.log(bucket.name); } @@ -1226,14 +1272,15 @@ async function main() { getClient: () => targetClient, }, }); - const secretName = 'projects/anotherProjectNumber/secrets/someProjectName/versions/1'; + const secretName = + 'projects/anotherProjectNumber/secrets/someProjectName/versions/1'; const [accessResponse] = await smClient.accessSecretVersion({ name: secretName, }); const responsePayload = accessResponse.payload.data.toString('utf8'); // Do something with the secret contained in `responsePayload`. -}; +} main(); ``` @@ -1248,12 +1295,13 @@ The `DownscopedClient` class can be used to produce a downscoped access token fr > Notice: Only Cloud Storage supports Credential Access Boundaries for now. ### Sample Usage + There are two entities needed to generate and use credentials generated from Downscoped Client with Credential Access Boundaries. - Token broker: This is the entity with elevated permissions. This entity has the permissions needed to generate downscoped tokens. The common pattern of usage is to have a token broker with elevated access generate these downscoped credentials from higher access source credentials and pass the downscoped short-lived access tokens to a token consumer via some secure authenticated channel for limited access to Google Cloud Storage resources. -``` js +```js const {GoogleAuth, DownscopedClient} = require('google-auth-library'); // Define CAB rules which will restrict the downscoped token to have readonly // access to objects starting with "customer-a" in bucket "bucket_name". @@ -1266,8 +1314,8 @@ const cabRules = { availabilityCondition: { expression: `resource.name.startsWith('projects/_/buckets/` + - `bucket_name/objects/customer-a)` - } + `bucket_name/objects/customer-a)`, + }, }, ], }, @@ -1275,7 +1323,7 @@ const cabRules = { // This will use ADC to get the credentials used for the downscoped client. const googleAuth = new GoogleAuth({ - scopes: ['https://www.googleapis.com/auth/cloud-platform'] + scopes: ['https://www.googleapis.com/auth/cloud-platform'], }); // Obtain an authenticated client via ADC. @@ -1299,7 +1347,7 @@ The broker will instantiate downscoped credentials instances that can be used to - Token consumer: This is the consumer of the downscoped tokens. This entity does not have the direct ability to generate access tokens and instead relies on the token broker to provide it with downscoped tokens to run operations on GCS buckets. It is assumed that the downscoped token consumer may have its own mechanism to authenticate itself with the token broker. -``` js +```js const {OAuth2Client} = require('google-auth-library'); const {Storage} = require('@google-cloud/storage'); @@ -1318,7 +1366,7 @@ oauth2Client.refreshHandler = async () => { return { access_token: refreshedAccessToken.token, expiry_date: refreshedAccessToken.expirationTime, - } + }; }; // Use the consumer client to define storageOptions and create a GCS object. @@ -1330,45 +1378,42 @@ const storageOptions = { const storage = new Storage(storageOptions); const downloadFile = await storage - .bucket('bucket_name') - .file('customer-a-data.txt') - .download(); + .bucket('bucket_name') + .file('customer-a-data.txt') + .download(); console.log(downloadFile.toString('utf8')); main().catch(console.error); ``` - ## Samples Samples are in the [`samples/`](https://github.com/googleapis/google-auth-library-nodejs/tree/main/samples) directory. Each sample's `README.md` has instructions for running its sample. -| Sample | Source Code | Try it | -| --------------------------- | --------------------------------- | ------ | -| Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/adc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/adc.js,samples/README.md) | -| Authenticate Explicit | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateExplicit.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateExplicit.js,samples/README.md) | -| Authenticate Implicit With Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateImplicitWithAdc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateImplicitWithAdc.js,samples/README.md) | -| Compute | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/compute.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/compute.js,samples/README.md) | -| Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/credentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/credentials.js,samples/README.md) | -| Downscopedclient | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/downscopedclient.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/downscopedclient.js,samples/README.md) | -| Headers | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/headers.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/headers.js,samples/README.md) | -| Id Token From Impersonated Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromImpersonatedCredentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromImpersonatedCredentials.js,samples/README.md) | -| Id Token From Metadata Server | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromMetadataServer.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromMetadataServer.js,samples/README.md) | -| Id Token From Service Account | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromServiceAccount.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromServiceAccount.js,samples/README.md) | -| ID Tokens for Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-iap.js,samples/README.md) | -| ID Tokens for Serverless | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-serverless.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-serverless.js,samples/README.md) | -| Jwt | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/jwt.js,samples/README.md) | -| Keepalive | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keepalive.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keepalive.js,samples/README.md) | -| Keyfile | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keyfile.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keyfile.js,samples/README.md) | -| Oauth2-code Verifier | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2-codeVerifier.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2-codeVerifier.js,samples/README.md) | -| Oauth2 | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2.js,samples/README.md) | -| Sign Blob | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlob.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlob.js,samples/README.md) | -| Sign Blob Impersonated | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlobImpersonated.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlobImpersonated.js,samples/README.md) | -| Verify Google Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyGoogleIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyGoogleIdToken.js,samples/README.md) | -| Verifying ID Tokens from Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken-iap.js,samples/README.md) | -| Verify Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken.js,samples/README.md) | - - +| Sample | Source Code | Try it | +| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/adc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/adc.js,samples/README.md) | +| Authenticate Explicit | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateExplicit.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateExplicit.js,samples/README.md) | +| Authenticate Implicit With Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateImplicitWithAdc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateImplicitWithAdc.js,samples/README.md) | +| Compute | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/compute.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/compute.js,samples/README.md) | +| Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/credentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/credentials.js,samples/README.md) | +| Downscopedclient | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/downscopedclient.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/downscopedclient.js,samples/README.md) | +| Headers | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/headers.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/headers.js,samples/README.md) | +| Id Token From Impersonated Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromImpersonatedCredentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromImpersonatedCredentials.js,samples/README.md) | +| Id Token From Metadata Server | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromMetadataServer.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromMetadataServer.js,samples/README.md) | +| Id Token From Service Account | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromServiceAccount.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromServiceAccount.js,samples/README.md) | +| ID Tokens for Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-iap.js,samples/README.md) | +| ID Tokens for Serverless | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-serverless.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-serverless.js,samples/README.md) | +| Jwt | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/jwt.js,samples/README.md) | +| Keepalive | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keepalive.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keepalive.js,samples/README.md) | +| Keyfile | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keyfile.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keyfile.js,samples/README.md) | +| Oauth2-code Verifier | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2-codeVerifier.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2-codeVerifier.js,samples/README.md) | +| Oauth2 | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2.js,samples/README.md) | +| Sign Blob | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlob.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlob.js,samples/README.md) | +| Sign Blob Impersonated | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlobImpersonated.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlobImpersonated.js,samples/README.md) | +| Verify Google Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyGoogleIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyGoogleIdToken.js,samples/README.md) | +| Verifying ID Tokens from Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken-iap.js,samples/README.md) | +| Verify Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken.js,samples/README.md) | The [Google Auth Library Node.js Client API Reference][client-docs] documentation also contains samples. @@ -1384,9 +1429,9 @@ as soon as possible to an actively supported LTS version. Google's client libraries support legacy versions of Node.js runtimes on a best-efforts basis with the following warnings: -* Legacy versions are not tested in continuous integration. -* Some security patches and features cannot be backported. -* Dependencies cannot be kept up-to-date. +- Legacy versions are not tested in continuous integration. +- Some security patches and features cannot be backported. +- Dependencies cannot be kept up-to-date. Client libraries targeting some end-of-life versions of Node.js are available, and can be installed through npm [dist-tags](https://docs.npmjs.com/cli/dist-tag). @@ -1398,18 +1443,11 @@ for versions compatible with Node.js 8. This library follows [Semantic Versioning](http://semver.org/). - - This library is considered to be **stable**. The code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues) or with an extensive deprecation period. Issues and requests against **stable** libraries are addressed with the highest priority. - - - - - More Information: [Google Cloud Platform Launch Stages][launch_stages] [launch_stages]: https://cloud.google.com/terms/launch-stages @@ -1435,5 +1473,4 @@ See [LICENSE](https://github.com/googleapis/google-auth-library-nodejs/blob/main [shell_img]: https://gstatic.com/cloudssh/images/open-btn.png [projects]: https://console.cloud.google.com/project [billing]: https://support.google.com/cloud/answer/6293499#enable-billing - [auth]: https://cloud.google.com/docs/authentication/getting-started From 247f384cc58171ed7a03ee87a033513f8775f1cb Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:25:38 -0700 Subject: [PATCH 06/21] refactor: API Key Support --- src/auth/googleauth.ts | 88 +++++++++++++++++++++++------------------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index f48411ae..39620e53 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -84,6 +84,11 @@ export interface ADCResponse { } export interface GoogleAuthOptions { + /** + * An API key to use, optional. Cannot be used with {@link GoogleAuthOptions.credentials `credentials`}. + */ + apiKey?: string; + /** * An `AuthClient` to use */ @@ -101,6 +106,7 @@ export interface GoogleAuthOptions { /** * Object containing client_email and private_key properties, or the * external account client options. + * Cannot be used with {@link GoogleAuthOptions.apiKey `apiKey`}. */ credentials?: JWTInput | ExternalAccountClientOptions; @@ -136,6 +142,8 @@ export const CLOUD_SDK_CLIENT_ID = '764086051850-6qr4p6gpi6hn506pt8ejuq83di341hur.apps.googleusercontent.com'; const GoogleAuthExceptionMessages = { + API_KEY_WITH_CREDENTIALS: + 'API Keys and Credentials are mutually exclusive authentication methods and cannot be used together.', NO_PROJECT_ID_FOUND: 'Unable to detect a Project Id in the current environment. \n' + 'To learn more about authentication and Google APIs, visit: \n' + @@ -144,6 +152,8 @@ const GoogleAuthExceptionMessages = { 'Unable to find credentials in current environment. \n' + 'To learn more about authentication and Google APIs, visit: \n' + 'https://cloud.google.com/docs/authentication/getting-started', + NO_ADC_FOUND: + 'Could not load the default credentials. Browse to https://cloud.google.com/docs/authentication/getting-started for more information.', NO_UNIVERSE_DOMAIN_FOUND: 'Unable to detect a Universe Domain in the current environment.\n' + 'To learn more about Universe Domain retrieval, visit: \n' + @@ -174,6 +184,7 @@ export class GoogleAuth { // To save the contents of the JSON credential file jsonContent: JWTInput | ExternalAccountClientOptions | null = null; + apiKey: string | null; cachedCredential: JSONClient | Impersonated | Compute | T | null = null; /** @@ -208,8 +219,16 @@ export class GoogleAuth { this.cachedCredential = opts.authClient || null; this.keyFilename = opts.keyFilename || opts.keyFile; this.scopes = opts.scopes; - this.jsonContent = opts.credentials || null; this.clientOptions = opts.clientOptions || {}; + this.jsonContent = opts.credentials || null; + this.apiKey = opts.apiKey || this.clientOptions.apiKey || null; + + // Cannot use both API Key + Credentials + if (this.apiKey && (this.jsonContent || this.clientOptions.credentials)) { + throw new RangeError( + GoogleAuthExceptionMessages.API_KEY_WITH_CREDENTIALS + ); + } if (opts.universeDomain) { this.clientOptions.universeDomain = opts.universeDomain; @@ -401,13 +420,10 @@ export class GoogleAuth { // This will also preserve one's configured quota project, in case they // set one directly on the credential previously. if (this.cachedCredential) { - return await this.prepareAndCacheADC(this.cachedCredential); + // cache, while preserving existing quota project preferences + return await this.#prepareAndCacheClient(this.cachedCredential, null); } - // Since this is a 'new' ADC to cache we will use the environment variable - // if it's available. We prefer this value over the value from ADC. - const quotaProjectIdOverride = process.env['GOOGLE_CLOUD_QUOTA_PROJECT']; - let credential: JSONClient | null; // Check for the existence of a local environment variable pointing to the // location of the credential file. This is typically used in local @@ -421,7 +437,7 @@ export class GoogleAuth { credential.scopes = this.getAnyScopes(); } - return await this.prepareAndCacheADC(credential, quotaProjectIdOverride); + return await this.#prepareAndCacheClient(credential); } // Look in the well-known credential file location. @@ -433,7 +449,7 @@ export class GoogleAuth { } else if (credential instanceof BaseExternalAccountClient) { credential.scopes = this.getAnyScopes(); } - return await this.prepareAndCacheADC(credential, quotaProjectIdOverride); + return await this.#prepareAndCacheClient(credential); } // Determine if we're running on GCE. @@ -445,27 +461,15 @@ export class GoogleAuth { } (options as ComputeOptions).scopes = this.getAnyScopes(); - return await this.prepareAndCacheADC( - new Compute(options), - quotaProjectIdOverride - ); + return await this.#prepareAndCacheClient(new Compute(options)); } - // No ADC, but perhaps there's an API key available... - if ('apiKey' in options && options.apiKey) { - const client = await this.fromAPIKey(options.apiKey, options); - client.scopes = this.scopes; - return await this.prepareAndCacheADC(client, quotaProjectIdOverride); - } - - throw new Error( - 'Could not load the default credentials. Browse to https://cloud.google.com/docs/authentication/getting-started for more information.' - ); + throw new Error(GoogleAuthExceptionMessages.NO_ADC_FOUND); } - private async prepareAndCacheADC( + async #prepareAndCacheClient( credential: JSONClient | Impersonated | Compute | T, - quotaProjectIdOverride?: string + quotaProjectIdOverride = process.env['GOOGLE_CLOUD_QUOTA_PROJECT'] || null ): Promise { const projectId = await this.getProjectIdOptional(); @@ -816,11 +820,8 @@ export class GoogleAuth { * @param options An optional options object. * @returns A JWT loaded from the key */ - fromAPIKey(apiKey: string, options?: AuthClientOptions): JWT { - options = options || {}; - const client = new JWT(options); - client.fromAPIKey(apiKey); - return client; + fromAPIKey(apiKey: string, options: AuthClientOptions = {}): JWT { + return new JWT({...options, apiKey}); } /** @@ -1003,18 +1004,25 @@ export class GoogleAuth { * Default Credentials. */ async getClient() { - if (!this.cachedCredential) { - if (this.jsonContent) { - this._cacheClientFromJSON(this.jsonContent, this.clientOptions); - } else if (this.keyFilename) { - const filePath = path.resolve(this.keyFilename); - const stream = fs.createReadStream(filePath); - await this.fromStreamAsync(stream, this.clientOptions); - } else { - await this.getApplicationDefaultAsync(this.clientOptions); - } + if (this.cachedCredential) { + return this.cachedCredential; + } else if (this.jsonContent) { + return this._cacheClientFromJSON(this.jsonContent, this.clientOptions); + } else if (this.keyFilename) { + const filePath = path.resolve(this.keyFilename); + const stream = fs.createReadStream(filePath); + return await this.fromStreamAsync(stream, this.clientOptions); + } else if (this.apiKey) { + const client = await this.fromAPIKey(this.apiKey, this.clientOptions); + client.scopes = this.scopes; + const {credential} = await this.#prepareAndCacheClient(client); + return credential; + } else { + const {credential} = await this.getApplicationDefaultAsync( + this.clientOptions + ); + return credential; } - return this.cachedCredential!; } /** From 81a10b9903d16287dac0c7fa5adeab467a308a86 Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Fri, 2 Aug 2024 22:28:03 +0000 Subject: [PATCH 07/21] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20?= =?UTF-8?q?post-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- README.md | 341 ++++++++++++++++++++++++------------------------------ 1 file changed, 153 insertions(+), 188 deletions(-) diff --git a/README.md b/README.md index 763b1c1c..f166b09c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,5 @@ -[//]: # 'This README.md file is auto-generated, all changes to this file will be lost.' -[//]: # 'To regenerate it, use `python -m synthtool`.' - +[//]: # "This README.md file is auto-generated, all changes to this file will be lost." +[//]: # "To regenerate it, use `python -m synthtool`." Google Cloud Platform logo # [Google Auth Library: Node.js Client](https://github.com/googleapis/google-auth-library-nodejs) @@ -8,14 +7,18 @@ [![release level](https://img.shields.io/badge/release%20level-stable-brightgreen.svg?style=flat)](https://cloud.google.com/terms/launch-stages) [![npm version](https://img.shields.io/npm/v/google-auth-library.svg)](https://www.npmjs.org/package/google-auth-library) + + + This is Google's officially supported [node.js](http://nodejs.org/) client library for using OAuth 2.0 authorization and authentication with Google APIs. + A comprehensive list of changes in each version may be found in [the CHANGELOG](https://github.com/googleapis/google-auth-library-nodejs/blob/main/CHANGELOG.md). -- [Google Auth Library Node.js Client API Reference][client-docs] -- [Google Auth Library Documentation][product-docs] -- [github.com/googleapis/google-auth-library-nodejs](https://github.com/googleapis/google-auth-library-nodejs) +* [Google Auth Library Node.js Client API Reference][client-docs] +* [Google Auth Library Documentation][product-docs] +* [github.com/googleapis/google-auth-library-nodejs](https://github.com/googleapis/google-auth-library-nodejs) Read more about the client libraries for Cloud APIs, including the older Google APIs Client Libraries, in [Client Libraries Explained][explained]. @@ -24,14 +27,15 @@ Google APIs Client Libraries, in [Client Libraries Explained][explained]. **Table of contents:** -- [Quickstart](#quickstart) - - [Installing the client library](#installing-the-client-library) +* [Quickstart](#quickstart) + + * [Installing the client library](#installing-the-client-library) -- [Samples](#samples) -- [Versioning](#versioning) -- [Contributing](#contributing) -- [License](#license) +* [Samples](#samples) +* [Versioning](#versioning) +* [Contributing](#contributing) +* [License](#license) ## Quickstart @@ -42,9 +46,7 @@ npm install google-auth-library ``` ## Ways to authenticate - This library provides a variety of ways to authenticate to your Google services. - - [Application Default Credentials](#choosing-the-correct-credential-type-automatically) - Use Application Default Credentials when you use a single identity for all users in your application. Especially useful for applications running on Google Cloud. Application Default Credentials also support workload identity federation to access Google Cloud resources from non-Google Cloud platforms. - [OAuth 2](#oauth2) - Use OAuth2 when you need to perform actions on behalf of the end user. - [JSON Web Tokens](#json-web-tokens) - Use JWT when you are using a single identity for all users. Especially useful for server->server or server->API communication. @@ -55,7 +57,6 @@ This library provides a variety of ways to authenticate to your Google services. - [Downscoped Client](#downscoped-client) - Use Downscoped Client with Credential Access Boundary to generate a short-lived credential with downscoped, restricted IAM permissions that can use for Cloud Storage. ## Application Default Credentials - This library provides an implementation of [Application Default Credentials](https://cloud.google.com/docs/authentication/getting-started) for Node.js. The [Application Default Credentials](https://cloud.google.com/docs/authentication/getting-started) provide a simple way to get authorization credentials for use in calling Google APIs. They are best suited for cases when the call needs to have the same identity and authorization level for the application independent of the user. This is the recommended approach to authorize calls to Cloud APIs, particularly when you're building an application that uses Google Cloud Platform. @@ -66,7 +67,7 @@ Application Default Credentials also support workload identity federation to acc To use Application Default Credentials, You first need to download a set of JSON credentials for your project. Go to **APIs & Auth** > **Credentials** in the [Google Developers Console](https://console.cloud.google.com/) and select **Service account** from the **Add credentials** dropdown. -> This file is your _only copy_ of these credentials. It should never be +> This file is your *only copy* of these credentials. It should never be > committed with your source code, and should be stored securely. Once downloaded, store the path to this file in the `GOOGLE_APPLICATION_CREDENTIALS` environment variable. @@ -75,6 +76,7 @@ Once downloaded, store the path to this file in the `GOOGLE_APPLICATION_CREDENTI Before making your API call, you must be sure the API you're calling has been enabled. Go to **APIs & Auth** > **APIs** in the [Google Developers Console](https://console.cloud.google.com/) and enable the APIs you'd like to call. For the example below, you must enable the `DNS API`. + #### Choosing the correct credential type automatically Rather than manually creating an OAuth2 client, JWT client, or Compute client, the auth library can create the correct credential type for you, depending upon the environment your code is running under. @@ -87,17 +89,17 @@ The code below shows how to retrieve a default credential type, depending upon t const {GoogleAuth} = require('google-auth-library'); /** - * Instead of specifying the type of client you'd like to use (JWT, OAuth2, etc) - * this library will automatically choose the right client based on the environment. - */ +* Instead of specifying the type of client you'd like to use (JWT, OAuth2, etc) +* this library will automatically choose the right client based on the environment. +*/ async function main() { const auth = new GoogleAuth({ - scopes: 'https://www.googleapis.com/auth/cloud-platform', + scopes: 'https://www.googleapis.com/auth/cloud-platform' }); const client = await auth.getClient(); const projectId = await auth.getProjectId(); const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`; - const res = await client.request({url}); + const res = await client.request({ url }); console.log(res.data); } @@ -116,7 +118,7 @@ For more information about OAuth2 and how it works, [see here](https://developer Let's take a look at a complete example. -```js +``` js const {OAuth2Client} = require('google-auth-library'); const http = require('http'); const url = require('url'); @@ -127,8 +129,8 @@ const destroyer = require('server-destroy'); const keys = require('./oauth2.keys.json'); /** - * Start by acquiring a pre-authenticated oAuth2 client. - */ +* Start by acquiring a pre-authenticated oAuth2 client. +*/ async function main() { const oAuth2Client = await getAuthenticatedClient(); // Make a simple request to the People API using our pre-authenticated client. The `request()` method @@ -146,9 +148,9 @@ async function main() { } /** - * Create a new OAuth2Client, and go through the OAuth2 content - * workflow. Return the full client to the callback. - */ +* Create a new OAuth2Client, and go through the OAuth2 content +* workflow. Return the full client to the callback. +*/ function getAuthenticatedClient() { return new Promise((resolve, reject) => { // create an oAuth client to authorize the API call. Secrets are kept in a `keys.json` file, @@ -203,12 +205,12 @@ main().catch(console.error); #### Handling token events -This library will automatically obtain an `access_token`, and automatically refresh the `access_token` if a `refresh_token` is present. The `refresh_token` is only returned on the [first authorization](https://github.com/googleapis/google-api-nodejs-client/issues/750#issuecomment-304521450), so if you want to make sure you store it safely. An easy way to make sure you always store the most recent tokens is to use the `tokens` event: +This library will automatically obtain an `access_token`, and automatically refresh the `access_token` if a `refresh_token` is present. The `refresh_token` is only returned on the [first authorization](https://github.com/googleapis/google-api-nodejs-client/issues/750#issuecomment-304521450), so if you want to make sure you store it safely. An easy way to make sure you always store the most recent tokens is to use the `tokens` event: ```js const client = await auth.getClient(); -client.on('tokens', tokens => { +client.on('tokens', (tokens) => { if (tokens.refresh_token) { // store the refresh_token in my database! console.log(tokens.refresh_token); @@ -217,23 +219,21 @@ client.on('tokens', tokens => { }); const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`; -const res = await client.request({url}); +const res = await client.request({ url }); // The `tokens` event would now be raised if this was the first request ``` #### Retrieve access token - With the code returned, you can ask for an access token as shown below: -```js +``` js const tokens = await oauth2Client.getToken(code); // Now tokens contains an access_token and an optional refresh_token. Save them. oauth2Client.setCredentials(tokens); ``` #### Obtaining a new Refresh Token - -If you need to obtain a new `refresh_token`, ensure the call to `generateAuthUrl` sets the `access_type` to `offline`. The refresh token will only be returned for the first authorization by the user. To force consent, set the `prompt` property to `consent`: +If you need to obtain a new `refresh_token`, ensure the call to `generateAuthUrl` sets the `access_type` to `offline`. The refresh token will only be returned for the first authorization by the user. To force consent, set the `prompt` property to `consent`: ```js // Generate the url that will be used for the consent dialog. @@ -246,14 +246,13 @@ const authorizeUrl = oAuth2Client.generateAuthUrl({ // consents to providing access. For illustration purposes, // setting the prompt to 'consent' will force this consent // every time, forcing a refresh_token to be returned. - prompt: 'consent', + prompt: 'consent' }); ``` #### Checking `access_token` information - After obtaining and storing an `access_token`, at a later time you may want to go check the expiration date, -original scopes, or audience for the token. To get the token info, you can use the `getTokenInfo` method: +original scopes, or audience for the token. To get the token info, you can use the `getTokenInfo` method: ```js // after acquiring an oAuth2Client... @@ -268,30 +267,29 @@ This method will throw if the token is invalid. #### Using an API Key An API key can be provided to the constructor: - ```js const client = new OAuth2Client({ - apiKey: 'my-api-key', + apiKey: 'my-api-key' }); ``` Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. Additionally, an API key can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: - ```js const auth = new GoogleAuth({ clientOptions: { - apiKey: 'my-api-key', - }, -}); + apiKey: 'my-api-key' + } +}) ``` -## JSON Web Tokens +Availability varies by API. +## JSON Web Tokens The Google Developers Console provides a `.json` file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account. -```js +``` js const {JWT} = require('google-auth-library'); const keys = require('./jwt.keys.json'); @@ -312,8 +310,7 @@ main().catch(console.error); The parameters for the JWT auth client including how to use it with a `.pem` file are explained in [samples/jwt.js](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js). #### Loading credentials from environment variables - -Instead of loading credentials from a key file, you can also provide them using an environment variable and the `GoogleAuth.fromJSON()` method. This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc). +Instead of loading credentials from a key file, you can also provide them using an environment variable and the `GoogleAuth.fromJSON()` method. This is particularly convenient for systems that deploy directly from source control (Heroku, App Engine, etc). Start by exporting your credentials: @@ -331,7 +328,6 @@ $ export CREDS='{ "client_x509_cert_url": "your-cert-url" }' ``` - Now you can create a new client from the credentials: ```js @@ -357,22 +353,20 @@ main().catch(console.error); ``` #### Using a Proxy - You can set the `HTTPS_PROXY` or `https_proxy` environment variables to proxy HTTPS requests. When `HTTPS_PROXY` or `https_proxy` are set, they will be used to proxy SSL requests that do not have an explicit proxy configuration option present. ## Compute - If your application is running on Google Cloud Platform, you can authenticate using the default service account or by specifying a specific service account. -**Note**: In most cases, you will want to use [Application Default Credentials](#choosing-the-correct-credential-type-automatically). Direct use of the `Compute` class is for very specific scenarios. +**Note**: In most cases, you will want to use [Application Default Credentials](#choosing-the-correct-credential-type-automatically). Direct use of the `Compute` class is for very specific scenarios. -```js +``` js const {auth, Compute} = require('google-auth-library'); async function main() { const client = new Compute({ // Specifying the service account email is optional. - serviceAccountEmail: 'my-service-account@example.com', + serviceAccountEmail: 'my-service-account@example.com' }); const projectId = await auth.getProjectId(); const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`; @@ -393,7 +387,6 @@ This lets you access Google Cloud resources directly, eliminating the maintenanc ### Accessing resources from AWS In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed: - - A workload identity pool needs to be created. - AWS needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS). - Permission to impersonate a service account needs to be granted to the external identity. @@ -416,7 +409,6 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: - - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$AWS_PROVIDER_ID`: The AWS provider ID. @@ -433,7 +425,6 @@ You can now [start using the Auth library](#using-external-identities) to call G ### Accessing resources from AWS using a custom AWS security credentials supplier. In order to access Google Cloud resources from Amazon Web Services (AWS), the following requirements are needed: - - A workload identity pool needs to be created. - AWS needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from AWS). - Permission to impersonate a service account needs to be granted to the external identity. @@ -461,11 +452,10 @@ class AwsSupplier implements AwsSecurityCredentialsSupplier { } const clientOptions = { - audience: - '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. + audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. subject_token_type: 'urn:ietf:params:aws:token-type:aws4_request', // Set the subject token type. - aws_security_credentials_supplier: new AwsSupplier(), // Set the custom supplier. -}; + aws_security_credentials_supplier: new AwsSupplier() // Set the custom supplier. +} const client = new AwsClient(clientOptions); ``` @@ -474,16 +464,16 @@ Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using- Where the following variables need to be substituted: -- `$PROJECT_NUMBER`: The Google Cloud project number. -- `$WORKLOAD_POOL_ID`: The workload pool ID. -- `$PROVIDER_ID`: The provider ID. +* `$PROJECT_NUMBER`: The Google Cloud project number. +* `$WORKLOAD_POOL_ID`: The workload pool ID. +* `$PROVIDER_ID`: The provider ID. + The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config). ### Access resources from Microsoft Azure In order to access Google Cloud resources from Microsoft Azure, the following requirements are needed: - - A workload identity pool needs to be created. - Azure needs to be added as an identity provider in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from Azure). - The Azure tenant needs to be configured for identity federation. @@ -507,7 +497,6 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: - - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$AZURE_PROVIDER_ID`: The Azure provider ID. @@ -520,7 +509,6 @@ You can now [start using the Auth library](#using-external-identities) to call G ### Accessing resources from an OIDC identity provider In order to access Google Cloud resources from an identity provider that supports [OpenID Connect (OIDC)](https://openid.net/connect/), the following requirements are needed: - - A workload identity pool needs to be created. - An OIDC identity provider needs to be added in the workload identity pool (The Google [organization policy](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers#restrict) needs to allow federation from the identity provider). - Permission to impersonate a service account needs to be granted to the external identity. @@ -554,7 +542,6 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: - - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$OIDC_PROVIDER_ID`: The OIDC provider ID. @@ -585,7 +572,6 @@ gcloud iam workload-identity-pools create-cred-config \ ``` Where the following variables need to be substituted: - - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$OIDC_PROVIDER_ID`: The OIDC provider ID. @@ -613,11 +599,10 @@ class CustomSupplier implements SubjectTokenSupplier { } const clientOptions = { - audience: - '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. + audience: '//iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type. - subject_token_supplier: new CustomSupplier(), // Set the custom supplier. -}; + subject_token_supplier: new CustomSupplier() // Set the custom supplier. +} const client = new CustomSupplier(clientOptions); ``` @@ -626,9 +611,9 @@ Where the [audience](https://cloud.google.com/iam/docs/best-practices-for-using- Where the following variables need to be substituted: -- `$PROJECT_NUMBER`: The Google Cloud project number. -- `$WORKLOAD_POOL_ID`: The workload pool ID. -- `$PROVIDER_ID`: The provider ID. +* `$PROJECT_NUMBER`: The Google Cloud project number. +* `$WORKLOAD_POOL_ID`: The workload pool ID. +* `$PROVIDER_ID`: The provider ID. The values for audience, service account impersonation URL, and any other builder field can also be found by generating a [credential configuration file with the gcloud CLI](https://cloud.google.com/sdk/gcloud/reference/iam/workload-identity-pools/create-cred-config). @@ -644,9 +629,8 @@ gcloud auth application-default login --login-config=$LOGIN_CONFIG ``` Where the following variable needs to be substituted: - - `$LOGIN_CONFIG`: The login config file generated with the cloud console or - [gcloud iam workforce-pools create-login-config](https://cloud.google.com/sdk/gcloud/reference/iam/workforce-pools/create-login-config) + [gcloud iam workforce-pools create-login-config](https://cloud.google.com/sdk/gcloud/reference/iam/workforce-pools/create-login-config) This will open a browser flow for you to sign in via the configured third party identity provider and then will store the external account authorized user configuration at the well known ADC location. @@ -684,9 +668,7 @@ gcloud iam workload-identity-pools create-cred-config \ # --executable-output-file=$EXECUTABLE_OUTPUT_FILE \ --output-file /path/to/generated/config.json ``` - Where the following variables need to be substituted: - - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$PROVIDER_ID`: The OIDC or SAML provider ID. @@ -714,7 +696,6 @@ using the command specified. The executable's output must adhere to the response specified below. It must output the response to stdout. A sample successful executable OIDC response: - ```json { "version": 1, @@ -726,7 +707,6 @@ A sample successful executable OIDC response: ``` A sample successful executable SAML response: - ```json { "version": 1, @@ -736,12 +716,10 @@ A sample successful executable SAML response: "expiration_time": 1620499962 } ``` - For successful responses, the `expiration_time` field is only required when an output file is specified in the credential configuration. A sample executable error response: - ```json { "version": 1, @@ -750,47 +728,41 @@ A sample executable error response: "message": "Caller not authorized." } ``` - These are all required fields for an error response. The code and message fields will be used by the library as part of the thrown exception. Response format fields summary: - -- `version`: The version of the JSON output. Currently, only version 1 is supported. -- `success`: The status of the response. When true, the response must contain the 3rd party token - and token type. The response must also contain the expiration time if an output file was specified in the credential configuration. - The executable must also exit with exit code 0. - When false, the response must contain the error code and message fields and exit with a non-zero value. -- `token_type`: The 3rd party subject token type. Must be _urn:ietf:params:oauth:token-type:jwt_, - _urn:ietf:params:oauth:token-type:id_token_, or _urn:ietf:params:oauth:token-type:saml2_. -- `id_token`: The 3rd party OIDC token. -- `saml_response`: The 3rd party SAML response. -- `expiration_time`: The 3rd party subject token expiration time in seconds (unix epoch time). -- `code`: The error code string. -- `message`: The error message. +* `version`: The version of the JSON output. Currently, only version 1 is supported. +* `success`: The status of the response. When true, the response must contain the 3rd party token + and token type. The response must also contain the expiration time if an output file was specified in the credential configuration. + The executable must also exit with exit code 0. + When false, the response must contain the error code and message fields and exit with a non-zero value. +* `token_type`: The 3rd party subject token type. Must be *urn:ietf:params:oauth:token-type:jwt*, +*urn:ietf:params:oauth:token-type:id_token*, or *urn:ietf:params:oauth:token-type:saml2*. +* `id_token`: The 3rd party OIDC token. +* `saml_response`: The 3rd party SAML response. +* `expiration_time`: The 3rd party subject token expiration time in seconds (unix epoch time). +* `code`: The error code string. +* `message`: The error message. All response types must include both the `version` and `success` fields. - -- Successful responses must include the `token_type` and one of - `id_token` or `saml_response`. The `expiration_time` field must also be present if an output file was specified in - the credential configuration. -- Error responses must include both the `code` and `message` fields. +* Successful responses must include the `token_type` and one of +`id_token` or `saml_response`. The `expiration_time` field must also be present if an output file was specified in +the credential configuration. +* Error responses must include both the `code` and `message` fields. The library will populate the following environment variables when the executable is run: - -- `GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE`: The audience field from the credential configuration. Always present. -- `GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL`: The service account email. Only present when service account impersonation is used. -- `GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE`: The output file location from the credential configuration. Only present when specified in the credential configuration. -- `GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE`: This expected subject token type. Always present. +* `GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE`: The audience field from the credential configuration. Always present. +* `GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL`: The service account email. Only present when service account impersonation is used. +* `GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE`: The output file location from the credential configuration. Only present when specified in the credential configuration. +* `GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE`: This expected subject token type. Always present. These environment variables can be used by the executable to avoid hard-coding these values. ##### Security considerations - The following security practices are highly recommended: - -- Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. -- The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. +* Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. +* The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. Given the complexity of using executable-sourced credentials, it is recommended to use the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party @@ -800,7 +772,6 @@ You can now [use the Auth library](#using-external-identities) to call Google Cl resources from an OIDC or SAML provider. #### Configurable Token Lifetime - When creating a credential configuration with workload identity federation using service account impersonation, you can provide an optional argument to configure the service account access token lifetime. To generate the configuration with configurable token lifetime, run the following command (this example uses an AWS configuration, but the token lifetime can be configured for all workload identity federation providers): @@ -815,8 +786,7 @@ gcloud iam workload-identity-pools create-cred-config \ --service-account-token-lifetime-seconds $TOKEN_LIFETIME ``` -Where the following variables need to be substituted: - + Where the following variables need to be substituted: - `$PROJECT_NUMBER`: The Google Cloud project number. - `$POOL_ID`: The workload identity pool ID. - `$AWS_PROVIDER_ID`: The AWS provider ID. @@ -844,7 +814,6 @@ Active Directory Federation Services (AD FS), Okta, and others. In order to access Google Cloud resources from an identity provider that supports [OpenID Connect (OIDC)](https://openid.net/connect/), the following requirements are needed: - - A workforce identity pool needs to be created. - An OIDC or SAML 2.0 identity provider needs to be added in the workforce pool. @@ -882,9 +851,7 @@ gcloud iam workforce-pools create-cred-config \ # --credential-source-field-name "id_token" \ --output-file=/path/to/generated/config.json ``` - Where the following variables need to be substituted: - - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$PATH_TO_OIDC_ID_TOKEN`: The file path used to retrieve the OIDC token. @@ -903,7 +870,6 @@ gcloud iam workforce-pools create-cred-config \ ``` Where the following variables need to be substituted: - - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$PATH_TO_SAML_ASSERTION`: The file path used to retrieve the base64-encoded SAML assertion. @@ -930,12 +896,11 @@ gcloud iam workforce-pools create-cred-config \ ``` Where the following variables need to be substituted: - - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$URL_TO_RETURN_OIDC_ID_TOKEN`: The URL of the local server endpoint. - `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to - `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`. + `$URL_TO_GET_OIDC_TOKEN`, e.g. `Metadata-Flavor=Google`. - `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project). To generate a URL-sourced SAML configuration, run the following command: @@ -954,12 +919,11 @@ gcloud iam workforce-pools create-cred-config \ These commands generate the configuration file in the specified output file. Where the following variables need to be substituted: - - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$URL_TO_GET_SAML_ASSERTION`: The URL of the local server endpoint. - `$HEADER_KEY` and `$HEADER_VALUE`: The additional header key/value pairs to pass along the GET request to - `$URL_TO_GET_SAML_ASSERTION`, e.g. `Metadata-Flavor=Google`. + `$URL_TO_GET_SAML_ASSERTION`, e.g. `Metadata-Flavor=Google`. - `$WORKFORCE_POOL_USER_PROJECT`: The project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project). ### Using Executable-sourced workforce credentials with OIDC and SAML @@ -990,9 +954,7 @@ gcloud iam workforce-pools create-cred-config \ --workforce-pool-user-project=$WORKFORCE_POOL_USER_PROJECT \ --output-file /path/to/generated/config.json ``` - Where the following variables need to be substituted: - - `$WORKFORCE_POOL_ID`: The workforce pool ID. - `$PROVIDER_ID`: The provider ID. - `$SUBJECT_TOKEN_TYPE`: The subject token type. @@ -1022,11 +984,9 @@ Refer to the [using executable-sourced credentials with Workload Identity Federa above for the executable response specification. ##### Security considerations - The following security practices are highly recommended: - -- Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. -- The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. +* Access to the script should be restricted as it will be displaying credentials to stdout. This ensures that rogue processes do not gain access to the script. +* The configuration file should not be modifiable. Write access should be restricted to avoid processes modifying the executable command portion. Given the complexity of using executable-sourced credentials, it is recommended to use the existing supported mechanisms (file-sourced/URL-sourced) for providing 3rd party @@ -1055,11 +1015,10 @@ class CustomSupplier implements SubjectTokenSupplier { } const clientOptions = { - audience: - '//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. + audience: '//iam.googleapis.com/locations/global/workforcePools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID', // Set the GCP audience. subject_token_type: 'urn:ietf:params:oauth:token-type:id_token', // Set the subject token type. - subject_token_supplier: new CustomSupplier(), // Set the custom supplier. -}; + subject_token_supplier: new CustomSupplier() // Set the custom supplier. +} const client = new CustomSupplier(clientOptions); ``` @@ -1068,8 +1027,8 @@ Where the audience is: `//iam.googleapis.com/locations/global/workforcePools/$WO Where the following variables need to be substituted: -- `WORKFORCE_POOL_ID`: The worforce pool ID. -- `$PROVIDER_ID`: The provider ID. +* `WORKFORCE_POOL_ID`: The worforce pool ID. +* `$PROVIDER_ID`: The provider ID. and the workforce pool user project is the project number associated with the [workforce pools user project](https://cloud.google.com/iam/docs/workforce-identity-federation#workforce-pools-user-project). @@ -1090,13 +1049,13 @@ The library can now automatically choose the right type of client and initialize ```js async function main() { const auth = new GoogleAuth({ - scopes: 'https://www.googleapis.com/auth/cloud-platform', + scopes: 'https://www.googleapis.com/auth/cloud-platform' }); const client = await auth.getClient(); const projectId = await auth.getProjectId(); // List all buckets in a project. const url = `https://storage.googleapis.com/storage/v1/b?project=${projectId}`; - const res = await client.request({url}); + const res = await client.request({ url }); console.log(res.data); } ``` @@ -1132,13 +1091,10 @@ async function main() { ``` #### Security Considerations - Note that this library does not perform any validation on the token_url, token_info_url, or service_account_impersonation_url fields of the credential configuration. It is not recommended to use a credential configuration that you did not generate with the gcloud CLI unless you verify that the URL fields point to a googleapis.com domain. ## Working with ID Tokens - ### Fetching ID Tokens - If your application is running on Cloud Run or Cloud Functions, or using Cloud Identity-Aware Proxy (IAP), you will need to fetch an ID token to access your application. For this, use the method `getIdTokenClient` on the `GoogleAuth` client. @@ -1151,7 +1107,7 @@ For invoking Cloud Functions, your service account will need the [`Function Invoker`](https://cloud.google.com/functions/docs/securing/authenticating#function-to-function) IAM permission. -```js +``` js // Make a request to a protected Cloud Run service. const {GoogleAuth} = require('google-auth-library'); @@ -1171,7 +1127,7 @@ A complete example can be found in [`samples/idtokens-serverless.js`](https://gi For invoking Cloud Identity-Aware Proxy, you will need to pass the Client ID used when you set up your protected resource as the target audience. -```js +``` js // Make a request to a protected Cloud Identity-Aware Proxy (IAP) resource const {GoogleAuth} = require('google-auth-library'); @@ -1211,7 +1167,7 @@ const ticket = await oAuth2Client.verifySignedJwtWithCertsAsync( ); // Print out the info contained in the IAP ID token -console.log(ticket); +console.log(ticket) ``` A complete example can be found in [`samples/verifyIdToken-iap.js`](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken-iap.js). @@ -1233,10 +1189,11 @@ set of scopes. ### Sample Usage ```javascript -const {GoogleAuth, Impersonated} = require('google-auth-library'); -const {SecretManagerServiceClient} = require('@google-cloud/secret-manager'); +const { GoogleAuth, Impersonated } = require('google-auth-library'); +const { SecretManagerServiceClient } = require('@google-cloud/secret-manager'); async function main() { + // Acquire source credentials: const auth = new GoogleAuth(); const client = await auth.getClient(); @@ -1247,7 +1204,7 @@ async function main() { targetPrincipal: 'impersonated-account@projectID.iam.gserviceaccount.com', lifetime: 30, delegates: [], - targetScopes: ['https://www.googleapis.com/auth/cloud-platform'], + targetScopes: ['https://www.googleapis.com/auth/cloud-platform'] }); // Get impersonated credentials: @@ -1255,9 +1212,8 @@ async function main() { // Do something with `authHeaders.Authorization`. // Use impersonated credentials: - const url = - 'https://www.googleapis.com/storage/v1/b?project=anotherProjectID'; - const resp = await targetClient.request({url}); + const url = 'https://www.googleapis.com/storage/v1/b?project=anotherProjectID' + const resp = await targetClient.request({ url }); for (const bucket of resp.data.items) { console.log(bucket.name); } @@ -1272,15 +1228,14 @@ async function main() { getClient: () => targetClient, }, }); - const secretName = - 'projects/anotherProjectNumber/secrets/someProjectName/versions/1'; + const secretName = 'projects/anotherProjectNumber/secrets/someProjectName/versions/1'; const [accessResponse] = await smClient.accessSecretVersion({ name: secretName, }); const responsePayload = accessResponse.payload.data.toString('utf8'); // Do something with the secret contained in `responsePayload`. -} +}; main(); ``` @@ -1295,13 +1250,12 @@ The `DownscopedClient` class can be used to produce a downscoped access token fr > Notice: Only Cloud Storage supports Credential Access Boundaries for now. ### Sample Usage - There are two entities needed to generate and use credentials generated from Downscoped Client with Credential Access Boundaries. - Token broker: This is the entity with elevated permissions. This entity has the permissions needed to generate downscoped tokens. The common pattern of usage is to have a token broker with elevated access generate these downscoped credentials from higher access source credentials and pass the downscoped short-lived access tokens to a token consumer via some secure authenticated channel for limited access to Google Cloud Storage resources. -```js +``` js const {GoogleAuth, DownscopedClient} = require('google-auth-library'); // Define CAB rules which will restrict the downscoped token to have readonly // access to objects starting with "customer-a" in bucket "bucket_name". @@ -1314,8 +1268,8 @@ const cabRules = { availabilityCondition: { expression: `resource.name.startsWith('projects/_/buckets/` + - `bucket_name/objects/customer-a)`, - }, + `bucket_name/objects/customer-a)` + } }, ], }, @@ -1323,7 +1277,7 @@ const cabRules = { // This will use ADC to get the credentials used for the downscoped client. const googleAuth = new GoogleAuth({ - scopes: ['https://www.googleapis.com/auth/cloud-platform'], + scopes: ['https://www.googleapis.com/auth/cloud-platform'] }); // Obtain an authenticated client via ADC. @@ -1347,7 +1301,7 @@ The broker will instantiate downscoped credentials instances that can be used to - Token consumer: This is the consumer of the downscoped tokens. This entity does not have the direct ability to generate access tokens and instead relies on the token broker to provide it with downscoped tokens to run operations on GCS buckets. It is assumed that the downscoped token consumer may have its own mechanism to authenticate itself with the token broker. -```js +``` js const {OAuth2Client} = require('google-auth-library'); const {Storage} = require('@google-cloud/storage'); @@ -1366,7 +1320,7 @@ oauth2Client.refreshHandler = async () => { return { access_token: refreshedAccessToken.token, expiry_date: refreshedAccessToken.expirationTime, - }; + } }; // Use the consumer client to define storageOptions and create a GCS object. @@ -1378,42 +1332,45 @@ const storageOptions = { const storage = new Storage(storageOptions); const downloadFile = await storage - .bucket('bucket_name') - .file('customer-a-data.txt') - .download(); + .bucket('bucket_name') + .file('customer-a-data.txt') + .download(); console.log(downloadFile.toString('utf8')); main().catch(console.error); ``` + ## Samples Samples are in the [`samples/`](https://github.com/googleapis/google-auth-library-nodejs/tree/main/samples) directory. Each sample's `README.md` has instructions for running its sample. -| Sample | Source Code | Try it | -| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/adc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/adc.js,samples/README.md) | -| Authenticate Explicit | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateExplicit.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateExplicit.js,samples/README.md) | -| Authenticate Implicit With Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateImplicitWithAdc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateImplicitWithAdc.js,samples/README.md) | -| Compute | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/compute.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/compute.js,samples/README.md) | -| Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/credentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/credentials.js,samples/README.md) | -| Downscopedclient | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/downscopedclient.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/downscopedclient.js,samples/README.md) | -| Headers | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/headers.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/headers.js,samples/README.md) | -| Id Token From Impersonated Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromImpersonatedCredentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromImpersonatedCredentials.js,samples/README.md) | -| Id Token From Metadata Server | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromMetadataServer.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromMetadataServer.js,samples/README.md) | -| Id Token From Service Account | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromServiceAccount.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromServiceAccount.js,samples/README.md) | -| ID Tokens for Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-iap.js,samples/README.md) | -| ID Tokens for Serverless | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-serverless.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-serverless.js,samples/README.md) | -| Jwt | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/jwt.js,samples/README.md) | -| Keepalive | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keepalive.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keepalive.js,samples/README.md) | -| Keyfile | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keyfile.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keyfile.js,samples/README.md) | -| Oauth2-code Verifier | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2-codeVerifier.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2-codeVerifier.js,samples/README.md) | -| Oauth2 | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2.js,samples/README.md) | -| Sign Blob | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlob.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlob.js,samples/README.md) | -| Sign Blob Impersonated | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlobImpersonated.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlobImpersonated.js,samples/README.md) | -| Verify Google Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyGoogleIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyGoogleIdToken.js,samples/README.md) | -| Verifying ID Tokens from Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken-iap.js,samples/README.md) | -| Verify Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken.js,samples/README.md) | +| Sample | Source Code | Try it | +| --------------------------- | --------------------------------- | ------ | +| Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/adc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/adc.js,samples/README.md) | +| Authenticate Explicit | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateExplicit.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateExplicit.js,samples/README.md) | +| Authenticate Implicit With Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateImplicitWithAdc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateImplicitWithAdc.js,samples/README.md) | +| Compute | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/compute.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/compute.js,samples/README.md) | +| Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/credentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/credentials.js,samples/README.md) | +| Downscopedclient | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/downscopedclient.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/downscopedclient.js,samples/README.md) | +| Headers | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/headers.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/headers.js,samples/README.md) | +| Id Token From Impersonated Credentials | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromImpersonatedCredentials.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromImpersonatedCredentials.js,samples/README.md) | +| Id Token From Metadata Server | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromMetadataServer.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromMetadataServer.js,samples/README.md) | +| Id Token From Service Account | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idTokenFromServiceAccount.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idTokenFromServiceAccount.js,samples/README.md) | +| ID Tokens for Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-iap.js,samples/README.md) | +| ID Tokens for Serverless | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/idtokens-serverless.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/idtokens-serverless.js,samples/README.md) | +| Jwt | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/jwt.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/jwt.js,samples/README.md) | +| Keepalive | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keepalive.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keepalive.js,samples/README.md) | +| Keyfile | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/keyfile.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/keyfile.js,samples/README.md) | +| Oauth2-code Verifier | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2-codeVerifier.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2-codeVerifier.js,samples/README.md) | +| Oauth2 | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/oauth2.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/oauth2.js,samples/README.md) | +| Sign Blob | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlob.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlob.js,samples/README.md) | +| Sign Blob Impersonated | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/signBlobImpersonated.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/signBlobImpersonated.js,samples/README.md) | +| Verify Google Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyGoogleIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyGoogleIdToken.js,samples/README.md) | +| Verifying ID Tokens from Identity-Aware Proxy (IAP) | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken-iap.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken-iap.js,samples/README.md) | +| Verify Id Token | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/verifyIdToken.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/verifyIdToken.js,samples/README.md) | + + The [Google Auth Library Node.js Client API Reference][client-docs] documentation also contains samples. @@ -1429,9 +1386,9 @@ as soon as possible to an actively supported LTS version. Google's client libraries support legacy versions of Node.js runtimes on a best-efforts basis with the following warnings: -- Legacy versions are not tested in continuous integration. -- Some security patches and features cannot be backported. -- Dependencies cannot be kept up-to-date. +* Legacy versions are not tested in continuous integration. +* Some security patches and features cannot be backported. +* Dependencies cannot be kept up-to-date. Client libraries targeting some end-of-life versions of Node.js are available, and can be installed through npm [dist-tags](https://docs.npmjs.com/cli/dist-tag). @@ -1443,11 +1400,18 @@ for versions compatible with Node.js 8. This library follows [Semantic Versioning](http://semver.org/). + + This library is considered to be **stable**. The code surface will not change in backwards-incompatible ways unless absolutely necessary (e.g. because of critical security issues) or with an extensive deprecation period. Issues and requests against **stable** libraries are addressed with the highest priority. + + + + + More Information: [Google Cloud Platform Launch Stages][launch_stages] [launch_stages]: https://cloud.google.com/terms/launch-stages @@ -1473,4 +1437,5 @@ See [LICENSE](https://github.com/googleapis/google-auth-library-nodejs/blob/main [shell_img]: https://gstatic.com/cloudssh/images/open-btn.png [projects]: https://console.cloud.google.com/project [billing]: https://support.google.com/cloud/answer/6293499#enable-billing + [auth]: https://cloud.google.com/docs/authentication/getting-started From 70b7eb6aa8f8d0bfe735f327995d6eeab9c799e7 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:32:01 -0700 Subject: [PATCH 08/21] fix: type --- src/auth/googleauth.ts | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index 39620e53..cef1b221 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -25,7 +25,7 @@ import {DefaultTransporter, Transporter} from '../transporters'; import {Compute, ComputeOptions} from './computeclient'; import {CredentialBody, ImpersonatedJWTInput, JWTInput} from './credentials'; -import {IdTokenClient} from './idtokenclient'; +import {IdTokenClient, IdTokenProvider} from './idtokenclient'; import {GCPEnv, getEnv} from './envDetect'; import {JWT, JWTOptions} from './jwtclient'; import {Headers, OAuth2ClientOptions} from './oauth2client'; @@ -1037,7 +1037,11 @@ export class GoogleAuth { 'Cannot fetch ID token in this environment, use GCE or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account credentials JSON file.' ); } - return new IdTokenClient({targetAudience, idTokenProvider: client}); + + return new IdTokenClient({ + targetAudience, + idTokenProvider: client as IdTokenProvider, + }); } /** From 65c69a72616b6844d041aae3581f8fbeeebd0760 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:43:25 -0700 Subject: [PATCH 09/21] feat: Export Error Messages --- src/auth/googleauth.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index cef1b221..d31f2833 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -141,7 +141,7 @@ export interface GoogleAuthOptions { export const CLOUD_SDK_CLIENT_ID = '764086051850-6qr4p6gpi6hn506pt8ejuq83di341hur.apps.googleusercontent.com'; -const GoogleAuthExceptionMessages = { +export const GoogleAuthExceptionMessages = { API_KEY_WITH_CREDENTIALS: 'API Keys and Credentials are mutually exclusive authentication methods and cannot be used together.', NO_PROJECT_ID_FOUND: From d4bf04337c2b828f00190c01fb82e54aa74ea8b4 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:43:36 -0700 Subject: [PATCH 10/21] test: Add tests for API Key Support --- test/test.googleauth.ts | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/test/test.googleauth.ts b/test/test.googleauth.ts index 3906bff7..e703e057 100644 --- a/test/test.googleauth.ts +++ b/test/test.googleauth.ts @@ -56,6 +56,7 @@ import {BaseExternalAccountClient} from '../src/auth/baseexternalclient'; import {AuthClient, DEFAULT_UNIVERSE} from '../src/auth/authclient'; import {ExternalAccountAuthorizedUserClient} from '../src/auth/externalAccountAuthorizedUserClient'; import {stringify} from 'querystring'; +import {GoogleAuthExceptionMessages} from '../src/auth/googleauth'; nock.disableNetConnect(); @@ -303,6 +304,30 @@ describe('googleauth', () => { assert.deepEqual(await auth.getRequestHeaders(''), customRequestHeaders); }); + it('should accept and use an `apiKey`', async () => { + const apiKey = 'myKey'; + const auth = new GoogleAuth({apiKey}); + const client = await auth.getClient(); + + assert.equal(client.apiKey, apiKey); + assert.deepEqual(await auth.getRequestHeaders(), { + 'X-Goog-Api-Key': apiKey, + }); + }); + + it('should not accept both an `apiKey` and `credentials`', async () => { + const apiKey = 'myKey'; + assert.throws( + () => + new GoogleAuth({ + credentials: {}, + // API key should supported via `clientOptions` + clientOptions: {apiKey}, + }), + new RangeError(GoogleAuthExceptionMessages.API_KEY_WITH_CREDENTIALS) + ); + }); + it('fromJSON should support the instantiated named export', () => { const result = auth.fromJSON(createJwtJSON()); assert(result); From 66829d81f1936ed63698767019dffbd33f2e57e0 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:49:50 -0700 Subject: [PATCH 11/21] test: cleanup --- test/test.googleauth.ts | 8 -------- 1 file changed, 8 deletions(-) diff --git a/test/test.googleauth.ts b/test/test.googleauth.ts index e703e057..afb56a3b 100644 --- a/test/test.googleauth.ts +++ b/test/test.googleauth.ts @@ -354,14 +354,6 @@ describe('googleauth', () => { assert.strictEqual(client.email, 'hello@youarecool.com'); }); - it('fromAPIKey should error given an invalid api key', () => { - assert.throws(() => { - // Test verifies invalid parameter tests, which requires cast to any. - // eslint-disable-next-line @typescript-eslint/no-explicit-any - (auth as any).fromAPIKey(null); - }); - }); - it('should make a request with the api key', async () => { const scope = nock(BASE_URL) .post(ENDPOINT) From 5f47a63f84f16df0f5b307dae18cda20834e67d7 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 2 Aug 2024 15:54:06 -0700 Subject: [PATCH 12/21] docs: Clarifications --- src/auth/googleauth.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index d31f2833..82b106f5 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -183,8 +183,8 @@ export class GoogleAuth { // To save the contents of the JSON credential file jsonContent: JWTInput | ExternalAccountClientOptions | null = null; - apiKey: string | null; + cachedCredential: JSONClient | Impersonated | Compute | T | null = null; /** @@ -816,6 +816,8 @@ export class GoogleAuth { /** * Create a credentials instance using the given API key string. + * The created client is not cached. In order to create and cache it use the {@link GoogleAuth.getClient `getClient`} method after first providing an {@link GoogleAuth.apiKey `apiKey`}. + * * @param apiKey The API key string * @param options An optional options object. * @returns A JWT loaded from the key From 12ae76cb556e675fb02f2a66c3ba9b370945c268 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Tue, 6 Aug 2024 11:22:06 -0700 Subject: [PATCH 13/21] refactor: streamline --- src/auth/googleauth.ts | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index 82b106f5..6052773c 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -212,9 +212,7 @@ export class GoogleAuth { * * @param opts */ - constructor(opts?: GoogleAuthOptions) { - opts = opts || {}; - + constructor(opts: GoogleAuthOptions = {}) { this._cachedProjectId = opts.projectId || null; this.cachedCredential = opts.authClient || null; this.keyFilename = opts.keyFilename || opts.keyFile; From 0bba0850ffa56ea00a9f90d29048b0e2b03ef467 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Wed, 14 Aug 2024 11:50:00 -0700 Subject: [PATCH 14/21] chore: merge cleanup --- src/auth/googleauth.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index 8809a7bf..d3b7fc2e 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -25,7 +25,7 @@ import {DefaultTransporter, Transporter} from '../transporters'; import {Compute, ComputeOptions} from './computeclient'; import {CredentialBody, ImpersonatedJWTInput, JWTInput} from './credentials'; -import {IdTokenClient, IdTokenProvider} from './idtokenclient'; +import {IdTokenClient} from './idtokenclient'; import {GCPEnv, getEnv} from './envDetect'; import {JWT, JWTOptions} from './jwtclient'; import {Headers, OAuth2ClientOptions} from './oauth2client'; @@ -413,7 +413,7 @@ export class GoogleAuth { } private async getApplicationDefaultAsync( - options: AuthClientOptions | OAuth2ClientOptions = {} + options: AuthClientOptions = {} ): Promise { // If we've already got a cached credential, return it. // This will also preserve one's configured quota project, in case they From 4191d61ac375603fceab496aa764cdb34387b63b Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 16 Aug 2024 15:30:36 -0700 Subject: [PATCH 15/21] docs(sample): Add API Key Sample --- samples/authenticateAPIKey.js | 63 +++++++++++++++++++++++++++++++++++ samples/package.json | 1 + 2 files changed, 64 insertions(+) create mode 100644 samples/authenticateAPIKey.js diff --git a/samples/authenticateAPIKey.js b/samples/authenticateAPIKey.js new file mode 100644 index 00000000..da9df2c1 --- /dev/null +++ b/samples/authenticateAPIKey.js @@ -0,0 +1,63 @@ +// Copyright 2024 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. + +/** + * Lists storage buckets by authenticating with ADC. + */ +function main() { + // [START apikeys_authenticate_api_key] + + const { + v1: {LanguageServiceClient}, + } = require('@google-cloud/language'); + + /** + * Authenticates with an API key for Google Language service. + * + * @param {string} apiKey An API Key to use + */ + async function authenticateWithAPIKey(apiKey) { + const language = new LanguageServiceClient({apiKey}); + + // Alternatively: + // const auth = new GoogleAuth({apiKey}); + // const {GoogleAuth} = require('google-auth-library'); + // const language = new LanguageServiceClient({auth}); + + const text = 'Hello, world!'; + + const [response] = await language.analyzeSentiment({ + document: { + content: text, + type: 'PLAIN_TEXT', + }, + }); + + console.log(`Text: ${text}`); + console.log( + `Sentiment: ${response.documentSentiment.score}, ${response.documentSentiment.magnitude}` + ); + console.log('Successfully authenticated using the API key'); + } + + authenticateWithAPIKey(); + // [END apikeys_authenticate_api_key] +} + +process.on('unhandledRejection', err => { + console.error(err.message); + process.exitCode = 1; +}); + +main(...process.argv.slice(2)); diff --git a/samples/package.json b/samples/package.json index 4733d8c4..9fc2109a 100644 --- a/samples/package.json +++ b/samples/package.json @@ -13,6 +13,7 @@ }, "license": "Apache-2.0", "dependencies": { + "@google-cloud/language": "^6.5.0", "@google-cloud/storage": "^7.0.0", "@googleapis/iam": "^20.0.0", "google-auth-library": "^9.13.0", From 70ab441bcd6f6e03d7348f6a819de78a33d661c3 Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Fri, 16 Aug 2024 22:33:21 +0000 Subject: [PATCH 16/21] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20?= =?UTF-8?q?post-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- README.md | 1 + samples/README.md | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+) diff --git a/README.md b/README.md index f166b09c..c5966aed 100644 --- a/README.md +++ b/README.md @@ -1348,6 +1348,7 @@ Samples are in the [`samples/`](https://github.com/googleapis/google-auth-librar | Sample | Source Code | Try it | | --------------------------- | --------------------------------- | ------ | | Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/adc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/adc.js,samples/README.md) | +| Authenticate API Key | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateAPIKey.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateAPIKey.js,samples/README.md) | | Authenticate Explicit | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateExplicit.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateExplicit.js,samples/README.md) | | Authenticate Implicit With Adc | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateImplicitWithAdc.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateImplicitWithAdc.js,samples/README.md) | | Compute | [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/compute.js) | [![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/compute.js,samples/README.md) | diff --git a/samples/README.md b/samples/README.md index 115dba68..5ea1e11e 100644 --- a/samples/README.md +++ b/samples/README.md @@ -13,6 +13,7 @@ This is Google's officially supported [node.js](http://nodejs.org/) client libra * [Before you begin](#before-you-begin) * [Samples](#samples) * [Adc](#adc) + * [Authenticate API Key](#authenticate-api-key) * [Authenticate Explicit](#authenticate-explicit) * [Authenticate Implicit With Adc](#authenticate-implicit-with-adc) * [Compute](#compute) @@ -67,6 +68,23 @@ __Usage:__ +### Authenticate API Key + +View the [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateAPIKey.js). + +[![Open in Cloud Shell][shell_img]](https://console.cloud.google.com/cloudshell/open?git_repo=https://github.com/googleapis/google-auth-library-nodejs&page=editor&open_in_editor=samples/authenticateAPIKey.js,samples/README.md) + +__Usage:__ + + +`node samples/authenticateAPIKey.js` + + +----- + + + + ### Authenticate Explicit View the [source code](https://github.com/googleapis/google-auth-library-nodejs/blob/main/samples/authenticateExplicit.js). From e4d3e5d0ebe95e84b3ce67cb37f4f7262b83836b Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Fri, 16 Aug 2024 15:37:33 -0700 Subject: [PATCH 17/21] chore: OCD --- .readme-partials.yaml | 2 +- src/auth/googleauth.ts | 6 +----- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/.readme-partials.yaml b/.readme-partials.yaml index 5fb3e97e..7b26d0d2 100644 --- a/.readme-partials.yaml +++ b/.readme-partials.yaml @@ -240,7 +240,7 @@ body: |- }) ``` - Availability varies by API. + API Key support varies by API. ## JSON Web Tokens The Google Developers Console provides a `.json` file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account. diff --git a/src/auth/googleauth.ts b/src/auth/googleauth.ts index d3b7fc2e..06ae466b 100644 --- a/src/auth/googleauth.ts +++ b/src/auth/googleauth.ts @@ -1038,11 +1038,7 @@ export class GoogleAuth { 'Cannot fetch ID token in this environment, use GCE or set the GOOGLE_APPLICATION_CREDENTIALS environment variable to a service account credentials JSON file.' ); } - - return new IdTokenClient({ - targetAudience, - idTokenProvider: client, - }); + return new IdTokenClient({targetAudience, idTokenProvider: client}); } /** From 1bd5a38d6e41412ae7d0d78c6bfc00109df01e13 Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Fri, 16 Aug 2024 22:39:48 +0000 Subject: [PATCH 18/21] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20?= =?UTF-8?q?post-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c5966aed..e15d28fc 100644 --- a/README.md +++ b/README.md @@ -284,7 +284,7 @@ const auth = new GoogleAuth({ }) ``` -Availability varies by API. +API Key support varies by API. ## JSON Web Tokens The Google Developers Console provides a `.json` file that you can use to configure a JWT auth client and authenticate your requests, for example when using a service account. From b0ce42f3e89832cd4f83afaafd0df5fd7710d829 Mon Sep 17 00:00:00 2001 From: Daniel Bankhead Date: Mon, 19 Aug 2024 10:37:54 -0700 Subject: [PATCH 19/21] Apply suggestions from code review Co-authored-by: sofisl <55454395+sofisl@users.noreply.github.com> --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e15d28fc..fe7da8e0 100644 --- a/README.md +++ b/README.md @@ -273,7 +273,7 @@ const client = new OAuth2Client({ }); ``` -Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. +Note, classes that extend from `OAuth2Client` can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. Additionally, an API key can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: ```js From 4eba6d23c35664b6a3912878d3b573c4bea3d709 Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Mon, 19 Aug 2024 17:39:51 +0000 Subject: [PATCH 20/21] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20?= =?UTF-8?q?post-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fe7da8e0..e15d28fc 100644 --- a/README.md +++ b/README.md @@ -273,7 +273,7 @@ const client = new OAuth2Client({ }); ``` -Note, classes that extend from `OAuth2Client` can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. +Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. Additionally, an API key can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: ```js From b7d6a916b97aab7f120dd15d981b64cc7c082ffe Mon Sep 17 00:00:00 2001 From: Owl Bot Date: Mon, 19 Aug 2024 17:40:22 +0000 Subject: [PATCH 21/21] =?UTF-8?q?=F0=9F=A6=89=20Updates=20from=20OwlBot=20?= =?UTF-8?q?post-processor?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fe7da8e0..e15d28fc 100644 --- a/README.md +++ b/README.md @@ -273,7 +273,7 @@ const client = new OAuth2Client({ }); ``` -Note, classes that extend from `OAuth2Client` can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. +Note, classes that extend from this can utilize this parameter as well, such as `JWT` and `UserRefreshClient`. Additionally, an API key can be used in `GoogleAuth` via the `clientOptions` parameter and will be passed to any generated `OAuth2Client` instances: ```js