Actions Constructs

AWS CDK Constructs for integrating GitHub Actions and AWS.

Table of Contents

• "Legacy" Constructs
• ActionsIdentityPoolV2
  • Usage
  • Usage - GitHub Actions
  • OpenID Connect Provider
    • Audience
  • Mapped Claims
    • Custom Tag Names
    • Library Tag Abbreviations
  • Enhanced AuthFlow
• ActionsIdentityPolicyUtility
  • Philosophy
  • Constraints
    • Example
      • Regular Usage
      • With Policy Utility
  • Policy Constraining
  • Policy Variable and PrincipalTagConditionKey
  • ActionsIdentityConstraints
    • Constraints and CDK
  • Resource Paths
    • ToString
    • More Examples
  • Role-Chaining (Cross Account)
  • Role Chaining in Workflows
  • Passing Claims
    • Trust Policy
• Entrypoint Account
  • Grant Organization Role Chain
    • Policy Statement
• Additional Roles
  • Same Stack
  • Separate Stack

"Legacy" Constructs

Will continue to be supported.

• ActionsIdentityPool
• ActionsIdentityPoolBasic

ActionsIdentityPoolV2

Detailed explanation of the use-case can be found here.

Use this to create a Cognito Identity Pool that allows GitHub Actions to authenticate and receive temporary AWS credentials that has session/principal tags corresponding with the GitHub Actions claims. This enables attribute-based access control (ABAC) to AWS resources from GitHub Actions.

Usage

1import * as iam from 'aws-cdk-lib/aws-iam';
2import * as cdk from 'aws-cdk-lib';
3import {
4  ActionsIdentityPoolV2,
5  ActionsIdentityMappedClaims,
6  GitHubActionsClaimConstraint,
7} from '@catnekaise/actions-constructs';
8
9const app = new cdk.App();
10const stack = new cdk.Stack(app, 'CatnekaiseActionsIdentityExampleStack');
11
12// More details about OIDC Provider further below.
13const openIdConnectProvider = iam.OpenIdConnectProvider
14        .fromOpenIdConnectProviderArn(stack, 'Provider', `arn:aws:iam::${stack.account}:oidc-provider/token.actions.githubusercontent.com`);
15
16const pool = new ActionsIdentityPoolV2(stack, 'Pool', {
17  authenticatedRoleConstraints: [
18    // change value to the name(s) of your GitHub organization(s) that shall be allowed to authenticate
19    GitHubActionsClaimConstraint.repoOwners('catnekaise'),
20  ],
21  mappedClaims: ActionsIdentityMappedClaims.create(GhaClaim.REPOSITORY, GhaClaim.ACTOR, GhaClaim.RUNNER_ENVIRONMENT),
22  authenticatedRoleName: 'GhaCognito', // Optional
23  openIdConnectProvider,
24});

Usage - GitHub Actions

If having used the example above you can test it by using the workflow below. Make sure to update the values to match your environment.

Also, make sure the OIDC Provider Audience has been configured with whichever audience is used below.

1on:
2  workflow_dispatch:
3jobs:
4  job1:
5    runs-on: ubuntu-latest
6    permissions:
7      id-token: write
8      contents: read
9    steps:
10      - name: "Get Credentials from Amazon Cognito Identity"
11        uses: catnekaise/cognito-idpool-auth@v1
12        with:
13          # Change values below to match your setup
14          auth-flow: "basic"
15          cognito-identity-pool-id: "eu-west-1:11111111-example"
16          aws-role-arn: "arn:aws:iam::111111111111:role/GhaCognito"
17          aws-region: "eu-west-1"
18          audience: "cognito-identity.amazonaws.com"
19          aws-account-id: "111111111111"
20          set-in-environment: true
21      
22      - name: "STS Get Caller Identity"
23        run: |
24          aws sts get-caller-identity

OpenID Connect Provider

• If no OIDC Provider is defined in the props given to ActionsIdentityPoolV2 it will try to import the provider from the AWS Account where the pool is being created.
• If the OIDC Provider does not exist in the target account, the construct cannot be deployed.
• If using GitHub Enterprise with a customized issuer, then import/create that provider and explicitly define it in the props.

