Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

feat: added OIDC #262

Merged
merged 7 commits into from
Sep 28, 2021
Merged

feat: added OIDC #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
5e4f686
feat: OIDC provider (with PR comments)
Sep 18, 2021
74ed23c
chore: Bump jest from 27.2.1 to 27.2.2 (#267)
dependabot[bot] Sep 28, 2021
207a070
chore: Bump ansi-regex from 5.0.0 to 5.0.1 (#269)
dependabot[bot] Sep 28, 2021
88e36ed
chore: Bump aws-sdk from 2.991.0 to 2.996.0 (#268)
dependabot[bot] Sep 28, 2021
ef6880f
chore: Update dist
Sep 28, 2021
8d77d75
feat: OIDC provider (with PR comments)
Sep 18, 2021
8c9da02
Merge remote-tracking branch 'origin/master'
Sep 28, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 81 additions & 57 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,8 @@ Configure AWS credential and region environment variables for use in other GitHu
- [Usage](#usage)
- [Credentials](#credentials)
- [Assuming a Role](#assuming-a-role)
+ [Permissions for assuming a role](#permissions-for-assuming-a-role)
+ [Session tagging](#session-tagging)
+ [Sample IAM Role Permissions](#sample-iam-role-cloudformation-template)
- [Self-Hosted Runners](#self-hosted-runners)
- [License Summary](#license-summary)
- [Security Disclosures](#security-disclosures)
Expand All @@ -25,9 +25,7 @@ Add the following step to your workflow:
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
# aws-session-token: ${{ secrets.AWS_SESSION_TOKEN }} # if you have/need it
role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role
aws-region: us-east-2
```

Expand All @@ -47,8 +45,7 @@ jobs:
- name: Configure AWS credentials from Test account
uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.TEST_AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.TEST_AWS_SECRET_ACCESS_KEY }}
role-to-assume: arn:aws:iam::111111111111:role/my-github-actions-role-test
aws-region: us-east-1

- name: Copy files to the test website with the AWS CLI
Expand All @@ -58,8 +55,7 @@ jobs:
- name: Configure AWS credentials from Production account
uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.PROD_AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.PROD_AWS_SECRET_ACCESS_KEY }}
role-to-assume: arn:aws:iam::222222222222:role/my-github-actions-role-prod
aws-region: us-west-2

- name: Copy files to the production website with the AWS CLI
Expand All @@ -72,19 +68,39 @@ See [action.yml](action.yml) for the full documentation for this action's inputs
## Credentials

We recommend following [Amazon IAM best practices](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html) for the AWS credentials used in GitHub Actions workflows, including:
* Do not store credentials in your repository's code. You may use [GitHub Actions secrets](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets) to store credentials and redact credentials from GitHub Actions workflow logs.
* [Create an individual IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#create-iam-users) with an access key for use in GitHub Actions workflows, preferably one per repository. Do not use the AWS account root user access key.
* Do not store credentials in your repository's code.
* [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege) to the credentials used in GitHub Actions workflows. Grant only the permissions required to perform the actions in your GitHub Actions workflows.
* [Rotate the credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#rotate-credentials) used in GitHub Actions workflows regularly.
* [Monitor the activity](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#keep-a-log) of the credentials used in GitHub Actions workflows.

## Assuming a Role
If you would like to use the static credentials you provide to this action to assume a role, you can do so by specifying the role ARN in `role-to-assume`.
The role credentials will then be configured in the Actions environment instead of the static credentials you have provided.
The default session duration is 6 hours, but if you would like to adjust this you can pass a duration to `role-duration-seconds`.
We recommend using GitHub's OIDC provider to get short-lived credentials needed for your actions.
Specifying `role-to-assume` without providing an `aws-access-key-id` or a `web-identity-token-file` will signal to the action that you wish to use the OIDC provider.
The default session duration is 1 hour when using the OIDC provider to directly assume an IAM Role.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I may be misunderstanding this documentation, but it doesn't look like this logic was implemented in the PR and the default is still using MAX_ACTION_RUNTIME regardless of method. I think 3600 seconds is the default on new roles and that would mean we'd need to set role-duration-seconds on every use of the plugin or change the maximum session duration on our roles. I like the 1 hour default if using OIDC.

I'm really excited for this to land and it's been working great in testing.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was a really good catch! Thank you! I'm fixing it now. It'll default to 3600 for GH OIDC provider Roles and remain 6hrs (for backwards compatibility reasons) for the rest.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That sounds perfect, thanks!

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed, and I updated the test to validate it.

The default session duration is 6 hours when using an IAM User to assume an IAM Role (by providing an `aws-access-key-id`, `aws-secret-access-key`, and a `role-to-assume`) .
If you would like to adjust this you can pass a duration to `role-duration-seconds`, but the duration cannot exceed the maximum that was defined when the IAM Role was created.
The default session name is GitHubActions, and you can modify it by specifying the desired name in `role-session-name`.

Example:
The following table describes which identity is used based on which values are supplied to the Action:

| **Identity Used** | `aws-access-key-id` | `role-to-assume` | `web-identity-token-file` |
|------------------------------------------------------------------|---------------------|------------------|---------------------------|
| [✅ Recommended] Assume Role directly using GitHub OIDC provider | | ✔ | |
| IAM User | ✔ | | |
| Assume Role using IAM User credentials | ✔ | ✔ | |
| Assume Role using WebIdentity Token File credentials | | ✔ | ✔ |

### Examples

```yaml
Copy link

@bshelton229 bshelton229 Sep 27, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a general question I've been struggling to find documentation on from Github. What I'm seeing in my test pipelines is we need to set the id-token: write permission in the job permissions field in order to be provided the token for OIDC. I can't find this documented by Github anywhere. I'm also finding that when I set that, and thus go down the road of defining the permissions block at all, it undoes any other default permissions. This means I need to do something like:

permissions:
  id-token: write
  contents: read

In order to both get the OIDC token and continue to be able to use the token for normal actions/checkout@v2 checkouts.

The google auth plugin did seem to allude to this setting when they updated for OIDC I noticed - https://github.com/google-github-actions/auth#usage

I can't find any Github documentation around this, which I assume is because this actual feature is still beta? If AWS or anyone understands how this thing works, maybe it could be documented here :)

google-github-actions/auth@f8bb88e#diff-b335630551682c19a781afebcf4d07bf978fb1f8ac04c6bf87428ed5106870f5

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we're also still waiting on official documenation

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome, thanks for verifying I'm not just missing something.

- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v1
with:
aws-region: us-east-2
role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role
role-session-name: MySessionName
```
In this example, the Action will load the OIDC token from the GitHub-provided environment variable and use it to assume the role `arn:aws:iam::123456789100:role/my-github-actions-role` with the session name `MySessionName`.

```yaml
- name: Configure AWS Credentials
uses: aws-actions/configure-aws-credentials@v1
Expand All @@ -99,48 +115,52 @@ Example:
```
In this example, the secret `AWS_ROLE_TO_ASSUME` contains a string like `arn:aws:iam::123456789100:role/my-github-actions-role`. To assume a role in the same account as the static credentials, you can simply specify the role name, like `role-to-assume: my-github-actions-role`.

### Permissions for assuming a role
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we also remove permissions to assuming a role from the Table of Contents


In order to assume a role, the IAM user for the static credentials must have the following permissions:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"sts:AssumeRole",
"sts:TagSession"
],
"Resource": "arn:aws:iam::123456789012:role/my-github-actions-role",
"Effect": "Allow"
}
]
}
### Sample IAM Role CloudFormation Template
```yaml
Parameters:
GitHubOrg:
Type: String
RepositoryName:
Type: String
OIDCProviderArn:
Description: Arn for the GitHub OIDC Provider.
Default: ""
Type: String

Conditions:
CreateOIDCProvider: !Equals
- !Ref OIDCProviderArn
- ""

Resources:
Role:
Type: AWS::IAM::Role
Properties:
RoleName: ExampleGithubRole
AssumeRolePolicyDocument:
Statement:
- Effect: Allow
Action: sts:AssumeRoleWithWebIdentity
Principal:
Federated: !Ref GithubOidc
Condition:
StringLike:
vstoken.actions.githubusercontent.com:sub: !Sub repo:${GitHubOrg}/${RepositoryName}:*

GithubOidc:
Type: AWS::IAM::OIDCProvider
Condition: CreateOIDCProvider
Properties:
Url: https://vstoken.actions.githubusercontent.com
ClientIdList: [sigstore]
ThumbprintList: [a031c46782e6e6c662c2c87c76da9aa62ccabd8e]

Outputs:
Role:
Value: !GetAtt Role.Arn
```

The role's trust policy must allow the IAM user to assume the role:
```json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowIamUserAssumeRole",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Principal": {"AWS": "arn:aws:iam::123456789012:user/my-github-actions-user"},
"Condition": {
"StringEquals": {"sts:ExternalId": "Example987"}
}
},
{
"Sid": "AllowPassSessionTags",
"Effect": "Allow",
"Action": "sts:TagSession",
"Principal": {"AWS": "arn:aws:iam::123456789012:user/my-github-actions-user"}
}
]
}
```
The GitHub OIDC Provider only needs to be created once per account (i.e. multiple IAM Roles that can be assumed by the GitHub's OIDC can share a single OIDC Provider)

### Session tagging
The session will have the name "GitHubActions" and be tagged with the following tags:
Expand All @@ -158,7 +178,10 @@ The session will have the name "GitHubActions" and be tagged with the following

_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 '*'._

The action will use session tagging by default during role assumption. You can skip this session tagging by providing `role-skip-session-tagging` as true in the action's inputs:
The action will use session tagging by default during role assumption.
Note that for WebIdentity role assumption, the session tags have to be included in the encoded WebIdentity token.
This means that Tags can only be supplied by the OIDC provider and not set during the AssumeRoleWithWebIdentity API call within the Action.
You can skip this session tagging by providing `role-skip-session-tagging` as true in the action's inputs:

```yaml
uses: aws-actions/configure-aws-credentials@v1
Expand Down Expand Up @@ -189,7 +212,8 @@ with:
```
In this case, your runner's credentials must have permissions to assume the role.

You can also assume a role using a web identity token file, such as if using [Amazon EKS IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts-technical-overview.html). Pods running in EKS worker nodes that do not run as root can use this file to assume a role with a web identity.
You can also assume a role using a web identity token file, such as if using [Amazon EKS IRSA](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts-technical-overview.html).
Pods running in EKS worker nodes that do not run as root can use this file to assume a role with a web identity.

You can configure your workflow as follows in order to use this file:
```yaml
Expand Down
Loading