# @aws-cdk/aws-iam 中文文档

规范地址：https://npmcn.com/package/%40aws-cdk/aws-iam/

版本：1\.204\.0
npm 元数据更新时间：2023-11-21T10:15:36.229Z
中文译文更新时间：2026-11-07T09:20:05.562Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws-cdk/aws-iam
原文对照：https://npmcn.com/package/%40aws-cdk/aws-iam/?lang=original
项目主页：https://github.com/aws/aws-cdk
源码仓库：https://github.com/aws/aws-cdk

弃用说明：AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.4 MB，66 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>= 14\.15\.0
- 运行依赖：4 个
- peer 依赖：@aws-cdk/core 1\.204\.0，@aws-cdk/region-info 1\.204\.0，constructs ^3\.3\.69
- 首次发布：2018-07-31T13:36:10.012Z
- 最新版本发布：2023-06-19T21:05:06.888Z
- 近 30 天下载量：483326（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：288（近 12 个月 0 个）

## 中文简介

易于分配正确和最小IAM权限的 CDK 常规

## 安装

```sh
npm install @aws-cdk/aws-iam
```

也可以使用：`pnpm add @aws-cdk/aws-iam`、`yarn add @aws-cdk/aws-iam`、`bun add @aws-cdk/aws-iam`

## README

# AWS 身份和访问管理建构库

* * *

