使用 TIP 插件进行访问 AWS 服务

可信身份传播 (TIP) 是一项功能 AWS IAM Identity Center ，允许的 AWS 服务管理员根据用户属性（例如群组关联）授予权限。通过可信身份传播，可以向 IAM 角色添加身份上下文，以识别请求访问 AWS 资源的用户。此上下文会传播到其他 AWS 服务。

身份上下文包含在他们收到访问请求时 AWS 服务用于做出授权决策的信息。这些信息包括识别请求者（例如，IAM 身份中心用户）、请求访问权限的元数据（例如 Amazon Redshift）和访问范围（例如，只读权限）的元数据。 AWS 服务接收方 AWS 服务使用此上下文以及分配给用户的任何权限来授权访问其资源。有关更多信息，请参阅《 AWS IAM Identity Center 用户指南》中的 “可信身份传播概述”。

TIP 插件可以与支持可信身份传播 AWS 服务的插件一起使用。作为参考使用案例，请参阅《Amazon Q Business 用户指南》中的 Configuring an Amazon Q Business application using AWS IAM Identity Center。

注意

如果您使用的是 Amazon Q Business，请参阅 Configuring an Amazon Q Business application using AWS IAM Identity Center，以了解服务特定的操作说明。

使用 TIP 插件的先决条件

需要具有下列资源才能正常使用该插件：

您必须使用适用于 Java 的 AWS SDK 或适用于 JavaScript 的 AWS SDK。
确认您使用的服务支持可信身份传播。

请参阅《AWS IAM Identity Center 用户指南》中 AWS managed applications that integrate with IAM Identity Center 表的 Enables trusted identity propagation through IAM Identity Center 列。
启用 IAM Identity Center 和可信身份传播。

请参阅《AWS IAM Identity Center 用户指南》中的 TIP prerequisites and considerations。
你必须有一个 Identity-Center-integrated应用程序。

请参阅《AWS IAM Identity Center 用户指南》中的 AWS managed applications 或 Customer managed applications。
您必须设置一个可信令牌颁发者（TTI）并将您的服务连接到 IAM Identity Center。

请参阅《AWS IAM Identity Center 用户指南》中的 Prerequisites for trusted token issuers 和 Tasks for setting up a trusted token issuer。

在代码中使用 TIP 插件

创建可信身份传播插件实例。
创建用于与您的交互的服务客户端实例， AWS 服务并通过添加可信身份传播插件来自定义服务客户端。

TIP 插件使用以下输入参数：

webTokenProvider：客户为了从其外部身份提供者处获取 OpenID 令牌而实现的函数。
accessRoleArn：该插件要使用用户的身份上下文代入的 IAM 角色的 ARN，用来获取身份增强型凭证。
applicationArn：客户端或应用程序的唯一标识符字符串。此值是已配置 OAuth 授权的应用程序 ARN。
ssoOidcClient:（可选）具有客户定义配置的 SSO OIDC 客户端，例如SsoOidcClient适用于 Java 或 for client-sso-oidc的 JavaScript客户端。如果未提供，则将实例化并使用采用 applicationRoleArn 的 OIDC 客户端。
stsClient：（可选）具有客户定义配置的 AWS STS 客户端，用于使用用户的身份上下文代入 accessRoleArn。如果未提供，则applicationRoleArn将实例化并使用正在使用的 AWS STS 客户端。
applicationRoleArn:（可选）要使用的 IAM 角色 ARN，AssumeRoleWithWebIdentity以便可以引导 OIDC 和 AWS STS 客户端。
- 如果未提供，则必须同时提供 ssoOidcClient 和 stsClient 参数。
- 如果提供，则 applicationRoleArn 的值不能与 accessRoleArn 参数的值相同。applicationRoleArn 用来构建用于代入 accessRole 的 stsClient。如果两者都使用相同的角色 applicationRoleaccessRole，则意味着使用角色来扮演自己（自我角色假设），这是不鼓励的。 AWS有关更多详细信息，请参阅公告。

`ssoOidcClient`、`stsClient` 和 `applicationRoleArn` 参数的注事意项

配置 TIP 插件时，根据您提供的参数应注意以下权限要求：