1const stack = new cdk.Stack(new cdk.App(), 'CatnekaiseActionsIdentityExampleStack');
2
3// Example for creating the OIDC Provider in the same stack as the Identity Pool
4const openIdConnectProvider = new iam.OpenIdConnectProvider(stack, 'Provider', {
5  url: 'https://token.actions.githubusercontent.com',
6  // Keep sts.amazonaws.com if also using account to assume roles directly via STS
7  clientIds: ['cognito-identity.amazonaws.com', 'sts.amazonaws.com'],
8});
9
10const pool = new ActionsIdentityPoolV2(stack, 'Pool', {
11  openIdConnectProvider,
12  // ...
13});

Audience

If the provider already exist, go ahead and add the clientId (audience) cognito-identity.amazonaws.com to the existing provider. This is the audience used as default value for actions catnekaise/cognito-idpool-auth and catnekaise/cognito-idpool-auth-basic.

Mapped Claims

Because there's a limit for how much data can be put into a session in AWS, not all existing GitHub Actions claims can be mapped by Cognito Identity. Attempting to map all (or too many) claims will result in failure when assuming a role.

ActionsIdentityMappedClaims is used for selecting which claims should be mapped in the identity pool. It can also be used to map claims using different tag names than the claim name. Using shorter tag names gives room for mapping additional claims and staying under the limit. Further details for how to manage the session limit can be found here.

A good starting point of which claims to map that should not affect these limits:

1const mappedClaims = ActionsIdentityMappedClaims.create(
2        GhaClaim.REPOSITORY,
3        GhaClaim.ACTOR,
4        GhaClaim.RUN_ID,
5        GhaClaim.SHA,
6        GhaClaim.REF,
7        GhaClaim.JOB_WORKFLOW_REF,
8);

Custom Tag Names

Claims can be mapped to a tag with a different name than the original claim. The key is the name of the claim and value will become name of the tag.

1const mappedClaims = ActionsIdentityMappedClaims.createCustom({
2  repository: 'repo',
3  job_workflow_ref: 'jWorkRef'
4})

Library Tag Abbreviations

This library has a set of abbreviations that can be used to shorten the tag names. Value of the abbreviation tag names can be found in claims.ts.

1const mappedClaims = ActionsIdentityMappedClaims.createWithAbbreviations(
2        // becomes `repo` instead of `repository`
3        GhaClaim.REPOSITORY,
4        // becomes `jWorkRef` instead of `job_workflow_ref`
5        GhaClaim.JOB_WORKFLOW_REF,
6);

Enhanced AuthFlow

[!NOTE] Using the basic auth-flow will feel the most similar to how you have been using GitHub Actions OIDC with AWS STS today, so it may be a better starting point than the enhanced auth-flow.

By default the ActionsIdentityPoolV2 uses the Basic (Classic) AuthFlow but it can also be configured to use the Enhanced (Simplified) AuthFlow.

Using the enhanced auth-flow requires an extra step where a role-assignment is made. More details about the differences of these auth-flows in the context of GitHub Actions can be found here.

1const pool = new ActionsIdentityPoolV2(stack, 'Pool', {
2  useEnhancedAuthFlow: true,
3  // other props
4});
5
6const role: iam.Role = pool.defaultAuthenticatedRole;
7
8// The claims used in role assignment does not have to be claims that are mapped in the identity pool.
9pool.enhancedFlowAssignRole(role, GhaClaim.REPOSITORY_OWNER, EnhancedFlowMatchType.EQUALS, 'catnekaise');

ActionsIdentityPolicyUtility

Use the policy utility to:

• Create principals (trust policy) for additional IAM Roles assumed via Cognito Identity
• Create principals (trust policy) for IAM Roles assumed via the roles above (role-chaining)
• Build resource paths containing a mix of text and GitHub Actions claims
• Append grants with conditions based on claims from GitHub Actions
• Append policy statements with conditions based on claims from GitHub Actions