![End-of-Support](https://img.shields.io/badge/End--of--Support-critical.svg?style=for-the-badge)

> AWS CDK v1在2023-06-01上达到了支持结束. 此软件包不再更新,用户应该迁移到 AWS CDK v2.
> 
> 关于如何移徙的更多信息,请参见: [_移动到 AWS CDK v2_ 指南](https://docs.aws.amazon.com/cdk/v2/guide/migrating-v2.html)。 。 。 .

* * *

定义一个角色并添加权限到它 。 这将自动创建和 在角色上附上IAM政策:

[附加角色权限](https://npmcn.com/package/%40aws-cdk/aws-iam/test/example.role.lit.ts)

确定一项政策,并将其附加于团体、用户和角色。 请注意,可以附上 政策通过电话 `xxx.attachInlinePolicy(policy)` 或者说 `policy.attachToXxx(xxx)`。 。 。 .

[附加用户和组的政策](https://npmcn.com/package/%40aws-cdk/aws-iam/test/example.attaching.lit.ts)

管理后的政策可使用 `xxx.addManagedPolicy(ManagedPolicy.fromAwsManagedPolicyName(policyName))`数字 :

[附加管理的政策](https://npmcn.com/package/%40aws-cdk/aws-iam/test/example.managedpolicy.lit.ts)

## 授予资源许可

许多 AWS CDK 资源有 `grant*` 允许其他资源访问该资源的方法。 例如,下面的代码给一个DynamoDB表一个Lambda函数写权限(Put, Update, Dext).

```ts
declare const fn: lambda.Function;
declare const table: dynamodb.Table;

table.grantWriteData(fn);
```

比较普通 `grant` 方法允许您对资源给予特定权限 :

```ts
declare const fn: lambda.Function;
declare const table: dynamodb.Table;

table.grant(fn, 'dynamodb:PutItem');
```

这个 `grant*` 方法接受一个 `IGrantable` 对象。 这个接口由IAM principlal资源(组,用户和角色)和资源执行,这些资源承担了Lambda函数,EC2实例或代码构建项目等角色.

你可以找到哪个 `grant*` 资源方法 [AWS CDK API 参考](https://docs.aws.amazon.com/cdk/api/latest/docs/aws-construct-library.html)。 。 。 .

## 作用

许多AWS资源需要 _作用_ 操作。 这些角色定义了 AWS API 允许调用实例或其他 AWS 服务.

创建角色, 并使用正确的权限 _发言_ 实值 建立AWS基础设施的必要但乏味的部分。 为了 帮助您关注您的商业逻辑, CDK 将负责创建 角色并自动向它们充斥最少特权权限.

所有需要角色的构造,如果不指定,将会为您创建一个 一个在施工时间。 该角色将增加权限 如果将构造与来自 AWS 构造库(例如,如果您告诉一个 _AWS 代码管道_ 触发 a 一个 _AWS Lambda 函数_,管道的作用会自动得到 `lambda:InvokeFunction` 关于该 Lambda 函数的权限, 或者如果您明确允许使用 `grant` 函数(参见 上一节).

### 选择退出自动权限管理

你可能更喜欢自己管理角色权限 而不是拥有 CDK自动为你管理它们. 这可能发生在其中之一 下列情况:

-   您不喜欢 CDK 自动生成和 想要替换您的组合 .
-   CDK 生成的最小许可政策也正在变成 需要添加一些通配符才能保存 政策规模缩小.

为了防止构造更新您的角色策略, 传递对象 返回时间 `myRole.withoutPolicyUpdates()` 改为 `myRole` 自己来.

例如, 拥有 AWS 代码Pipeline _没有_ 自动添加所需 允许触发预期目标时,执行下列操作:

```ts
const role = new iam.Role(this, 'Role', {
  assumedBy: new iam.ServicePrincipal('codepipeline.amazonaws.com'),
  // custom description if desired
  description: 'This is a custom role...',
});

new codepipeline.Pipeline(this, 'Pipeline', {
  // Give the Pipeline an immutable view of the Role
  role: role.withoutPolicyUpdates(),
});

// You now have to manage the Role policies yourself
role.addToPolicy(new iam.PolicyStatement({
  actions: [/* whatever actions you want */],
  resources: [/* whatever resources you intend to touch */],
}));
```

### 利用现有角色

如果在您的账户中存在已经创建的角色 想要在您的 CDK 应用程序中使用, 您可以使用 `Role.fromRoleArn` 改为 导入它们如下:

```ts
const role = iam.Role.fromRoleArn(this, 'Role', 'arn:aws:iam::123456789012:role/MyExistingRole', {
  // Set 'mutable' to 'false' to use the role as-is and prevent adding new
  // policies to it. The default is 'true', which means the role may be
  // modified as part of the deployment.
  mutable: false,
});
```

## 配置外部图像

如果需要创建第三方将承担的角色,一般认为 [需要一个 `ExternalId` 假设他们](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)配置 a 一个 `ExternalId` 这样的工作:

[提供外部标识](https://npmcn.com/package/%40aws-cdk/aws-iam/test/example.external-id.lit.ts)

## 校长与身份

当我们说 _校长_我们是指你允许的实体 这个 实体可以是AWS Service,一个角色,或者更抽象的东西如"All 此账户中的用户,甚至"本组织的所有用户". 一个 _身份_ 代表一个能够拥有 附加政策,其中一项 `Role`, (中文(简体) ), `User`,或 `Group`。 。 。 .

## IAM 校长

在界定政策声明作为AssumeRole政策的一部分或作为A 资源政策,报表通常是指一个具体的IAM主 下级 `Principal`。 。 。 .

学院校长以班级为模式 `iam.PolicyPrincipal` 抽象阶级. 主要对象包括主类型(字符串)和值 (字符串阵列),可选的一组条件和本主的行动 要求它用于承担角色政策文件.

要在政策说明中添加本金,您可以使用抽象 `statement.addPrincipal`一个混凝土 `addXxxPrincipal` 方法:

-   `addAwsPrincipal`, (中文(简体) ), `addArnPrincipal` 或者说 `new ArnPrincipal(arn)` 页:1 `{ "AWS": arn }`
-   `addAwsAccountPrincipal` 或者说 `new AccountPrincipal(accountId)` 页:1 `{ "AWS": account-arn }`
-   `addServicePrincipal` 或者说 `new ServicePrincipal(service)` 页:1 `{ "Service": service }`
-   `addAccountRootPrincipal` 或者说 `new AccountRootPrincipal()` 页:1 `{ "AWS": { "Ref: "AWS::AccountId" } }`
-   `addCanonicalUserPrincipal` 或者说 `new CanonicalUserPrincipal(id)` 页:1 `{ "CanonicalUser": id }`
-   `addFederatedPrincipal` 或者说 `new FederatedPrincipal(federated, conditions, assumeAction)` 页:1 `{ "Federated": arn }` 和一组可选条件 以及角色扮演动作.
-   `addAnyPrincipal` 或者说 `new AnyPrincipal` 页:1 `{ "AWS": "*" }`

如果在政策说明中增加多个主要负责人,将合并:

```ts
const statement = new iam.PolicyStatement();
statement.addServicePrincipal('cloudwatch.amazonaws.com');
statement.addServicePrincipal('ec2.amazonaws.com');
statement.addArnPrincipal('arn:aws:boom:boom');
```

将导致:

```json
{
  "Principal": {
    "Service": [ "cloudwatch.amazonaws.com", "ec2.amazonaws.com" ],
    "AWS": "arn:aws:boom:boom"
  }
}
```

这个 `CompositePrincipal` 类也可以用来定义复杂的主因,例如:

```ts
const role = new iam.Role(this, 'MyRole', {
  assumedBy: new iam.CompositePrincipal(
    new iam.ServicePrincipal('ec2.amazonaws.com'),
    new iam.AccountPrincipal('1818188181818187272')
  ),
});
```

这个 `PrincipalWithConditions` 类可用于添加条件到一个 校长,尤其是那些不拿 `conditions` 参数 建筑师。 这个 `principal.withConditions()` 方法可用于创建 `PrincipalWithConditions` 例如:

```ts
const principal = new iam.AccountPrincipal('123456789000')
  .withConditions({ StringEquals: { foo: "baz" } });
```

> 注:如果需要定义使用符号(例如: 在 JSON 映射密钥中, 使用 `CfnJson` 改为 做这个条件。 见 [此测试](https://npmcn.com/package/%40aws-cdk/aws-iam/test/integ.condition-with-ref.ts) 页:1 一个例子.

这个 `WebIdentityPrincipal` 类可以用作网络身份的特等,例如: 例如:

```ts
const principal = new iam.WebIdentityPrincipal('cognito-identity.amazonaws.com', {
  'StringEquals': { 'cognito-identity.amazonaws.com:aud': 'us-east-2:12345678-abcd-abcd-abcd-123456' },
  'ForAnyValue:StringLike': {'cognito-identity.amazonaws.com:amr': 'unauthenticated' },
});
```

如果您的身份提供者被配置为角色 [第二届会议 标记](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_session-tags.html),你吗 需要打电话 `.withSessionTags()` 在角色中添加所需的权限 政策文件:

```ts
new iam.Role(this, 'Role', {
  assumedBy: new iam.WebIdentityPrincipal('cognito-identity.amazonaws.com', {
    'StringEquals': {
      'cognito-identity.amazonaws.com:aud': 'us-east-2:12345678-abcd-abcd-abcd-123456',
     },
    'ForAnyValue:StringLike': {
      'cognito-identity.amazonaws.com:amr': 'unauthenticated',
    },
  }).withSessionTags(),
});
```

## 分析 JSON 政策文件

这个 `PolicyDocument.fromJson` 财务报告和审定财务报表 `PolicyStatement.fromJson` 静态方法可用于剖析JSON对象. 例如:

```ts
const policyDocument = {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "FirstStatement",
      "Effect": "Allow",
      "Action": ["iam:ChangePassword"],
      "Resource": "*"
    },
    {
      "Sid": "SecondStatement",
      "Effect": "Allow",
      "Action": "s3:ListAllMyBuckets",
      "Resource": "*"
    },
    {
      "Sid": "ThirdStatement",
      "Effect": "Allow",
      "Action": [
        "s3:List*",
        "s3:Get*"
      ],
      "Resource": [
        "arn:aws:s3:::confidential-data",
        "arn:aws:s3:::confidential-data/*"
      ],
      "Condition": {"Bool": {"aws:MultiFactorAuthPresent": "true"}}
    }
  ]
};

const customPolicyDocument = iam.PolicyDocument.fromJson(policyDocument);

// You can pass this document as an initial document to a ManagedPolicy
// or inline Policy.
const newManagedPolicy = new iam.ManagedPolicy(this, 'MyNewManagedPolicy', {
  document: customPolicyDocument,
});
const newPolicy = new iam.Policy(this, 'MyNewPolicy', {
  document: customPolicyDocument,
});
```

## 允许边界

[权限 边界](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) 可以通过创建新的 `Role`s. 许可边界是一项管理政策,附属于角色或 用户,代表 _上限_ 他们可以拥有的一系列权限。 这个 角色(或用户)的有效权限集将是 身份政策和与角色相关的权限边界 用户). 权限边界通常由账户创建 管理员及其在新创建中的用途 `Role`s 将由 IAM政策.

可以将权限边界附加到构造中创建的所有角色 一次全部树 :

```ts
// This imports an existing policy.
const boundary = iam.ManagedPolicy.fromManagedPolicyArn(this, 'Boundary', 'arn:aws:iam::123456789012:policy/boundary');

// This creates a new boundary
const boundary2 = new iam.ManagedPolicy(this, 'Boundary2', {
  statements: [
    new iam.PolicyStatement({
      effect: iam.Effect.DENY,
      actions: ['iam:*'],
      resources: ['*'],
    }),
  ],
});

// Directly apply the boundary to a Role you create
declare const role: iam.Role;
iam.PermissionsBoundary.of(role).apply(boundary);

// Apply the boundary to an Role that was implicitly created for you
declare const fn: lambda.Function;
iam.PermissionsBoundary.of(fn).apply(boundary);

// Apply the boundary to all Roles in a stack
iam.PermissionsBoundary.of(this).apply(boundary);

// Remove a Permissions Boundary that is inherited, for example from the Stack level
declare const customResource: CustomResource;
iam.PermissionsBoundary.of(customResource).clear();
```

## OpenID 连接供应商

OIDC 身份提供者是IAM中描述外部身份的实体 用于支持 [OpenID 连接](http://openid.net/connect) (OIDC)标准,例如 作为谷歌或销售力量。 您需要时使用 IAM OIDC 身份提供者 在 OIDC 兼容的 IdP 和您的 AWS 账户之间建立信任 。 这是 创建需要访问 AWS 的移动应用程序或网络应用程序时有用 资源,但您不想创建自定义的签名代码或管理自己的代码 用户身份。 关于这一设想的更多信息,请参见: [关于网络 身份联合会](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_oidc.html) 和报告中的有关文件 [亚马逊-科尼奥托 身份池开发者指南](https://docs.aws.amazon.com/cognito/latest/developerguide/open-id.html)。 。 。 .

以下示例定义了 OpenID 连接提供者. 两个客户身份 (观众)将能够向 [https://openid/连接](https://openid/connect)。 。 。 .

```ts
const provider = new iam.OpenIdConnectProvider(this, 'MyProvider', {
  url: 'https://openid/connect',
  clientIds: [ 'myclient1', 'myclient2' ],
});
```

您可以指定可选列表 `thumbprints`未指定时 将自动获得根证书权威( CA) 的拇指印 从主机如所述 [这里](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc_verify-thumbprint.html)。 。 。 .

一旦定义了 OpenID 连接提供者, 您可以用 AWS 服务使用 需要IAM OIDC的供应商。 例如,当您定义一个 [亚马逊 认知身份 组合](https://docs.aws.amazon.com/cognito/latest/developerguide/open-id.html) 您可以引用提供者的 ARN 如下:

```ts
import * as cognito from '@aws-cdk/aws-cognito';

declare const myProvider: iam.OpenIdConnectProvider;
new cognito.CfnIdentityPool(this, 'IdentityPool', {
  openIdConnectProviderArns: [myProvider.openIdConnectProviderArn],
  // And the other properties for your identity pool
  allowUnauthenticatedIdentities: false,
});
```

这个 `OpenIdConnectPrincipal` 类可用作主要用法 `OpenIdConnectProvider`,例如:

```ts
const provider = new iam.OpenIdConnectProvider(this, 'MyProvider', {
  url: 'https://openid/connect',
  clientIds: [ 'myclient1', 'myclient2' ],
});
const principal = new iam.OpenIdConnectPrincipal(provider);
```

## SAML 供应商

IAM SAML 2.0 身份提供商是IAM中描述外部实体 支持 SAML 2.0 (安全请求) 的身份提供商( IdP) 服务 Markup Language 2.0)标准. 您需要时使用 IAM 身份提供者 以建立 SAML 兼容的 IdP 如 Shibboleth 或 Active 之间的信任 Directory Federal Services and AWS,以便您的组织的用户可以 访问 AWS 资源。 IAM SAML 身份提供商在 IAM信托政策.

```ts
new iam.SamlProvider(this, 'Provider', {
  metadataDocument: iam.SamlMetadataDocument.fromFile('/path/to/saml-metadata-document.xml'),
});
```

这个 `SamlPrincipal` 类可用作本金,带有 `SamlProvider`数字 :

```ts
const provider = new iam.SamlProvider(this, 'Provider', {
  metadataDocument: iam.SamlMetadataDocument.fromFile('/path/to/saml-metadata-document.xml'),
});
const principal = new iam.SamlPrincipal(provider, {
  StringEquals: {
    'SAML:iss': 'issuer',
  },
});
```

当创建程序角色和 AWS 管理控制台访问时,使用 `SamlConsolePrincipal` 类 :

```ts
const provider = new iam.SamlProvider(this, 'Provider', {
  metadataDocument: iam.SamlMetadataDocument.fromFile('/path/to/saml-metadata-document.xml'),
});
new iam.Role(this, 'Role', {
  assumedBy: new iam.SamlConsolePrincipal(provider),
});
```

## 用户

IAM 管理您的 AWS 账户的用户 。 要创建新用户 :

```ts
const user = new iam.User(this, 'MyUser');
```

以名称导入已有用户 [有路径](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names)数字 :

```ts
const user = iam.User.fromUserName(this, 'MyImportedUserByName', 'johnsmith');
```

要通过 ARN 导入已有的用户 :

```ts
const user = iam.User.fromUserArn(this, 'MyImportedUserByArn', 'arn:aws:iam::123456789012:user/johnsmith');
```

要通过属性导入已有用户:

```ts
const user = iam.User.fromUserAttributes(this, 'MyImportedUserByAttributes', {
  userArn: 'arn:aws:iam::123456789012:user/johnsmith',
});
```

### 访问密钥

用户通过 CLI 或 SDK 进行 API 调用的能力,由有 访问密钥对 。 要创建访问密钥 :

```ts
const user = new iam.User(this, 'MyUser');
const accessKey = new iam.AccessKey(this, 'MyAccessKey', { user: user });
```

您可以通过提供单调递增来强制 CloudFormation 旋转访问密钥 `serial` 属性。 简单地提供比以前使用的任何数字更高的序列值:

```ts
const user = new iam.User(this, 'MyUser');
const accessKey = new iam.AccessKey(this, 'MyAccessKey', { user: user, serial: 1 });
```

一个访问密钥可能只与单一用户相关联,不能在用户之间"移动". 变化 与访问密钥相关的用户替换访问密钥(及其ID和秘密值).

## 组

一个IAM用户组是IAM用户的集合. 用户组允许您为多个用户指定权限.

```ts
const group = new iam.Group(this, 'MyGroup');
```

要通过 ARN 导入一个已存在的组 :

```ts
const group = iam.Group.fromGroupArn(this, 'MyImportedGroupByArn', 'arn:aws:iam::account-id:group/group-name');
```

按名称导入已存在的组 [有路径](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-friendly-names)数字 :

```ts
const group = iam.Group.fromGroupName(this, 'MyImportedGroupByName', 'group-name');
```

要将一个用户添加到一个组( 既针对新用户, 也针对导入用户/ 组) :

```ts
const user = new iam.User(this, 'MyUser'); // or User.fromUserName(stack, 'User', 'johnsmith');
const group = new iam.Group(this, 'MyGroup'); // or Group.fromGroupArn(stack, 'Group', 'arn:aws:iam::account-id:group/group-name');

user.addToGroup(group);
// or
group.addUser(user);
```

## 特征

-   政策名称独有性得到强制执行。 如果将两个同名政策附在同一个上 校长,附件将失败.
-   不需要政策名称 - 将使用和确保 CDK 逻辑ID 以独有性.
-   政策在综合过程中得到验证,以确保其有行动,并确保政策 附属于机构间委员会负责人的指定相关资源,而附属于资源的政策 具体说明它们适用于哪一种IMA原则.

## 常见问题

### @aws-cdk/aws-iam 是什么？

易于分配正确和最小IAM权限的 CDK 常规注意：该包已被作者标记为弃用——AWS CDK v1 has reached End-of-Support on 2023-06-01\. This package is no longer being updated, and users should migrate to AWS CDK v2\. For more information on how to migrate, see https://docs\.aws\.amazon\.com/cdk/v2/guide/migrating-v2\.html

### 如何安装 @aws-cdk/aws-iam？

在项目目录运行 npm install @aws-cdk/aws-iam，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@aws-cdk/core（1\.204\.0）、@aws-cdk/region-info（1\.204\.0）、constructs（^3\.3\.69）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws-cdk/aws-iam 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws-cdk/aws-iam 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws-cdk/aws-iam 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>= 14\.15\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @aws-cdk/aws-iam 可以商用吗？

@aws-cdk/aws-iam 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-cdk/aws-iam 的下载量有多少？

根据 npm 官方下载统计，@aws-cdk/aws-iam 在 2026/10/08 – 2026/11/06 这 30 天内被下载 483,326 次，日均约 16,111 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws-cdk/aws-iam 还在维护吗？

最新版本 1\.204\.0 发布于 2023/06/20（3 年前）；至今共发布 288 个版本，其中过去 12 个月发布了 0 个；首次发布于 2018/07/31。作者已将其标记为弃用，新项目建议寻找替代方案。