如果您提供了 ssoOidcClient 和 stsClient：
- ssoOidcClient 上的凭证应具有 oauth:CreateTokenWithIAM 权限，以调用 Identity Center 来获取 Identity Center 特定的用户上下文。
- stsClient 上的凭证应具有 accessRole 上的 sts:AssumeRole 和 sts:SetContext 权限。accessRole 还需要配置与 stsClient 上的凭证的信任关系。
如果您提供了 applicationRoleArn：
- applicationRole 应具有所需资源（IdC 实例、accessRole）的 oauth:CreateTokenWithIAM、sts:AssumeRole 和 sts:SetContext 权限，因为该角色将用于构建 OIDC 和 STS 客户端。
- applicationRole应该与用于生成的身份提供者建立信任关系webToken，因为webToken将用于通过插件的AssumeRoleWithWebIdentity调用来假设 ApplicationRole。

ApplicationRole 配置示例：

Web 令牌提供者的信任策略：


{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/IDENTITY_PROVIDER_URL"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "IDENTITY_PROVIDER_URL:aud": "CLIENT_ID_TO_BE_TRUSTED"
                }
            }
        }
    ]
}

权限策略：


{
    "Version": "2012-10-17",		 	 	 
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sts:AssumeRole",
                "sts:SetContext"
            ],
            "Resource": [
                "accessRoleArn"
            ]
        },
        {
            "Effect": "Allow",
            "Action": [
                "sso-oauth:CreateTokenWithIAM"
            ],
            "Resource": [
                "*"
            ]
        }
    ]
}

使用 TIP 的代码示例

以下示例显示了如何使用适用于 Java 的 AWS SDK 或在代码中实现 TIP 插件适用于 JavaScript 的 AWS SDK。

Java

要在适用于 Java 的 AWS SDK 项目中使用 TIP 插件，您需要在项目pom.xml文件中将其声明为依赖项。


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

在源代码中，包括 software.amazon.awssdk.trustedidentitypropagation 的必需软件包语句。

以下示例演示了创建可信身份传播插件实例并将其添加到服务客户端的两种方式。这两个示例都使用 Amazon S3 作为服务并S3AccessGrantsPlugin用来管理用户的特定权限，但可以应用于任何 AWS 服务支持可信身份传播 (TIP) 的权限。

注意

对于这些示例，您需要从 S3 访问权限管控设置用户特定的权限。有关更多详细信息，请参阅 S3 访问权限管控文档。

选项 1：构建并传递 OIDC 和 STS 客户端


SsoOidcClient oidcClient = SsoOidcClient.builder()
    .region(Region.US_EAST_1)
    .credentialsProvider(credentialsProvider).build();

StsClient stsClient = StsClient.builder()
    .region(Region.US_EAST_1)
    .credentialsProvider(credentialsProvider).build();

TrustedIdentityPropagationPlugin trustedIdentityPropagationPlugin = TrustedIdentityPropagationPlugin.builder()
        .webTokenProvider(() -> webToken)
        .applicationArn(idcApplicationArn)
        .accessRoleArn(accessRoleArn)
        .ssoOidcClient(oidcClient)
        .stsClient(stsClient)
        .build();

S3AccessGrantsPlugin accessGrantsPlugin = S3AccessGrantsPlugin.builder()
        .build();

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

final var resp = s3Client.getObject(GetObjectRequest.builder()
        .key("path/to/object/fileName")
        .bucket("bucketName")
        .build());

选项 2：将客户端创建传递给插件 applicationRoleArn 并推迟创建


TrustedIdentityPropagationPlugin trustedIdentityPropagationPlugin = TrustedIdentityPropagationPlugin.builder()
        .webTokenProvider(() -> webToken)
        .applicationArn(idcApplicationArn)
        .accessRoleArn(accessRoleArn)
        .applicationRoleArn(applicationRoleArn)
        .build();

S3AccessGrantsPlugin accessGrantsPlugin = S3AccessGrantsPlugin.builder()
        .build();

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

final var resp = s3Client.getObject(GetObjectRequest.builder()
        .key("path/to/object/fileName")
        .bucket("bucketName")
        .build());

有关更多详细信息和来源，请参阅 trusted-identity-propagation-java上的 GitHub。

JavaScript

运行以下命令在您的适用于 JavaScript 的 AWS SDK 项目中安装 TIP 身份验证插件包：


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

最终的 package.json 应包含与以下类似的依赖项：


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

在源代码中，导入所需的 TrustedIdentityPropagationExtension 依赖项。

以下示例演示了创建可信身份传播插件实例并将其添加到服务客户端的两种方式。这两个示例都使用 Amazon S3 作为服务，并利用 Amazon S3 访问权限来管理用户的特定权限，但可以应用于任何 AWS 服务支持可信身份传播 (TIP) 的权限。

注意