1import { ActionsIdentityPoolV2, ActionsIdentityPolicyUtility } from '@catnekaise/actions-constructs';
2
3declare const pool: ActionsIdentityPoolV2;
4
5// Available via ActionsIdentityPoolV2
6let policyUtility = pool.policyUtility;
7
8// Configure separately
9policyUtility = ActionsIdentityPolicyUtility.create(scope, {
10  mappedClaims: ActionsIdentityMappedClaims.create(GhaClaim.REPOSITORY /** additional claims **/),
11  // Additional utility configuration
12});

Philosophy

The ActionsIdentityPolicyUtility aims to make it as easy as possible to work with the GitHub Actions claims while minimizing interference with how you work with AWS CDK today.

• The utility prevents you from using claims you have not mapped in your identity pool.
• The utility will select correct tag names if you have mapped a claim to a tag with a different name.
• Any changes to mapped claims configuration is reflected in any conditions or resource paths created via the policy utility

Constraints

In the context of this library (and catnekaise/cdk-iam-utilities), constraining is the act of appending existing iam.PolicyStatement(s) with conditions. One applied constraint may conditionally add none, one or many conditions to the provided policy statement(s).

The goal of constraints is to simplify working with the condition block of a policy statement when there are many conditions being used, and to help make working with the conditions "contextual" to the task at hand, such as creating policies for GitHub Actions attribute based access controls.

Example

Using the existing functionality in CDK of granting a role the permissions to read and write in a S3 bucket, there are these example requirements:

