diff --git a/.github/workflows/production.yml b/.github/workflows/production.yml index 5e80e9d..a7a683c 100644 --- a/.github/workflows/production.yml +++ b/.github/workflows/production.yml @@ -13,7 +13,6 @@ jobs: runs-on: ubuntu-latest permissions: id-token: write - statuses: write contents: read environment: production diff --git a/README.md b/README.md index 0110bc5..b019f30 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Configure AWS Credentials by Assuming Roles +The action configures AWS Credential by assuming roles and [OpenID Connect (OIDC)](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). + ## Usage At first, create an IAM role for your repository. @@ -28,11 +30,22 @@ The role's trust policy must allow an AWS account `053160724612` to assume the r And then, add the following step to your workflow: ```yaml -- name: Configure AWS Credentials - uses: fuller-inc/actions-aws-assume-role@v1 - with: - aws-region: us-east-2 - role-to-assume: arn:aws:iam::123456789012:role/GitHubRepoRole-us-east-2 +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + id-token: write # needed to interact with GitHub's OIDC Token endpoint. + contents: read + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Configure AWS Credentials + uses: fuller-inc/actions-aws-assume-role@v1 + with: + aws-region: us-east-2 + role-to-assume: arn:aws:iam::123456789012:role/GitHubRepoRole-us-east-2 ``` ### Session tagging @@ -49,15 +62,18 @@ You can enable session tagging by adding `role-session-tagging: true`. The session will have the name "GitHubActions" and be tagged with the following tags: -| Key | Value | -| ---------- | ------------------- | -| GitHub | "Actions" | -| Repository | `GITHUB_REPOSITORY` | -| Workflow | `GITHUB_WORKFLOW` | -| RunId | `GITHUB_RUN_ID` | -| Actor | `GITHUB_ACTOR` | -| Branch | `GITHUB_REF` | -| Commit | `GITHUB_SHA` | +| Key | Value | +| ----------- | ----------------------------- | +| GitHub | "Actions" | +| Repository | `GITHUB_REPOSITORY` | +| Workflow | `GITHUB_WORKFLOW` | +| RunId | `GITHUB_RUN_ID` | +| Actor | `GITHUB_ACTOR` | +| Branch | `GITHUB_REF` | +| Commit | `GITHUB_SHA` | +| Audience | `aud` of the ID token | +| Subject | `sub` of the ID token | +| Environment | `environment` of the ID token | _Note: all tag values must conform to [the requirements](https://docs.aws.amazon.com/STS/latest/APIReference/API_Tag.html). Particularly, `GITHUB_WORKFLOW` will be truncated if it's too long. If `GITHUB_ACTOR` or `GITHUB_WORKFLOW` contain invalid characters, the characters will be replaced with an '\_'._ @@ -200,56 +216,14 @@ See [Migrating GraphQL global node IDs](https://docs.github.com/en/graphql/guide and [GraphQL global ID migration update](https://github.blog/2021-11-16-graphql-global-id-migration-update/) for more detail. -## About security hardening with OpenID Connect - -The action also supports [OpenID Connect (OIDC)](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect). - -- Additional session tags "Audience" and "Subject" are available -- All session tags are signed by GitHub OIDC Provider. You can use them in the `Condition` element in your IAM JSON policy - -Example workflow: - -```yaml -jobs: - deploy: - runs-on: ubuntu-latest - # These permissions are needed to interact with GitHub's OIDC Token endpoint. - permissions: - id-token: write - statuses: write - contents: read - - steps: - - name: Checkout - uses: actions/checkout@v4 - - - uses: fuller-inc/actions-aws-assume-role@v1 - with: - aws-region: us-east-2 - role-to-assume: arn:aws:iam::123456789012:role/GitHubRepoRole-us-east-2 -``` - -| Key | Value | -| ----------- | -------------------------- | -| Audience | `aud` of the token | -| Subject | `sub` of the token | -| Environment | `environment` of the token | -| GitHub | "Actions" | -| Repository | `GITHUB_REPOSITORY` | -| Workflow | `GITHUB_WORKFLOW` | -| RunId | `GITHUB_RUN_ID` | -| Actor | `GITHUB_ACTOR` | -| Branch | `GITHUB_REF` | -| Commit | `GITHUB_SHA` | - ## How to Work ![How to Work](how-to-work.svg) 1. Request a new credential\ - The fuller-inc/actions-aws-assume-role action sends the `GITHUB_TOKEN` and requests a new credential to the credential provider. It works on AWS Lambda owned by @fuller-inc. + The `fuller-inc/actions-aws-assume-role` action sends an ID token of OpenID connect to the credential provider. The credential provider works on AWS Lambda owned by @fuller-inc. 2. Check Permission of GitHub Repository\ - The Lambda function checks the permission of the repository. `GITHUB_TOKEN` must have the write permission of the repository and be generated by GitHub Action bot. + The Lambda function validates the ID token. 3. Request AssumeRole to an IAM Role on your AWS account 4. Check Permission of the IAM Role\ The AWS IAM Service checks the role's trust policy.