对于这些示例，您需要从Amazon S3 访问权限管控中设置用户特定的权限。有关更多详细信息，请参阅 Amazon S3 访问权限管控文档。

选项 1：构建并传递 OIDC 和 STS 客户端


import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { S3ControlClient, GetDataAccessCommand } from "@aws-sdk/client-s3-control";
import { TrustedIdentityPropagationExtension } from "@aws-sdk-extension/trusted-identity-propagation";

const s3ControlClient = new S3ControlClient({
    region: "us-east-1",
    extensions: [
        TrustedIdentityPropagationExtension.create({
            webTokenProvider: async () => {
                return 'ID_TOKEN_FROM_YOUR_IDENTITY_PROVIDER';
            },
            ssoOidcClient: customOidcClient,
            stsClient: customStsClient,
            accessRoleArn: accessRoleArn,
            applicationArn: applicationArn,
        }),
    ],
});

const getDataAccessParams = {
  Target: "S3_URI_PATH",
  Permission: "READ",
  AccountId: ACCOUNT_ID,
  InstanceArn: S3_ACCESS_GRANTS_ARN,
  TargetType: "Object",
};

try {
  const command = new GetDataAccessCommand(getDataAccessParams);
  const response = await s3ControlClient.send(command);

  const credentials = response.Credentials;

  // Create a new S3 client with the temporary credentials
  const temporaryS3Client = new S3Client({
    region: "us-east-1",
    credentials: {
      accessKeyId: credentials.AccessKeyId,
      secretAccessKey: credentials.SecretAccessKey,
      sessionToken: credentials.SessionToken,
    },
  });

  // Use the temporary S3 client to perform the operation
  const s3Params = {
    Bucket: "BUCKET_NAME",
    Key: "S3_OBJECT_KEY",
  };
  const getObjectCommand = new GetObjectCommand(s3Params);
  const s3Object = await temporaryS3Client.send(getObjectCommand);

  const fileContent = await s3Object.Body.transformToString();

  // Process the S3 object data
  console.log("Successfully retrieved S3 object:", fileContent);
} catch (error) {
  console.error("Error accessing S3 data:", error);
}

选项 2：将客户端创建传递给插件 applicationRoleArn 并推迟创建


import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";
import { S3ControlClient, GetDataAccessCommand } from "@aws-sdk/client-s3-control";
import { TrustedIdentityPropagationExtension } from "@aws-sdk-extension/trusted-identity-propagation";

const s3ControlClient = new S3ControlClient({
    region: "us-east-1",
    extensions: [
        TrustedIdentityPropagationExtension.create({
            webTokenProvider: async () => {
                return 'ID_TOKEN_FROM_YOUR_IDENTITY_PROVIDER';
            },
            accessRoleArn: accessRoleArn,
            applicationRoleArn: applicationRoleArn,
            applicationArn: applicationArn,
        }),
    ],
});

// Same S3 AccessGrants workflow as Option 1
const getDataAccessParams = {
  Target: "S3_URI_PATH",
  Permission: "READ",
  AccountId: ACCOUNT_ID,
  InstanceArn: S3_ACCESS_GRANTS_ARN,
  TargetType: "Object",
};

try {
  const command = new GetDataAccessCommand(getDataAccessParams);
  const response = await s3ControlClient.send(command);

  const credentials = response.Credentials;

  const temporaryS3Client = new S3Client({
    region: "us-east-1",
    credentials: {
      accessKeyId: credentials.AccessKeyId,
      secretAccessKey: credentials.SecretAccessKey,
      sessionToken: credentials.SessionToken,
    },
  });

  const s3Params = {
    Bucket: "BUCKET_NAME",
    Key: "S3_OBJECT_KEY",
  };
  const getObjectCommand = new GetObjectCommand(s3Params);
  const s3Object = await temporaryS3Client.send(getObjectCommand);

  const fileContent = await s3Object.Body.transformToString();

  console.log("Successfully retrieved S3 object:", fileContent);
} catch (error) {
  console.error("Error accessing S3 data:", error);
}

有关更多详细信息和来源，请参阅trusted-identity-propagation-js上的 GitHub。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

EC2 实例的 IAM 角色

设置参考

使用 TIP 插件进行访问 AWS 服务

注意

使用 TIP 插件的先决条件

在代码中使用 TIP 插件

ssoOidcClient、stsClient 和 applicationRoleArn 参数的注事意项

使用 TIP 的代码示例

注意

注意

`ssoOidcClient`、`stsClient` 和 `applicationRoleArn` 参数的注事意项