• Can only read/write to an object prefix that matches artifacts/workflow_run/${{ github.repository }}/${{ github.run_id }}/*
• Can only read/write when workflow is running on a self-hosted runner
• Can only read/write when workflows running is a re-usable workflow on the main branch in repository catnekaise/shared-workflows

Regular Usage

1declare const bucket: s3.Bucket;
2
3const grant = bucket.grantReadWrite(role,
4        'artifacts/workflow_run/${aws:principalTag/repository}/${aws:principalTag/run_id}/*',
5);
6
7grant.principalStatements[0].addCondition('StringEquals', {
8  'aws:principalTag/runner_environment': 'self-hosted',
9});
10
11grant.principalStatements[0].addCondition('StringLike', {
12  'aws:principalTag/job_workflow_ref': 'catnekaise/shared-workflows/.github/workflows/*@refs/heads/main',
13});

With Policy Utility

1declare const pool: ActionsIdentityPoolV2;
2declare const bucket: s3.Bucket;
3
4const grant = bucket.grantReadWrite(role,
5        pool.policyUtility.util.resourcePath('artifacts/workflow_run', GhaClaim.REPOSITORY, GhaCLaim.RUN_ID, '*'),
6);
7
8pool.policyUtility.constrainGrant(grant)
9        .whenSelfHosted()
10        .jobWorkflowLike('catnekaise', 'shared-workflows', '*', 'refs/heads/main');

Policy Constraining

A single policy statement can be constrained in the same way as a grant.

1declare const role: iam.Role;
2declare const pool: ActionsIdentityPoolV2;
3
4const policy = new iam.PolicyStatement({
5  effect: iam.Effect.ALLOW,
6  actions: ['ssm:GetParameter'],
7  resources: ['*'],
8});
9
10pool.policyUtility.constrain(policy)
11        .hasResourceTagEqualToClaim('repository', GhaClaim.REPOSITORY);
12
13role.addToPolicy(policy);

Policy Variable and PrincipalTagConditionKey

It's also possible to create individual policy variables and/or principal tags via the policy utility and use them in condition statements. Any changes made to the mapped claims configurations will be reflected in variables/tags created via the policy utility.

1import { ActionsIdentityPolicyUtility, GhaClaim } from '@catnekaise/actions-constructs';
2
3const policyUtility = ActionsIdentityPolicyUtility.create(scope, {
4  mappedClaims: ActionsIdentityMappedClaims.create(GhaClaim.REPOSITORY, GhaClaim.ACTOR),
5});
6
7const policyVariable = policyUtility.policyVar(GhaClaim.REPOSITORY);
8const principalTag = policyUtility.principalTagConditionKey(GhaClaim.ACTOR);
9
10const policy = new iam.PolicyStatement({
11  conditions: {
12    StringEquals: {
13      [principalTag.toString()]: 'catnekaise/example-repo',
14      'aws:ResourceTag/owner': policyVariable.toString(),
15    },
16  },
17});

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Condition": {
6        "StringEquals": {
7          "aws:PrincipalTag/repository": "catnekaise/example-repo",
8          "aws:ResourceTag/owner": "${aws:PrincipalTag/actor}"
9        }
10      }
11    }
12  ]
13}

ActionsIdentityConstraints

When working with constraints via the policy utility you will be using ActionsIdentityConstraints where convenience methods has been created for some common scenarios such as whenSelfHosted() and repoOwners('catnekaise', 'additional-org').

These convenience methods do cover all possible scenarios. The following methods can be used for those scenarios.

1import { ConditionOperator } from '@catnekaise/cdk-iam-utilities';
2
3pool.policyUtility.newPrincipalBuilder()
4        .claimEquals(GhaClaim.REPOSITORY_VISIBILITY, 'public') // StringEquals
5        .claimLike(GhaClaim.ENVIRONMENT, 'dev-*') // StringLike
6        .claimCondition(ConditionOperator.STRING_NOT_EQUALS, GhaClaim.ENVIRONMENT, 'dev-custom');

Constraints and CDK

Whether on a single policy statement or on several policy statements included in a grant, each condition is added to each policy statement via policyStatement.addCondition(). If the combination of Operator and ConditionKey already exists, existing value(s) gets replaced.

1declare const role: iam.Role;
2declare const pool: ActionsIdentityPoolV2;
3
4const policy = new iam.PolicyStatement({
5  effect: iam.Effect.ALLOW,
6  actions: [],
7  resources: [],
8  conditions: {
9    StringEquals: {
10      'aws:PrincipalTag/runner_environment': 'github-hosted',
11    },
12  },
13});
14
15// Condition value runner_environment is changed from github-hosted to self-hosted
16pool.policyUtility.constrain(policy).whenSelfHosted();
17
18// Condition value is changed from self-hosted to github-hosted
19policy.addCondition('StringEquals', { 'aws:PrincipalTag/runner_environment': 'self-hosted' });
20
21role.addToPolicy(policy);

Resource Paths

Concatenate strings and claims to a resource path. All examples below results in the resource path: items/${aws:principalTag/repository}/${aws:principalTag/environment}/*.

1declare const pool: ActionsIdentityPoolV2;
2declare const bucket: s3.Bucket;
3
4let resourcePath: string;
5
6resourcePath = policyUtility.resourcePath('items', GhaClaim.REPOSITORY, GhaCLaim.ENVIRONMENT, '*').toString();
7
8resourcePath = policyUtility.resourcePath()
9        .text('items')
10        .claim(GhaClaim.REPOSITORY, GhaClaim.ENVIRONMENT)
11        .text('*').toString();
12
13resourcePath = policyUtility.resourcePath('items')
14        .value(GhaClaim.REPOSITORY, GhaClaim.ENVIRONMENT, '*').toString();
15
16const grant = bucket.grantReadWrite(role, resourcePath);

ToString

While some CDK constructs allow passing in resource paths of any type and will implicitly invoke the toString() method, it's best to invoke toString() before passing the resource path to where it will be used.

More Examples

1import { ActionsIdentityPoolV2 } from '@catnekaise/actions-constructs';
2
3declare const pool: ActionsIdentityPoolV2;
4declare const bucket: s3.Bucket;
5declare const terraformStateTable: dynamodb.TableV2;
6
7// Allow Github Actions to store cache to an S3 bucket in context of repository and the ref that is running
8bucket.grantReadWrite(pool.defaultAuthenticatedRole,
9        pool.policyUtility.resourcePath('cache', GhaClaim.REPOSITORY, GhaCLaim.REF, '*'));
10
11// Allow Github Actions to upload/download artifacts in context of repository and the specific workflow run
12bucket.grantReadWrite(pool.defaultAuthenticatedRole,
13        pool.policyUtility.resourcePath('artifacts/workflow_run', GhaClaim.REPOSITORY, GhaCLaim.RUN_ID, '*'));
14
15
16// Allow terraform running in GitHub Actions to to acquire state lock, but only on the combination of repository and environment running
17const tableGrant = terraformStateTable.grant(pool.defaultAuthenticatedRole, 'dynamodb:DescribeTable', 'dynamodb:GetItem', 'dynamodb:PutItem', 'dynamodb:DeleteItem');
18tableGrant.principalStatements.addCondition('ForAllValues:StringEquals', {
19  'dynamodb:LeadingKeys': [
20    pool.policyUtility.resourcePath(GhaClaim.REPOSITORY, GhaClaim.ENVIRONMENT, 'terraform.tfstate').toString(),
21  ],
22});

Role-Chaining (Cross Account)

The example below can be split into separate CDK Apps.

1const poolStack = new cdk.Stack(app, 'PoolStack', {
2  env: {
3    region: 'eu-west-1',
4    account: '111111111111',
5  },
6});
7
8const workloadStack = new cdk.Stack(app, 'WorkloadStack', {
9  env: {
10    region: 'eu-west-1',
11    account: '222222222222',
12  },
13});
14
15workloadStack.addDependency(poolStack);
16
17const mappedClaims = ActionsIdentityMappedClaims.create(GhaClaim.REPOSITORY, GhaClaim.ENVIRONMENT);
18
19const pool = new ActionsIdentityPoolV2(poolStack, 'Pool', {
20  authenticatedRoleConstraints: [
21    // change value to the name(s) of your GitHub organization(s) or username(s) that shall be allowed to authenticate
22    GitHubActionsClaimConstraint.repoOwners('catnekaise'),
23  ],
24  mappedClaims,
25  authenticatedRoleName: 'GhaCognito',
26});
27
28pool.defaultAuthenticatedRole.grantAssumeRole(new iam.SessionTagsPrincipal(new iam.ArnPrincipal('arn:aws:iam::222222222222:role/github-actions/WorkloadDeploymentDev')));
29
30
31new iam.Role(workloadStack, 'Role', {
32  roleName: 'WorkloadDeploymentDev',
33  path: '/github-actions/',
34  assumedBy: util.newChainedPrincipalBuilder()
35          .repositoryEquals('catnekaise/workload-repo')
36          .environmentEquals('dev')
37          .createPrincipalAssumedBy(workloadStack, new iam.AccountPrincipal('111111111111'), {
38            // Read more about passing claims further below
39            passClaims: mappedClaims.toPassClaims(),
40          }),
41});

Role Chaining in Workflows

For more information, read documentation at catnekaise/cognito-idpool-auth

1on:
2  workflow_dispatch:
3    inputs:
4      environment:
5        required: true
6        description: Environment
7
8jobs:
9  job1:
10    runs-on: ubuntu-latest
11    environment: ${{ inputs.environment }}
12    permissions:
13      id-token: write
14      contents: read
15    steps:
16      - name: "Get Credentials from Amazon Cognito Identity"
17        uses: catnekaise/cognito-idpool-auth@v1
18        with:
19          # Change values below to match your environment
20          cognito-identity-pool-id: "eu-west-1:11111111-example"
21          aws-role-arn: "arn:aws:iam::111111111111:role/GhaCognito"
22          aws-region: "eu-west-1"
23          audience: "cognito-identity.amazonaws.com"
24          aws-account-id: "111111111111"
25          set-in-environment: true
26          role-chain-pass-claims: "repository,environment"
27          role-chain-arn: "arn:aws:iam::222222222222:role/WorkloadDevDeployment"

Passing Claims

In the context of this library, passing claims means tagging the next session with one or more of the GitHub Actions claims present in the current role session. Doing this is optional, but it makes it possible to use the GitHub Actions claims with policies inside the workload account.

In order to not allow the workflow to alter the value of claims during role chaining or setting any additional session tags, the trust policy in the workload account needs to be configured accordingly.

1import * as iam from 'aws-cdk-lib/aws-iam';
2import * as cdk from 'aws-cdk-lib';
3import { ActionsIdentityPolicyUtility, ActionsIdentityMappedClaims, GhaClaim } from '@catnekaise/actions-constructs';
4
5const stack = new cdk.Stack(new cdk.App(), 'WorkloadStack');
6
7const mappedClaims = ActionsIdentityMappedClaims.create(GhaClaim.ACTOR, GhaClaim.REPOSITORY, GhaClaim.SHA, GhaClaim.REF, GhaClaim.ENVIRONMENT);
8
9// All claims will have to be defined as session tags when using AssumeRole
10const passAllClaims = mappedClaims.toPassClaims();
11
12// Only the Repository and Environment claim has to be set when using AssumeRole
13const passSomeClaims = mappedClaims.toPassClaims(GhaClaim.ENVIRONMENT, GhaClaim.REPOSITORY);
14
15// Only Repository and Environment has to be set, but has to be set with customized tag names
16const passCustomClaims = mappedClaims.toPassClaimsCustom({
17  // claim: tagName
18  repository: 'repo',
19  environment: 'github_environment',
20});
21
22// Allows directly using the configure-aws-credentials action: https://github.com/aws-actions/configure-aws-credentials#session-tagging-and-name
23// Note: The only real claims passable using this is: Repository, Actor, Sha and Ref
24const passConfigureAwsCredentialsClaims = mappedClaims.toConfigureAwsCredentialsPassClaims();
25
26const util = ActionsIdentityPolicyUtility.create(stack, {
27  mappedClaims,
28});
29
30new iam.Role(workloadStack, 'Role', {
31  roleName: 'WorkloadRole',
32  assumedBy: util.newChainedPrincipalBuilder()
33          .repositoryEquals('catnekaise/workload-repo')
34          .environmentEquals('dev')
35          .createPrincipalAssumedBy(workloadStack, new iam.AccountPrincipal('111111111111'), {
36            // Set one of the examples above
37            passClaims: passSomeClaims,
38          }),
39});

Trust Policy

The example above would produce this trust policy:

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Principal": {
7        "AWS": "arn:aws:iam::111111111111:root"
8      },
9      "Action": [
10        "sts:AssumeRole",
11        "sts:TagSession"
12      ],
13      "Condition": {
14        "StringEquals": {
15          // Requires role was assumed via Cognito Identity
16          "aws:FederatedProvider": "cognito-identity.amazonaws.com",
17          // Requires that value of current session tags equals the following environment and repository
18          "aws:PrincipalTag/environment": "dev",
19          "aws:PrincipalTag/repository": "catnekaise/workload-repo",
20          // Requires setting session tags with same value as current session tags
21          "aws:RequestTag/environment": "${aws:principalTag/environment}",
22          "aws:RequestTag/repository": "${aws:principalTag/repository}"
23        },
24        "ForAllValues:StringEquals": {
25          // Requires that only the two following session tags are set
26          "aws:TagKeys": [
27            "repository",
28            "environment"
29          ]
30        }
31      }
32    }
33  ]
34}

Entrypoint Account

In the context of this library (and its associated documentation), an entrypoint account is a production AWS account in an organization that is trusted to have correctly configured Cognito Identity, associated AWS IAM Roles and their permissions. This account is where GitHub Actions authentication starts.

The AWS credentials received from the Cognito Identity Pool in the entrypoint account is primarily used to perform role chaining into many workload accounts.

Grant Organization Role Chain

When assuming a role cross-account, the role that performs AssumeRole needs permissions to do this (in addition to the cross-account role trust policy allowing the assumption to begin with). In order to not have to add permission for each individual workload role that an identity pool role shall be allowed to assume, and in order to not grant the same role the ability to assume any roles that have a weak trust policy, grantOrganizationRoleChain can be used.

grantOrganizationRoleChain provides an opinionated interface of granting the type of permissions required to meet the criteria above.

1import { ActionsIdentityPoolV2 } from '@catnekaise/actions-constructs';
2
3declare const pool: ActionsIdentityPoolV2;
4
5pool.policyUtility.grantOrganizationRoleChain(pool.defaultAuthenticatedRole, {
6  // One of rolePath or roleHasResourceTags is required, or both.
7  rolePath: '/github-actions/',
8  roleHasResourceTags: {
9    usedViaGitHubActions: '1',
10  },
11  // Optional
12  resourceOrgPaths: ['o-example/r-ab12/ou-ab12-11111111/*'],
13  // Optional
14  // Identity Pool AWS Account ID is automatically excluded when using policyUtility via ActionsIdentityPoolV2
15  excludeAccountIds: ['333333333333', '444444444444'],
16});

Policy Statement

The following permissions are granted to the role in the example above.

1{
2  "Version": "2012-10-17",
3  "Statement": [
4    {
5      "Effect": "Allow",
6      "Action": "sts:TagSession",
7      "Resource": "*"
8    },
9    {
10      "Effect": "Allow",
11      "Action": "sts:AssumeRole",
12      // Limited to assuming workload roles under path /github-actions/
13      "Resource": "arn:aws:iam::*:role/github-actions/*",
14      "Condition": {
15        "StringEquals": {
16          // Limited to assuming workload roles that have the following tag
17          "aws:ResourceTag/usedViaGitHubActions": "1",
18          // Limit to assuming roles within the same organization as the current role
19          "aws:ResourceOrgID": "${aws:PrincipalOrgID}"
20        },
21        "StringNotEquals": {
22          // Shall explicitly not be allowed to assume roles in identity pool account (111111111111)
23          // Shall explicitly not be allowed to assume roles in accounts 333333333333, 444444444444
24          "aws:ResourceAccount": ["111111111111", "333333333333", "444444444444"]
25        },
26        "ForAnyValue:StringLike": {
27          // Shall only be allowed to assume roles under the following organization path
28          "aws:ResourceOrgPaths": [
29            "o-example/r-ab12/ou-ab12-11111111/*"
30          ]
31        }
32      }
33    }
34  ]
35}

Additional Roles

More roles can be created and assumed via a Cognito Identity Pool. If using the enhanced auth-flow, these roles must exist in the same AWS account as the identity pool. If using the basic auth-flow, these roles can be created in any AWS Account and reference the ID of the identity pool.

Using the ActionsIdentityPolicyUtility, the trust policies for these roles can be created that align with the configuration of an identity pool in any stack.

Same Stack

1declare const pool: ActionsIdentityPoolV2;
2
3const principal = pool.policyUtility.newPrincipalBuilder()
4        .repositoryEquals('catnekaise/workload-repo')
5        .createPrincipal(pool);
6
7const role = new iam.Role(scope, 'AdditionalRole', {
8  assumedBy: principal,
9});
10
11// If using the enhanced auth-flow, assignment must be configured
12pool.enhancedFlowAssignRole(role, GhaClaim.REPOSITORY, EnhancedFlowMatchType.EQUALS, 'catnekaise/workload-repo');

Separate Stack

1import { ActionsIdentityPolicyUtility } from '@catnekaise/actions-constructs';
2
3const mappedClaims = ActionsIdentityMappedClaims.create(
4        GhaClaim.REPOSITORY,
5        // additional claims
6);
7
8const utility = ActionsIdentityPolicyUtility.create(stack, {
9  mappedClaims,
10  // identityPoolId is required when using the principalBuilder.
11  identityPoolId: 'eu-west-1:11111111-example',
12});
13
14const principal = utility.newPrincipalBuilder()
15        .repositoryEquals('catnekaise/workload-repo')
16        .createPrincipal(pool);
17
18new iam.Role(scope, 'AdditionalRole', {
19  assumedBy: principal,
20});