google-auth-library - npm Package Compare versions

Comparing version 8.1.1 to 8.2.0

build/src/auth/baseexternalclient.d.ts

@@ -83,3 +83,3 @@ import { GaxiosOptions, GaxiosPromise, GaxiosResponse } from 'gaxios';
     protected readonly audience: string;
-    private readonly subjectTokenType;
+    protected readonly subjectTokenType: string;
     private readonly serviceAccountImpersonationUrl?;
@@ -86,0 +86,0 @@ private readonly stsCredential;

build/src/auth/externalclient.d.ts

@@ -5,3 +5,4 @@ import { RefreshOptions } from './oauth2client';
 import { AwsClientOptions } from './awsclient';
-export declare type ExternalAccountClientOptions = IdentityPoolClientOptions | AwsClientOptions;
+import { PluggableAuthClientOptions } from './pluggable-auth-client';
+export declare type ExternalAccountClientOptions = IdentityPoolClientOptions | AwsClientOptions | PluggableAuthClientOptions;
 /**
@@ -8,0 +9,0 @@ * Dummy class with no constructor. Developers are expected to use fromJSON.

build/src/auth/externalclient.js

@@ -20,2 +20,3 @@ "use strict";
 const awsclient_1 = require("./awsclient");
+const pluggable_auth_client_1 = require("./pluggable-auth-client");
 /**
@@ -29,3 +30,4 @@ * Dummy class with no constructor. Developers are expected to use fromJSON.
             'directly via explicit constructors, eg. ' +
-            'new AwsClient(options), new IdentityPoolClient(options) or via ' +
+            'new AwsClient(options), new IdentityPoolClient(options), new' +
+            'PluggableAuthClientOptions, or via ' +
             'new GoogleAuth(options).getClient()');
@@ -46,3 +48,3 @@ }
     static fromJSON(options, additionalOptions) {
-        var _a;
+        var _a, _b;
         if (options && options.type === baseexternalclient_1.EXTERNAL_ACCOUNT_TYPE) {
@@ -52,2 +54,5 @@ if ((_a = options.credential_source) === null || _a === void 0 ? void 0 : _a.environment_id) {
             }
+            else if ((_b = options.credential_source) === null || _b === void 0 ? void 0 : _b.executable) {
+                return new pluggable_auth_client_1.PluggableAuthClient(options, additionalOptions);
+            }
             else {
@@ -54,0 +59,0 @@ return new identitypoolclient_1.IdentityPoolClient(options, additionalOptions);

build/src/index.d.ts

@@ -20,4 +20,5 @@ import { GoogleAuth } from './auth/googleauth';
 export { CredentialAccessBoundary, DownscopedClient, } from './auth/downscopedclient';
+export { PluggableAuthClient, PluggableAuthClientOptions, } from './auth/pluggable-auth-client';
 export { DefaultTransporter } from './transporters';
 declare const auth: GoogleAuth<import("./auth/googleauth").JSONClient>;
 export { auth, GoogleAuth };

build/src/index.js

 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.GoogleAuth = exports.auth = exports.DefaultTransporter = exports.DownscopedClient = exports.BaseExternalAccountClient = exports.ExternalAccountClient = exports.IdentityPoolClient = exports.AwsClient = exports.UserRefreshClient = exports.LoginTicket = exports.OAuth2Client = exports.CodeChallengeMethod = exports.Impersonated = exports.JWT = exports.JWTAccess = exports.IdTokenClient = exports.IAMAuth = exports.GCPEnv = exports.Compute = exports.AuthClient = void 0;
+exports.GoogleAuth = exports.auth = exports.DefaultTransporter = exports.PluggableAuthClient = exports.DownscopedClient = exports.BaseExternalAccountClient = exports.ExternalAccountClient = exports.IdentityPoolClient = exports.AwsClient = exports.UserRefreshClient = exports.LoginTicket = exports.OAuth2Client = exports.CodeChallengeMethod = exports.Impersonated = exports.JWT = exports.JWTAccess = exports.IdTokenClient = exports.IAMAuth = exports.GCPEnv = exports.Compute = exports.AuthClient = void 0;
 // Copyright 2017 Google LLC
@@ -52,2 +52,4 @@ //
 Object.defineProperty(exports, "DownscopedClient", { enumerable: true, get: function () { return downscopedclient_1.DownscopedClient; } });
+var pluggable_auth_client_1 = require("./auth/pluggable-auth-client");
+Object.defineProperty(exports, "PluggableAuthClient", { enumerable: true, get: function () { return pluggable_auth_client_1.PluggableAuthClient; } });
 var transporters_1 = require("./transporters");
@@ -54,0 +56,0 @@ Object.defineProperty(exports, "DefaultTransporter", { enumerable: true, get: function () { return transporters_1.DefaultTransporter; } });

CHANGELOG.md

@@ -7,2 +7,9 @@ # Changelog
 
+## [8.2.0](https://github.com/googleapis/google-auth-library-nodejs/compare/v8.1.1...v8.2.0) (2022-08-11)
+
+
+### Features
+
+* adds Pluggable Auth support ([#1437](https://github.com/googleapis/google-auth-library-nodejs/issues/1437)) ([ed7ef7a](https://github.com/googleapis/google-auth-library-nodejs/commit/ed7ef7a5d1fa6bf5d06bdaab278052fd3930fb7f))
+
 ## [8.1.1](https://github.com/googleapis/google-auth-library-nodejs/compare/v8.1.0...v8.1.1) (2022-07-08)
@@ -9,0 +16,0 @@

package.json

 {
   "name": "google-auth-library",
-  "version": "8.1.1",
+  "version": "8.2.0",
   "author": "Google Inc.",
@@ -63,3 +63,3 @@ "description": "Google APIs Authentication Client Library for Node.js",
     "null-loader": "^4.0.0",
-    "puppeteer": "^15.0.0",
+    "puppeteer": "^16.0.0",
     "sinon": "^14.0.0",
@@ -66,0 +66,0 @@ "tmp": "^0.2.0",

README.md

@@ -523,4 +523,133 @@ [//]: # "This README.md file is auto-generated, all changes to this file will be lost."
 
-You can now [start using the Auth library](#using-external-identities) to call Google Cloud resources from an OIDC provider.
+#### Using Executable-sourced credentials with OIDC and SAML
 
+**Executable-sourced credentials**
+For executable-sourced credentials, a local executable is used to retrieve the 3rd party token.
+The executable must handle providing a valid, unexpired OIDC ID token or SAML assertion in JSON format
+to stdout.
+
+To use executable-sourced credentials, the `GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES`
+environment variable must be set to `1`.
+
+To generate an executable-sourced workload identity configuration, run the following command:
+
+```bash
+# Generate a configuration file for executable-sourced credentials.
+gcloud iam workload-identity-pools create-cred-config \
+    projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$POOL_ID/providers/$PROVIDER_ID \
+    --service-account=$SERVICE_ACCOUNT_EMAIL \
+    --subject-token-type=$SUBJECT_TOKEN_TYPE \
+    # The absolute path for the program, including arguments.
+    # e.g. --executable-command="/path/to/command --foo=bar"
+    --executable-command=$EXECUTABLE_COMMAND \
+    # Optional argument for the executable timeout. Defaults to 30s.
+    # --executable-timeout-millis=$EXECUTABLE_TIMEOUT \
+    # Optional argument for the absolute path to the executable output file.
+    # See below on how this argument impacts the library behaviour.
+    # --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.
+- `$SERVICE_ACCOUNT_EMAIL`: The email of the service account to impersonate.
+- `$SUBJECT_TOKEN_TYPE`: The subject token type.
+- `$EXECUTABLE_COMMAND`: The full command to run, including arguments. Must be an absolute path to the program.
+
+The `--executable-timeout-millis` flag is optional. This is the duration for which
+the auth library will wait for the executable to finish, in milliseconds.
+Defaults to 30 seconds when not provided. The maximum allowed value is 2 minutes.
+The minimum is 5 seconds.
+
+The `--executable-output-file` flag is optional. If provided, the file path must
+point to the 3PI credential response generated by the executable. This is useful
+for caching the credentials. By specifying this path, the Auth libraries will first
+check for its existence before running the executable. By caching the executable JSON
+response to this file, it improves performance as it avoids the need to run the executable
+until the cached credentials in the output file are expired. The executable must
+handle writing to this file - the auth libraries will only attempt to read from
+this location. The format of contents in the file should match the JSON format
+expected by the executable shown below.
+
+To retrieve the 3rd party token, the library will call the executable
+using the command specified. The executable's output must adhere to the response format
+specified below. It must output the response to stdout.
+
+A sample successful executable OIDC response:
+```json
+{
+  "version": 1,
+  "success": true,
+  "token_type": "urn:ietf:params:oauth:token-type:id_token",
+  "id_token": "HEADER.PAYLOAD.SIGNATURE",
+  "expiration_time": 1620499962
+}
+```
+
+A sample successful executable SAML response:
+```json
+{
+  "version": 1,
+  "success": true,
+  "token_type": "urn:ietf:params:oauth:token-type:saml2",
+  "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,
+  "success": false,
+  "code": "401",
+  "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.
+
+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.
+
+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.
+
+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.
+
+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
+credentials unless they do not meet your specific requirements.
+
+You can now [use the Auth library](#using-external-identities) to call Google Cloud
+resources from an OIDC or SAML provider.
+
 ### Using External Identities
@@ -527,0 +656,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

Found 2 instances in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

472104

increased by10.14%

Number of package files

66

increased by10%

Lines of code

8101

increased by11.97%

Number of lines in readme file

1049

increased by14.02%

Worsened metrics

Number of low supply chain risk alerts

28

increased by12%

Number of medium supply chain risk alerts

2

increased by100%

No dependency changes