@aws-sdk/credential-provider-web-identity
Advanced tools
@aws-sdk/credential-provider-web-identity - npm Package Compare versions
Comparing version 3.25.0 to 3.27.0
@@ -6,2 +6,13 @@ # Change Log | ||
| # [3.27.0](https://github.com/aws/aws-sdk-js-v3/compare/v3.26.0...v3.27.0) (2021-08-19) | ||
| ### Features | ||
| * **credential-providers:** collect credential providers in single package ([#2672](https://github.com/aws/aws-sdk-js-v3/issues/2672)) ([5375c91](https://github.com/aws/aws-sdk-js-v3/commit/5375c91f8a4d2cac6918885843718f47ce82e5d5)) | ||
| # [3.25.0](https://github.com/aws/aws-sdk-js-v3/compare/v3.24.0...v3.25.0) (2021-08-05) | ||
@@ -8,0 +19,0 @@ |
| { | ||
| "name": "@aws-sdk/credential-provider-web-identity", | ||
| "version": "3.25.0", | ||
| "version": "3.27.0", | ||
| "description": "AWS credential provider that calls STS assumeRole for temporary AWS credentials", | ||
@@ -24,3 +24,3 @@ "main": "./dist/cjs/index.js", | ||
| "dependencies": { | ||
| "@aws-sdk/property-provider": "3.25.0", | ||
| "@aws-sdk/property-provider": "3.27.0", | ||
| "@aws-sdk/types": "3.25.0", | ||
@@ -27,0 +27,0 @@ "tslib": "^2.3.0" |
136
README.md
@@ -6,135 +6,7 @@ # @aws-sdk/credential-provider-web-identity | ||
| ## AWS Credential Provider for Node.js - AssumeRole | ||
| > An internal package | ||
| This module includes functions which get credentials by calling STS assumeRoleWithWebIdentity API. | ||
| ## Usage | ||
| ## fromWebToken | ||
| The function `fromWebToken` returns `CredentialProvider` that get credentials calling sts:assumeRoleWithWebIdentity | ||
| API via `roleAssumerWithWebIdentity`. | ||
| ### Supported configuration | ||
| This configuration supports all the input parameters from | ||
| [sts:AssumeWithWebIdentity](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/clients/client-sts/modules/assumerolewithwebidentityrequest.html) API. The following options are supported: | ||
| - `roleArn` - The Amazon Resource Name (ARN) of the role that the caller is assuming. | ||
| - `webIdentityToken` - The OAuth 2.0 access token or OpenID Connect ID token that is provided by the identity provider. | ||
| - `roleSessionName` - An identifier for the assumed role session. | ||
| - `providerId` - The fully qualified host component of the domain name of the identity provider. Do not specify this | ||
| value for OpenID Connect ID tokens. | ||
| - `policyArns` - The Amazon Resource Names (ARNs) of the IAM managed policies that you want to use as managed session | ||
| policies. | ||
| - `policy` - An IAM policy in JSON format that you want to use as an inline session policy. | ||
| - `durationSeconds` - The duration, in seconds, of the role session. Default to 3600. | ||
| - `roleAssumerWithWebIdentity` - A function that assumes a role with web identity | ||
| and returns a promise fulfilled with credentials for the assumed role. You may call | ||
| `sts:assumeRoleWithWebIdentity` API within this function. | ||
| ### Examples | ||
| You can directly configure individual identity providers to access AWS resources using web identity federation. AWS | ||
| currently supports authenticating users using web identity federation through several identity providers: | ||
| - [Login with Amazon](https://login.amazon.com/) | ||
| - [Facebook Login](https://developers.facebook.com/docs/facebook-login/web/) | ||
| - [Google Sign-in](https://developers.google.com/identity/) | ||
| You must first register your application with the providers that your application supports. Next, create an IAM role and | ||
| set up permissions for it. The IAM role you create is then used to grant the permissions you configured for it through | ||
| the respective identity provider. For example, you can set up a role that allows users who logged in through Facebook | ||
| to have read access to a specific Amazon S3 bucket you control. | ||
| After you have both an IAM role with configured privileges and an application registered with your chosen identity | ||
| providers, you can set up the SDK to get credentials for the IAM role using helper code, as follows: | ||
| ```javascript | ||
| import { DynamoDBClient } from "@aws-sdk/client-dynamodb"; | ||
| import { getDefaultRoleAssumerWithWebIdentity } from "@aws-sdk/client-sts"; | ||
| import { fromWebToken } from "@aws-sdk/credential-provider-web-identity"; | ||
| const dynamodb = new DynamoDBClient({ | ||
| region, | ||
| credentials: fromWebToken({ | ||
| roleArn: 'arn:aws:iam::<AWS_ACCOUNT_ID>/:role/<WEB_IDENTITY_ROLE_NAME>', | ||
| providerId: 'graph.facebook.com|www.amazon.com', // this is null for Google | ||
| webIdentityToken: ACCESS_TOKEN // from OpenID token identity provider | ||
| roleAssumerWithWebIdentity: getDefaultRoleAssumerWithWebIdentity(), | ||
| }) | ||
| }); | ||
| ``` | ||
| The value in the ProviderId parameter depends on the specified identity provider. The value in the WebIdentityToken | ||
| parameter is the access token retrieved from a successful login with the identity provider. For more information on how | ||
| to configure and retrieve access tokens for each identity provider, see the documentation for the identity provider. | ||
| ## fromTokenFile | ||
| The function `fromTokenFile` returns `CredentialProvider` that reads credentials as follows: | ||
| - Reads file location of where the OIDC token is stored from either provided option `webIdentityTokenFile` or environment variable `AWS_WEB_IDENTITY_TOKEN_FILE`. | ||
| - Reads IAM role wanting to be assumed from either provided option `roleArn` or environment variable `AWS_ROLE_ARN`. | ||
| - Reads optional role session name to be used to distinguish sessions from provided option `roleSessionName` or environment variable `AWS_ROLE_SESSION_NAME`. | ||
| If session name is not defined, it comes up with a role session name. | ||
| - Reads OIDC token from file on disk. | ||
| - Calls sts:AssumeRoleWithWebIdentity via `roleAssumerWithWebIdentity` option to get credentials. | ||
| | **Configuration Key** | **Environment Variable** | **Required** | **Description** | | ||
| | --------------------- | --------------------------- | ------------ | ------------------------------------------------- | | ||
| | webIdentityTokenFile | AWS_WEB_IDENTITY_TOKEN_FILE | true | File location of where the `OIDC` token is stored | | ||
| | roleArn | AWS_IAM_ROLE_ARN | true | The IAM role wanting to be assumed | | ||
| | roleSessionName | AWS_IAM_ROLE_SESSION_NAME | false | The IAM session name used to distinguish sessions | | ||
| ### Supported configuration | ||
| The following options are supported: | ||
| - `roleAssumerWithWebIdentity` - A function that assumes a role with web identity | ||
| and returns a promise fulfilled with credentials for the assumed role. You may call | ||
| `sts:assumeRoleWithWebIdentity` API within this function. | ||
| ### Examples | ||
| A basic example of using fromTokenFile: | ||
| ```js | ||
| import { getDefaultRoleAssumerWithWebIdentity } from "@aws-sdk/client-sts"; | ||
| import { fromTokenFile } from "@aws-sdk/credential-provider-web-identity"; | ||
| const client = new FooClient({ | ||
| credentials: fromTokenFile({ | ||
| roleAssumerWithWebIdentity: getDefaultRoleAssumerWithWebIdentity() | ||
| }); | ||
| }); | ||
| ``` | ||
| #### Values in environment variables | ||
| The values can be defined in environment variables as follows: | ||
| ```console | ||
| $ node | ||
| > Object.fromEntries(Object.entries(process.env).filter(([key, value]) => key.startsWith("AWS_"))); | ||
| { | ||
| AWS_WEB_IDENTITY_TOKEN_FILE: '/temp/token', | ||
| AWS_ROLE_ARN: 'arn:aws:iam::123456789012:role/example-role-arn' | ||
| } | ||
| ``` | ||
| #### Values in configuration keys | ||
| The values can be defined in configuration keys as follows: | ||
| ```js | ||
| ... | ||
| const client = new FooClient({ | ||
| credentials: fromTokenFile({ | ||
| webIdentityTokenFile: "/temp/token", | ||
| roleArn: "arn:aws:iam::123456789012:role/example-role-arn", | ||
| roleAssumerWithWebIdentity: getDefaultRoleAssumerWithWebIdentity() | ||
| }); | ||
| }); | ||
| ``` | ||
| You probably shouldn't, at least directly. Please use [@aws-sdk/credential-providers](https://www.npmjs.com/package/@aws-sdk/credential-providers) | ||
| instead. |
New alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Fixed alerts
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Worsened metrics
- Total package byte prevSize
- decreased by-4.24%
131123
- Number of lines in readme file
- decreased by-91.43%
12
Dependency changes
+ Added@aws-sdk/property-provider@3.27.0(transitive)
- Removed@aws-sdk/property-provider@3.25.0(transitive)