@blimmer/cdk-github-oidc

一个 CDK 构建库,可以使用 OpenID Connection(OIDC) 在 GitHub Actions 和 AWS 之间安全认证. 这就不再需要在您的 GitHub 寄存器中长期使用 AWS 证书 .

什么是OIDC吗?

OIDC( OpenID Connect) 允许 GitHub 动作使用短寿命的符号直接认证 AWS 而不是 存储 AWS 证书 。 这一过程在下文中作了描述 GitHub 文档。 。 。 .

安装

节点.js

npm install --save @blimmer/cdk-github-oidc

或者说

yarn add @blimmer/cdk-github-oidc

蟒

pip install cdk-github-oidc

使用量

下面的例子为TypeScript. 关于每种支持语言的完整API,请参见 API.md (英语)。 。 。 .

创建或导入提供者

每个AWS账户都必须由单一的OIDC提供商来固定.

要在您的堆栈中创建,请使用 GithubActionsIdentityProvider 构造.

import { GithubActionsIdentityProvider } from "@blimmer/cdk-github-oidc";

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps) {
    super(scope, id, props);

    const provider = new GithubActionsIdentityProvider(this, "Provider");
  }
}

或者,如果另一个堆栈创建了提供者,你可以使用 GithubActionsIdentityProvider.fromAccount() 方法.

import { GithubActionsIdentityProvider } from "@blimmer/cdk-github-oidc";

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps) {
    super(scope, id, props);

    const provider = GithubActionsIdentityProvider.fromAccount(this);
  }
}

创建角色

一旦向提供者拥有了手柄,就可以创建由GitHub Actions承担的角色. 您给予此角色权限 访问资源/ AP 您需要( 更多信息) 下级) (中文(简体) ).

import { GithubActionsRole, GithubActionsIdentityProvider, BranchFilter } from "@blimmer/cdk-github-oidc";

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps) {
    super(scope, id, props);

    const provider = new GithubActionsIdentityProvider(this, "Provider");

    const role = new GithubActionsRole(this, "Role", {
      provider,
      roleName: "my-github-actions-role",
      description: "Role assumed by GitHub Actions",
      subjectFilters: [
        new BranchFilter({
          owner: "blimmer",
          ownerId: "630449",
          repository: "cdk-github-oidc",
          repositoryId: "919628491",
          branch: "*",
        }),
      ],
    });
  }
}

ownerId 财务报告和审定财务报表 repositoryId 选择使用 GitHub a. 不可改变的主题索赔,默认值为 2026年7月15日之后创建的寄存器. 如果你的寄存器早于此,就同时关闭.

主题过滤器

你必须经过一个或一个以上 SubjectFilter页:1 GithubActionsRole 构造。 这些过滤器用于确定 gitHub 动作工作流程可以承担该角色.

此构造会曝光以下过滤器的一等支持. 实例省略 ownerId 财务报告和审定财务报表 repositoryId 改为 将焦点放在每个过滤器的操作上;如果您的存储器使用不可改变的主题要求,则如上所示添加.

• AllowAllFilter

  // Allow all branches, tags, environments, pull requests, etc.
  new AllowAllFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
  });
  

• BranchFilter

  // Allow all branches
  new BranchFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    branch: "*",
  });
  
  // Specify a branch
  new BranchFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    branch: "main",
  });
  
  // Specify a branch pattern
  new BranchFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    branch: "feature/*",
  });
  

• TagFilter

  // Allow all tags
  new TagFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    tag: "*",
  });
  
  // Specify a tag
  new TagFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    tag: "v1.0.0",
  });
  
  // Specify a tag pattern
  new TagFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    tag: "v1.*",
  });
  

• EnvironmentFilter

  // Allow all environments
  new EnvironmentFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    environment: "*",
  });
  
  // Specify an environment
  new EnvironmentFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
    environment: "staging",
  });
  

• PullRequestFilter

  // Allow all pull requests
  new PullRequestFilter({
    owner: "blimmer",
    repository: "cdk-github-oidc",
  });
  

如果这些过滤器都不符合您的使用大小写, 您可以通过 IGithubActionOidcFilter 接口,或使用 CustomFilter 构造.

在写自己的作品时, 从受保护对象中构建主题 repositoryClaim 比从 owner 财务报告和审定财务报表 repository 直接说 随你怎么说 repo: 前缀过滤器被配置,所以您的过滤器继续工作 如果寄存器移动到 a. 不可改变的主题索赔。 。 。 .

