aws/assume-role 2.1.0

Assume an AWS role

Source Code
https://github.com/rwx-cloud/packages/tree/main/aws/assume-role
Issue Tracker
https://github.com/rwx-cloud/packages/issues

Parameters

Parameter
Required
Default
Description
region
*
The AWS region (e.g. us-east-2).
role-to-assume
*
The ARN of the AWS role to be assumed (e.g. arn:aws:iam::your-account-id:role/your-role).
role-duration-seconds
900
The role duration in seconds.
role-session-name
The name of the session.
profile-name
default
The profile under which the credentials will be configured.
oidc-token-env-var
AWS_OIDC_TOKEN
The environment variable that contains the OIDC token.
oidc-token-path-env-var
AWS_OIDC_TOKEN_PATH
The environment variable that contains the path to the OIDC token file.
role-chaining
false
Enable role chaining.
source-profile-name
default
The profile used to assume the chained role (only used with role-chaining is enabled).

README.md

To assume a role:

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role

  - key: task-that-needs-role
    use: [aws-cli, assume-role]
    run: ...
    env:
      AWS_OIDC_TOKEN_PATH: ${{ vaults.your-vault.oidc.your-token.path }}

The package accepts either the token file path in AWS_OIDC_TOKEN_PATH or the token contents in AWS_OIDC_TOKEN, but not both. In path mode, the package configures an AWS web identity profile so the CLI and compatible SDKs reread the rotating token file when their temporary credentials expire. Prefer AWS_OIDC_TOKEN_PATH when it is available. Use the oidc-token-path-env-var and oidc-token-env-var parameters to customize the environment variable names.

If for some reason you need to opt-out of role assumption, your task can set specify the environment variable AWS_SKIP_AUTH to true.

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role

  - key: task-that-does-not-need-role
    use: [aws-cli, assume-role]
    run: ...
    env:
      AWS_SKIP_AUTH: true

To specify the length of the session:

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role
      role-duration-seconds: 3600

  - key: task-that-needs-role
    use: [aws-cli, assume-role]
    run: ...
    env:
      AWS_OIDC_TOKEN:
        value: ${{ vaults.your-vault.oidc.your-token }}
        cache-key: excluded

To choose a name for the session:

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role
      role-session-name: your-unique-session-name-${{ run.id }}

  - key: task-that-needs-role
    use: [aws-cli, assume-role]
    run: ...
    env:
      AWS_OIDC_TOKEN:
        value: ${{ vaults.your-vault.oidc.your-token }}
        cache-key: excluded

To configure a specific profile:

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role
      profile-name: your-profile

  - key: task-that-needs-role
    use: [aws-cli, assume-role]
    run: ...
    env:
      AWS_OIDC_TOKEN:
        value: ${{ vaults.your-vault.oidc.your-token }}
        cache-key: excluded

To assume another role, via chaining:

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      oidc-token: ${{ vaults.your-vault.oidc.your-token }}
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role

  - key: chained-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-other-role
      role-chaining: true

  - key: task-that-needs-chained-role
    use: [aws-cli, assume-role, chained-role]
    run: ...
    env:
      AWS_OIDC_TOKEN:
        value: ${{ vaults.your-vault.oidc.your-token }}
        cache-key: excluded

To assume another role, via chaining, with specific profiles:

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role
      profile-name: your-profile

  - key: chained-role
    call: aws/assume-role 2.1.0
    with:
      source-profile-name: your-profile
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-other-role
      profile-name: your-other-profile

  - key: task-that-needs-chained-role
    use: [aws-cli, assume-role, chained-role]
    run: ...
    env:
      AWS_OIDC_TOKEN:
        value: ${{ vaults.your-vault.oidc.your-token }}
        cache-key: excluded

Upgrading from v1.X.X

In v1.X.X the AWS OIDC token was provided as a leaf parameter. Starting in version 2, the AWS OIDC token is provided to tasks that use the assume role leaf task as an environment variable (by default AWS_OIDC_TOKEN).

With this change, the task will run the role assumption as a before hook. As a result of this, upon retrying a task, a new token will be used, preventing the incidental use of expired credentials.

Assuming a Role

Before

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    use: aws-cli
    call: aws/assume-role 1.1.4 # deprecated by 2.0.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role
      oidc-token: ${{ vaults.your-vault.oidc.your-token }}

  - key: your-task
    use: assume-role
    run: # ...

After

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role

  - key: your-task
    use: [aws-cli, assume-role]
    run: ...
    env:
      AWS_OIDC_TOKEN:
        value: ${{ vaults.your-vault.oidc.your-token }}
        cache-key: excluded

Role Chaining

Before

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    use: aws-cli
    call: aws/assume-role 1.1.4 # deprecated by 2.0.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role
      oidc-token: ${{ vaults.your-vault.oidc.your-token }}

  - key: chain-role
    use: assume-role
    call: aws/assume-role 1.1.4 # deprecated by 2.0.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-other-role

  - key: your-task
    use: chain-role
    run: ...

After

tasks:
  - key: aws-cli
    call: aws/install-cli 1.0.8

  - key: assume-role
    call: aws/assume-role 2.1.0
    with:
      oidc-token: ${{ vaults.your-vault.oidc.your-token }}
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-role

  - key: chain-role
    call: aws/assume-role 2.1.0
    with:
      region: us-east-2
      role-to-assume: arn:aws:iam::your-account-id:role/your-other-role
      role-chaining: true

  - key: your-task
    use: [aws-cli, assume-role, chain-role]
    run: ...
    env:
      AWS_OIDC_TOKEN:
        value: ${{ vaults.your-vault.oidc.your-token }}
        cache-key: excluded