{"id":24458631,"url":"https://github.com/blimmer/cdk-github-oidc","last_synced_at":"2025-05-05T21:41:26.480Z","repository":{"id":273412804,"uuid":"919628491","full_name":"blimmer/cdk-github-oidc","owner":"blimmer","description":"AWS CDK construct to create OIDC roles for GitHub Actions","archived":false,"fork":false,"pushed_at":"2025-04-01T00:32:35.000Z","size":534,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-16T04:24:35.298Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blimmer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-20T18:35:29.000Z","updated_at":"2025-04-01T00:32:38.000Z","dependencies_parsed_at":"2025-01-20T19:34:16.074Z","dependency_job_id":"1e118456-91b7-44e2-8098-ed4cb6d29b9e","html_url":"https://github.com/blimmer/cdk-github-oidc","commit_stats":null,"previous_names":["blimmer/cdk-github-oidc"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blimmer%2Fcdk-github-oidc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blimmer%2Fcdk-github-oidc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blimmer%2Fcdk-github-oidc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blimmer%2Fcdk-github-oidc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blimmer","download_url":"https://codeload.github.com/blimmer/cdk-github-oidc/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252581847,"owners_count":21771579,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-21T03:15:20.742Z","updated_at":"2025-05-05T21:41:26.442Z","avatar_url":"https://github.com/blimmer.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `@blimmer/cdk-github-oidc`\n\nA CDK construct library that enables secure authentication between GitHub Actions and AWS using OpenID Connect (OIDC).\nThis eliminates the need for long-lived AWS credentials in your GitHub repositories.\n\n## What is OIDC?\n\nOIDC (OpenID Connect) allows GitHub Actions to authenticate directly with AWS using short-lived tokens instead of\nstoring AWS credentials. The process is described in\n[GitHub's documentation](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect).\n\n## Security Benefits\n\nUsing OIDC for GitHub Actions authentication:\n\n- Eliminates the need to store AWS credentials as GitHub secrets\n- Provides short-lived, automatically rotated credentials\n- Enables fine-grained access control based on repository, branch, environment, or other conditions\n- Follows security best practices for cloud access\n\n## Installation\n\n### Node.js\n\n```shell\nnpm install --save @blimmer/cdk-github-oidc\n```\n\nor\n\n```shell\nyarn add @blimmer/cdk-github-oidc\n```\n\n### Python\n\n```bash\npip install cdk-github-oidc\n```\n\nFor Python, see [below](#python).\n\n### Create or Import a Provider\n\nEach AWS account must be bootstrapped with a single OIDC provider.\n\nTo create it in your stack, use the `GithubActionsIdentityProvider` construct.\n\n```ts\nimport { GithubActionsIdentityProvider } from \"@blimmer/cdk-github-oidc\";\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string, props: StackProps) {\n    super(scope, id, props);\n\n    const provider = new GithubActionsIdentityProvider(this, \"Provider\");\n  }\n}\n```\n\nOr, if another stack created the provider, you can import it using the `GithubActionsIdentityProvider.fromAccount()`\nmethod.\n\n```ts\nimport { GithubActionsIdentityProvider } from \"@blimmer/cdk-github-oidc\";\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string, props: StackProps) {\n    super(scope, id, props);\n\n    const provider = GithubActionsIdentityProvider.fromAccount(this);\n  }\n}\n```\n\n### Create a Role\n\nOnce you have a handle to a provider, you can create a role assumed by GitHub Actions. You grant this role permission to\naccess the resources/APIs you need (more on that [below](#granting-permissions-to-the-role)).\n\n```ts\nimport { GithubActionsRole, GithubActionsIdentityProvider, BranchFilter } from \"@blimmer/cdk-github-oidc\";\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string, props: StackProps) {\n    super(scope, id, props);\n\n    const provider = new GithubActionsIdentityProvider(this, \"Provider\");\n\n    const role = new GithubActionsRole(this, \"Role\", {\n      provider,\n      roleName: \"my-github-actions-role\",\n      description: \"Role assumed by GitHub Actions\",\n      subjectFilters: [new BranchFilter({ owner: \"blimmer\", repository: \"cdk-github-oidc\", branch: \"*\" })],\n    });\n  }\n}\n```\n\n### Subject Filters\n\nYou must pass one or more `SubjectFilter`s to the `GithubActionsRole` construct. These filters are used to determine\nwhich GitHub Actions workflows can assume the role.\n\nThis construct exposes first class support for the following filters:\n\n- [`AllowAllFilter`](/API.md#allowallfilter)\n\n  ```ts\n  // Allow all branches, tags, environments, pull requests, etc.\n  new AllowAllFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n  });\n  ```\n\n- [`BranchFilter`](/API.md#branchfilter)\n\n  ```ts\n  // Allow all branches\n  new BranchFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    branch: \"*\",\n  });\n\n  // Specify a branch\n  new BranchFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    branch: \"main\",\n  });\n\n  // Specify a branch pattern\n  new BranchFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    branch: \"feature/*\",\n  });\n  ```\n\n- [`TagFilter`](/API.md#tagfilter)\n\n  ```ts\n  // Allow all tags\n  new TagFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    tag: \"*\",\n  });\n\n  // Specify a tag\n  new TagFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    tag: \"v1.0.0\",\n  });\n\n  // Specify a tag pattern\n  new TagFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    tag: \"v1.*\",\n  });\n  ```\n\n- [`EnvironmentFilter`](/API.md#environmentfilter)\n\n  ```ts\n  // Allow all environments\n  new EnvironmentFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    environment: \"*\",\n  });\n\n  // Specify an environment\n  new EnvironmentFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n    environment: \"staging\",\n  });\n  ```\n\n- [`PullRequestFilter`](/API.md#pullrequestfilter)\n\n  ```ts\n  // Allow all pull requests\n  new PullRequestFilter({\n    owner: \"blimmer\",\n    repository: \"cdk-github-oidc\",\n  });\n  ```\n\nIf none of these filters fit your use case, you can implement your own via the\n[`IGithubActionOidcFilter`](/API.md#igithubactionoidcfilter) interface, or use the\n[`CustomFilter`](/API.md#customfilter) construct.\n\nYou can learn more about subject filters in the\n[Github docs](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#configuring-the-subject-in-your-cloud-provider)\n\n### Granting Permissions to the Role\n\nThe `GithubActionsRole` construct _is a_ `Role` construct, so you can use all of the same properties and methods as you\nwould with a normal\n[CDK IAM `Role` construct](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html).\n\n```ts\nimport { GithubActionsRole, GithubActionsIdentityProvider, BranchFilter } from \"@blimmer/cdk-github-oidc\";\nimport { Bucket } from \"aws-cdk-lib/aws-s3\";\nimport { PolicyStatement } from \"aws-cdk-lib/aws-iam\";\n\nexport class MyStack extends Stack {\n  constructor(scope: Construct, id: string, props: StackProps) {\n    super(scope, id, props);\n\n    const bucket = new Bucket(this, \"Bucket\");\n\n    const provider = new GithubActionsIdentityProvider(this, \"Provider\");\n    const role = new GithubActionsRole(this, \"Role\", {\n      provider,\n      roleName: \"my-github-actions-role\",\n      description: \"Role assumed by GitHub Actions\",\n      subjectFilters: [\n        new BranchFilter({\n          owner: \"blimmer\",\n          repository: \"cdk-github-oidc\",\n          branch: \"*\",\n        }),\n      ],\n    });\n\n    // Grant access via CDK `grant*` methods\n    // https://docs.aws.amazon.com/cdk/v2/guide/permissions.html#permissions_grants\n    role.grantReadWrite(bucket);\n\n    // Add a custom policy\n    role.addToPolicy(\n      new PolicyStatement({\n        actions: [\"s3:PutObject\"],\n        resources: [\"arn:aws:s3:::my-bucket/*\"],\n      }),\n    );\n  }\n}\n```\n\n### Using a Role in a Workflow\n\nTo use a role in a GitHub Actions workflow, you can use the `aws-actions/configure-aws-credentials` action.\n\n```yaml\njobs:\n  deploy:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      id-token: write # Required for OIDC role assumption\n    steps:\n      - name: Configure AWS Credentials\n        uses: aws-actions/configure-aws-credentials@v4\n        with:\n          role-to-assume: arn:aws:iam::123456789012:role/my-github-actions-role\n          region: us-west-2\n```\n\nSee [the `aws-actions/configure-aws-credentials` docs](https://github.com/aws-actions/configure-aws-credentials) for\nmore details.\n\n## Usage\n\nFor detailed API docs, see [API.md](/API.md).\n\n## Troubleshooting\n\n### Common Issues\n\n1. **Role assumption fails**: Ensure your GitHub Action has the required permissions:\n\n```yaml\npermissions:\n  id-token: write # Required for OIDC\n  contents: read # Required for checking out code\n```\n\n1. **Provider already exists**: Only one OIDC provider can exist per AWS account. Use\n   `GithubActionsIdentityProvider.fromAccount()` if one already exists.\n\n1. **Subject filter not matching**: Double check your subject filter configuration matches your GitHub workflow context.\n   Use logging to debug the actual subject string being provided.\n\n## Migrating from `aws-cdk-github-oidc`\n\nThis package was inspired by [`aws-cdk-github-oidc`](https://github.com/aripalo/aws-cdk-github-oidc), but that package\nbecame unmaintained.\n\nFor a role that looked like this in `aws-cdk-github-oidc`:\n\n```ts\nimport { GithubActionsIdentityProvider, GithubActionsRole } from \"aws-cdk-github-oidc\";\n\nconst provider = new GithubActionsIdentityProvider(scope, \"GithubProvider\");\nconst deployRole = new GithubActionsRole(scope, \"DeployRole\", {\n  provider,\n  owner: \"octo-org\",\n  repo: \"octo-repo\",\n  roleName: \"MyDeployRole\",\n  description: \"This role deploys stuff to AWS\",\n  maxSessionDuration: cdk.Duration.hours(2),\n});\n```\n\nThe equivalent role in this package looks like this:\n\n```ts\nimport { GithubActionsIdentityProvider, GithubActionsRole, AllowAllFilter } from \"@blimmer/cdk-github-oidc\";\n\nconst provider = new GithubActionsIdentityProvider(scope, \"GithubProvider\");\nconst deployRole = new GithubActionsRole(scope, \"DeployRole\", {\n  provider,\n  roleName: \"MyDeployRole\",\n  description: \"This role deploys stuff to AWS\",\n  subjectFilters: [\n    // I encourage you to scope this down to a different filter (e.g., BranchFilter, TagFilter, PullRequestFilter, etc.)\n    new AllowAllFilter({ owner: \"octo-org\", repository: \"octo-repo\" }),\n  ],\n  maxSessionDuration: cdk.Duration.hours(2),\n});\n```\n\n### Resource Replacement\n\nBy default, CloudFormation will create resources before destroying the old ones. This is a problem when transitioning\nbetween `aws-cdk-github-oidc` and `@blimmer/cdk-github-oidc` because the `GithubActionsIdentityProvider` is a singleton.\nIt might also affect your roles, if you specified a `roleName`.\n\nTo work around this issue, delete the old provider and role(s) before migrating to use this package. Note that this will\nmake the role unavailable for a few minutes while things are recreated\n\n## Resources\n\n- [Security hardening your deployments](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments)\n  on Github Docs.\n- [Assuming a role with `aws-actions/configure-aws-credentials`](https://github.com/aws-actions/configure-aws-credentials#assuming-a-role)\n\n## Contributing\n\nContributions, issues, and feedback are welcome!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblimmer%2Fcdk-github-oidc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblimmer%2Fcdk-github-oidc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblimmer%2Fcdk-github-oidc/lists"}