class DeploymentFilter extends IGithubActionOidcFilter {
  public toSubject(): string {
    return `${this.repositoryClaim}:deployment`;
  }
}

您可以在 Github 文档

B. 无法更改的主题索赔

GitHub 移动到一个 c. 不可改变的主题索赔格式 嵌入数字所有者和寄存器ID:

repo:blimmer/cdk-github-oidc:ref:refs/heads/main                   # previous
repo:blimmer@630449/cdk-github-oidc@919628491:ref:refs/heads/main  # immutable

2026年7月15日之后创建的仓库使用不可改变的格式,在此之后重新命名或转移的仓库也是如此 约会。 在 OIDC 设置 UI 或 NOG 中,所有其它文件都保留上一个格式,直到您选择使用 (原始内容存档于2013-10-12) (英语). REST API。一个寄存器会发出一种或另一种格式,永远不会同时发出两种格式.

过 ownerId 财务报告和审定财务报表 repositoryId 到任何获取永久格式的过滤器 :

new BranchFilter({
  owner: "blimmer",
  ownerId: "630449",
  repository: "cdk-github-oidc",
  repositoryId: "919628491",
  branch: "main",
});

离开他们,你得到之前的格式,这就是什么 主题过滤器 上面的例子.

找到身份证

gh api repos/OWNER/REPO --jq '{ownerId: .owner.id, repositoryId: .id}'

要检查寄存器的当前格式, 请读 sub_claim_prefix数字 :

gh api repos/OWNER/REPO/actions/oidc/customization/sub
# {"use_default":true,"use_immutable_subject":false,"sub_claim_prefix":"repo:blimmer/cdk-github-oidc"}

同样的环境生活 https://github.com/OWNER/REPO/settings/actions/oidc-configuration。 。 。 .

快速迁移

如果你有不止几个过滤器 把这个交给你的编码代理.

Upgrade `@blimmer/cdk-github-oidc` to the latest version, then audit this CDK app for GitHub's immutable OIDC
subject claim format.

Background: GitHub embeds numeric owner and repository IDs in the OIDC `sub` claim
(`repo:owner@123/repo@456:ref:refs/heads/main` instead of `repo:owner/repo:ref:refs/heads/main`). Repositories
created, renamed, or transferred after July 15, 2026 use it automatically. Older repositories keep the previous
format until someone opts in. A repository emits one format or the other, never both, so a trust policy built for
the wrong format fails with `Not authorized to perform sts:AssumeRoleWithWebIdentity`.

For every subject filter passed to a `GithubActionsRole` in this app:

1. Run `gh api repos/<owner>/<repository>/actions/oidc/customization/sub` and read `use_immutable_subject`.
2. If it is `false`, leave the filter alone. It is already correct.
3. If it is `true`, run `gh api repos/<owner>/<repository> --jq '{ownerId: .owner.id, repositoryId: .id}'` and add
   both values to that filter as `ownerId` and `repositoryId` (strings, not numbers). Keep `owner` and
   `repository` as the plain names.

Then find every class in this app that extends `IGithubActionOidcFilter`. If its `toSubject()` builds the subject
from `this.owner` and `this.repository`, rewrite it to use the `this.repositoryClaim` getter instead, leaving the
rest of the subject unchanged. Custom filters that skip this keep emitting the previous format no matter which IDs
are passed to them.

Report any repository the `gh` calls fail for rather than guessing its IDs, since a wrong ID produces a role nobody
can assume. Do not add, remove, or re-scope any filter, and do not change anything beyond the filter arguments and
the custom filter subject construction.

切换现有仓库

添加第二个带ID的过滤器,部署,选择在GitHub上,然后删除原来的过滤器. 这个角色都相信 中间的主体,所以没有突破中关节.

subjectFilters: [
  new BranchFilter({ owner: "blimmer", repository: "cdk-github-oidc", branch: "main" }),
  new BranchFilter({
    owner: "blimmer",
    ownerId: "630449",
    repository: "cdk-github-oidc",
    repositoryId: "919628491",
    branch: "main",
  }),
];

双重检查身份证 一个错误的产生一个 永远不匹配的主题, 唯一的症状是 Not authorized to perform sts:AssumeRoleWithWebIdentity。 。 。 .

别拿通配符 blimmer@* 避免寻找他们。 相信每个账户的名字 blimmer, (中文(简体) ), 包括当当前所有者重取名称或删除名称时声称名称的人。 确切的防止,这就是为什么身份证 已存在.

授予角色权限

这个 GithubActionsRole 构造 是一个 Role 构造,这样您就可以使用与您相同的所有属性和方法 {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}会是正常的 光盘IAM Role 构造。 。 。 .

