Using the TIP plugin to access Amazon Web Services services - Amazon SDKs and Tools
Prerequisites for using the TIP pluginTo use the TIP plugin in your code
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using the TIP plugin to access Amazon Web Services services

Trusted identity propagation (TIP) is a feature of Amazon IAM Identity Center that enables administrators of Amazon Web Services services to grant permissions based on user attributes such as group associations. With trusted identity propagation, identity context is added to an IAM role to identify the user requesting access to Amazon resources. This context is propagated to other Amazon Web Services services.

Identity context comprises information that Amazon Web Services services use to make authorization decisions when they receive access requests. This information includes metadata that identifies the requester (for example, an IAM Identity Center user), the Amazon Web Services service to which access is requested (for example, Amazon Redshift), and the scope of access (for example, read only access). The receiving Amazon Web Services service uses this context, and any permissions assigned to the user, to authorize access to its resources. For more information, see in the Trusted identity propagation overview in the Amazon IAM Identity Center User Guide.

Prerequisites for using the TIP plugin

The following resources are required in order for the plugin to work:

  1. You must be using either the Amazon SDK for Java or the Amazon SDK for JavaScript.

  2. Verify that the service you are using supports the trusted identity propagation.

    See the Enables trusted identity propagation through IAM Identity Center column of the Amazon managed applications that integrate with IAM Identity Center table in the Amazon IAM Identity Center User Guide.

  3. Enable IAM Identity Center and trusted identity propagation.

    See TIP prerequisites and considerations in the Amazon IAM Identity Center User Guide.

  4. You must have an Identity-Center-integrated application.

    See Amazon managed applications or Customer managed applications in the Amazon IAM Identity Center User Guide.

  5. You must set up a trusted token issuer (TTI) and connect your service to IAM Identity Center.

    See Prerequisites for trusted token issuers and Tasks for setting up a trusted token issuer in the Amazon IAM Identity Center User Guide.

To use the TIP plugin in your code

  1. Create an instance of the trusted identity propagation plugin.

  2. Create a service client instance for interacting with your Amazon Web Services service and customize the service client by adding the trusted identity propagation plugin.

The TIP plugin takes the following input parameters:

  • webTokenProvider: A function that the customer implements to obtain an OpenID token from their external identity provider.

  • accessRoleArn: The IAM role ARN to be assumed by the plugin with the user's identity context to get the identity-enhanced credentials.

  • applicationArn: The unique identifier string for the client or application. This value is an application ARN that has OAuth grants configured.

  • applicationRoleArn: (Optional) The IAM role ARN to be assumed with AssumeRoleWithWebIdentity so that the OIDC and Amazon STS clients can be bootstrapped without a default credentials provider. If this is not provided, the value of the accessRoleArn parameter will be used.

  • ssoOidcClient: (Optional) An SSO OIDC client, such as SsoOidcClient for Java or client-sso-oidc for Javascript, with customer-defined configurations. If not provided, an OIDC client using default configurations is instantiated and used.

  • stsClient: (Optional) An Amazon STS client with customer-defined configurations, used to assume accessRoleArn with the user's identity context. If not provided, an Amazon STS client using default configurations is instantiated and used.

Java

To use the TIP plugin in your Amazon SDK for Java project, you need to declare it as a dependency in your project's pom.xml file. 

<dependency>
<groupId>software.amazon.awsidentity.trustedIdentityPropagation</groupId>
<artifactId>aws-sdk-java-trustedIdentityPropagation-java-plugin</artifactId>
   <version>1.0.0</version>
</dependency>

In your source code, include the required package statement for software.amazon.awssdk.trustedidentitypropagation.

The following example code shows how to create an instance of the trusted identity propagation plugin and then add the plugin to a service client instance.

This example uses an S3Client as the chosen Amazon Web Services service client to show obtaining IAM Identity Center tokens. However, any other Amazon Web Services service that supports TIP would be similar. 

StsClient client = StsClient.builder()
    .region(Region.US_EAST_1)
    .credentialsProvider(AnonymousCredentialsProvider.create()).build();

TrustedIdentityPropagationPlugin trustedIdentityPropagationPlugin = TrustedIdentityPropagationPlugin.builder()
    .stsClient(client)
    .webTokenProvider(() -> idToken)
    .applicationArn(idcApplicationArn)
    .accessRoleArn(accessRoleArn)
    .ssoOidcClient(SsoOidcClient.builder().region(Region.US_EAST_1).build())
    .build();

S3Client s3Client =
   S3Client.builder().region(Region.US_EAST_1).addPlugin(trustedIdentityPropagationPlugin)
        .build();

For additional details and source, see trusted-identity-propagation-java on GitHub.

Javascript

Run the following command to install the TIP authentication plugin package in your Amazon SDK for JavaScript project: 

$  npm i @aws-sdk-extension/trusted-identity-propagation

The final package.json should include a dependency similar to the following: 

  "dependencies": {
"@aws-sdk-extension/trusted-identity-propagation": "^1.0.0"
  },

In your source code, import the required TrustedIdentityPropagationExtension dependency.

The following example code shows how to create an instance of the trusted identity propagation plugin and then add the plugin to a service client instance.

This example uses an S3Client as the chosen Amazon Web Services service client to show obtaining IAM Identity Center tokens. However, any other Amazon Web Services service that supports TIP would be similar. 

import { S3Client } from "@aws-sdk/client-s3";
import { TrustedIdentityPropagationExtension } from "@aws-sdk-extension/trusted-identity-propagation";

// Plugin configurations, please refer to the documentation on each of these fields.
const applicationRoleArn = 'YOUR_APPLICATION_ROLE_ARN';
const accessRoleArn = 'YOUR_ACCESS_ROLE_ARN';
const applicationArn = 'YOUR_APPLICATION_ARN';

const s3Client = new S3Client({
	region,
	extensions: [
		TrustedIdentityPropagationExtension.create({
			webTokenProvider: async () => {
				return 'ID_TOKEN_FROM_YOUR_IDENTITY_PROVIDER';
			},
			applicationRoleArn,
			accessRoleArn,
			applicationArn,
		}),
	],
});

For additional details and source, see trusted-identity-propagation-js on GitHub.