Awesome Open Source
Awesome Open Source

assume-aws-role-action

GitHub release (latest by date) GitHub issues GitHub Workflow Status Gitter

This action enables workflows to obtain AWS Access Credentials for a desired IAM Role using AWS IAM SAML and a GitHub Actions Repository Token.

Benefits:

  • No need to copy/paste AWS Access Tokens into GitHub Secrets
  • No need to rotate AWS Access Tokens

This action uses SAML.to and an AWS IAM Identity Provider to exchange a GitHub Actions Token for AWS Access Credentials.

This action will set the following environment variables:

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_SESSION_TOKEN
  • AWS_DEFAULT_REGION

Usage

See action.yml

steps:
  - uses: saml-to/[email protected]
    with:
      role: arn:aws:iam::123456789012:role/admin
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  - run: aws sts get-caller-identity
  - run: aws ec2 describe-instances

Examples

See aws-assume-role-action-examples

Configuration

  1. Download Your Metadata from SAML.to

  2. Create a new SAML Identity Provider in AWS IAM

    1. Provider Name: Repository Name (the name of the repository running the action)
    2. Metadata Document: Upload the Metadata Document from SAML.to
    3. Make note of the Provder ARN in the AWS console
  3. Create or update the Trust Relationship on a new or existing IAM Role to contain the following:

    {
      "Version": "2012-10-17",
      "Statement": [
        {
          "Effect": "Allow",
          "Principal": {
            "Federated": "PROVIDER_ARN"
          },
          "Action": "sts:AssumeRoleWithSAML",
          "Condition": {
            "StringEquals": {
              "SAML:aud": "https://signin.aws.amazon.com/saml"
            }
          }
        }
      ]
    }
    
    • Replace PROVIDER_ARN with the newly created ARN of the provider, e.g. arn:aws:iam::123456789012:saml-provider/my-repository
    • Make note of the Role ARN for this Role
  4. Add a new file named saml-to.yml to the repository that needs AWS Access Credentials during GitHub Actions:

    your-repository/saml-to.yml:

    ---
    version: "20220101"
    variables:
      awsProviderArn: "PROVIDER_ARN"
      awsRoleArn: "ROLE_ARN"
    providers:
      aws:
        entityId: https://signin.aws.amazon.com/saml
        acsUrl: https://signin.aws.amazon.com/saml
        attributes:
          https://aws.amazon.com/SAML/Attributes/RoleSessionName: "<#= repo.name #>"
          https://aws.amazon.com/SAML/Attributes/SessionDuration: "3600"
          https://aws.amazon.com/SAML/Attributes/Role: "<#= repo.selectedRole #>,<$= awsProviderArn $>"
    permissions:
      aws:
        roles:
          - name: <$= awsRoleArn $>
            self: true
    
    • Replace PROVIDER_ARN with the ARN of the provider created above (e.g. arn:aws:iam::123456689012:saml-provider/my-repository)
    • Replace ROLE_ARN with the ARN of the IAM Role modified above. (e.g. arn:aws:iam::123456689012:role/admin)
  5. Modify the GitHub Action Workflow to obtain AWS Access Credentials

    your-repository/.github/workflows/action-name.yml:

       jobs:
         prerelease:
           runs-on: ubuntu-latest
           steps:
             - uses: actions/[email protected]
             ...
             - uses: saml-to/[email protected]
               env:
                 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
               with:
                 role: "ROLE_ARN"
             ...
    
    • Replace ROLE_ARN with the ARN of the IAM Role modified above. (e.g. arn:aws:iam::123456689012:role/admin)

Inputs

role (Required)

The ARN of the role to assume. This Role ARN must also be defined in the saml-to.yml configuration file under permissions.

region (Optional)

The AWS Region to use. This will also be set as the AWS_DEFAULT_REGION environment variable and the region output.

Default: us-east-1

provider (Optional)

If there are multiple provider entries in the saml-to.yml configuration file, set a specific provider.

Note: If multiple providers are configured, and this is absent, the Action will fail.

Default: `` (Empty String)

Outputs

region

The AWS Region authenitcated with (default: us-east-1)

Can be modified with the region input.

This will also be set in the AWS_DEFAULT_REGION environment variable.

accountId

The AWS Account ID authenticated with (e.g. 123456789012)

userId

The ephemeral user ID (e.g. AROAYOAAAAAAAAAAAAAAA:my-repository)

roleArn

The ARN of the Role.

It will be identical to the role input.

assumedRoleArn

The effective ARN of the Assumed Role (e.g. arn:aws:sts::123456789012:assumed-role/admin/my-repository)

accessKeyId

The generated AWS Access Key ID.

This is also be set in the AWS_ACCESS_KEY_ID environment variable.

secretAccessKey

The generated AWS Secret Access Key.

This is also be set in the AWS_SECRET_ACCESS_KEY environment variable.

sessionToken

The generated AWS Session Toke.

This is also be set in the AWS_SESSION_TOKEN environment variable.

FAQs

See FAQs

Maintainers

Help & Support

License

Apache-2.0 License



Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Typescript (246,626
Amazon Web Services (38,275
Github Actions (4,697
Saml (1,235
Aws Iam (174
Assume Role (22