import { GithubActionsRole, GithubActionsIdentityProvider, BranchFilter } from "@blimmer/cdk-github-oidc";
import { Bucket } from "aws-cdk-lib/aws-s3";
import { PolicyStatement } from "aws-cdk-lib/aws-iam";

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps) {
    super(scope, id, props);

    const bucket = new Bucket(this, "Bucket");

    const provider = new GithubActionsIdentityProvider(this, "Provider");
    const role = new GithubActionsRole(this, "Role", {
      provider,
      roleName: "my-github-actions-role",
      description: "Role assumed by GitHub Actions",
      subjectFilters: [
        new BranchFilter({
          owner: "blimmer",
          repository: "cdk-github-oidc",
          branch: "*",
        }),
      ],
    });

    // Grant access via CDK `grant*` methods
    // https://docs.aws.amazon.com/cdk/v2/guide/permissions.html#permissions_grants
    role.grantReadWrite(bucket);

    // Add a custom policy
    role.addToPolicy(
      new PolicyStatement({
        actions: ["s3:PutObject"],
        resources: ["arn:aws:s3:::my-bucket/*"],
      }),
    );
  }
}

在工作流程中发挥作用

要使用 GitHub 动作工作流程中的角色, 您可以使用 aws-actions/configure-aws-credentials 行动.

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write # Required for OIDC role assumption
    steps:
      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role
          region: us-west-2

见 页:1 aws-actions/configure-aws-credentials 文档 页:1 更多细节.

解决问题

共同问题

1. 角色假设失败: 确保您的 GitHub 动作具有所需的权限 :

   permissions:
     id-token: write # Required for OIDC
     contents: read # Required for checking out code
   

2. 提供者已经存在:每个AWS账户只有一个OIDC供应商可以存在. 使用 GithubActionsIdentityProvider.fromAccount() 如果一个已经存在.

3. 主体过滤器不匹配: 双向检查您的主题过滤器配置符合您的 GitHub 工作流程上下文 . 使用日志调试提供的实际主题字符串 .

4. 创建、重新命名或转让后角色假设中断: 仓库可能已切换到 a. 不可改变的主题索赔运行 gh api repos/OWNER/REPO/actions/oidc/customization/sub 以查看其发射和通过的格式 ownerId 财务报告和审定财务报表 repositoryId 到过滤器,如果 use_immutable_subject 实值 true. CloudTrail)展示了实际呈现的主题.

从 aws-cdk-github-oidc

这个软件包灵感来自 aws-cdk-github-oidc软件包 变得无法保存.

为了这个角色 aws-cdk-github-oidc数字 :

import { GithubActionsIdentityProvider, GithubActionsRole } from "aws-cdk-github-oidc";

const provider = new GithubActionsIdentityProvider(scope, "GithubProvider");
const deployRole = new GithubActionsRole(scope, "DeployRole", {
  provider,
  owner: "octo-org",
  repo: "octo-repo",
  roleName: "MyDeployRole",
  description: "This role deploys stuff to AWS",
  maxSessionDuration: cdk.Duration.hours(2),
});

本套件中的等同角色看起来是这样的:

import { GithubActionsIdentityProvider, GithubActionsRole, AllowAllFilter } from "@blimmer/cdk-github-oidc";

const provider = new GithubActionsIdentityProvider(scope, "GithubProvider");
const deployRole = new GithubActionsRole(scope, "DeployRole", {
  provider,
  roleName: "MyDeployRole",
  description: "This role deploys stuff to AWS",
  subjectFilters: [
    // I encourage you to scope this down to a different filter (e.g., BranchFilter, TagFilter, PullRequestFilter, etc.)
    new AllowAllFilter({ owner: "octo-org", repository: "octo-repo" }),
  ],
  maxSessionDuration: cdk.Duration.hours(2),
});

资源更换

默认情况下,CloudFormation将会在摧毁旧的之前创造资源. 这是过渡时的问题 介于 aws-cdk-github-oidc 财务报告和审定财务报表 @blimmer/cdk-github-oidc 因为 GithubActionsIdentityProvider 是一个单子. 如果你指定一个 roleName。 。 。 .

要围绕这个问题开展工作,在迁移到使用这个包之前,删除旧的提供者和角色. 注意,这将 使角色在重建时无法使用几分钟

资源

• 安全加强你的部署 在Github Docs号上.
• 承担角色 aws-actions/configure-aws-credentials

捐款

欢迎贡献、问题和反馈!