{"id":22854753,"url":"https://github.com/catnekaise/cognito-idpool-auth","last_synced_at":"2025-04-30T12:14:48.439Z","repository":{"id":203299558,"uuid":"709171033","full_name":"catnekaise/cognito-idpool-auth","owner":"catnekaise","description":"Authenticate with Amazon Cognito Identity from GitHub Actions.","archived":false,"fork":false,"pushed_at":"2024-09-03T16:37:07.000Z","size":17,"stargazers_count":3,"open_issues_count":1,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-30T16:04:13.952Z","etag":null,"topics":["action","authentication","aws"],"latest_commit_sha":null,"homepage":"https://catnekaise.github.io","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/catnekaise.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-10-24T07:03:52.000Z","updated_at":"2024-09-03T14:47:37.000Z","dependencies_parsed_at":null,"dependency_job_id":"3c6f9894-ec71-4037-a356-c2a46c535758","html_url":"https://github.com/catnekaise/cognito-idpool-auth","commit_stats":null,"previous_names":["catnekaise/cognito-idpool-auth"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catnekaise%2Fcognito-idpool-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catnekaise%2Fcognito-idpool-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catnekaise%2Fcognito-idpool-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/catnekaise%2Fcognito-idpool-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/catnekaise","download_url":"https://codeload.github.com/catnekaise/cognito-idpool-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251699351,"owners_count":21629809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["action","authentication","aws"],"created_at":"2024-12-13T07:08:28.463Z","updated_at":"2025-04-30T12:14:48.380Z","avatar_url":"https://github.com/catnekaise.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cognito Identity Pool Authentication\n\nUse this action to perform authentication with an Amazon Cognito Identity Pool using the GitHub Actions OIDC access token. More details about this use-case can be read [here](https://catnekaise.github.io/github-actions-abac-aws/cognito-identity/).\n\nThis action supports both `Enhanched (Simplified) AuthFlow` and the `Basic (Classic) AuthFlow`.\n\n### Table of Contents\n\n- [Usage](#usage)\n- [Standard Input Parameters](#standard-input-parameters)\n- [Role Chain Input Parameters](#role-chain-input-parameters)\n- [Output](#output)\n- [Passing Claims (Session Tags)](#passing-claims-session-tags)\n  - [Passing Repository Name](#passing-repository-name)\n- [Usage - Role Chain](#usage---role-chain)\n- [Environment Variables](#environment-variables)\n- [Credentials Behaviour](#credentials-behaviour)\n  - [Behaviour when Role Chaining](#behaviour-when-role-chaining)\n- [Custom Role Arn (Enhanced AuthFlow only)](#custom-role-arn-enhanced-authflow-only)\n- [Use as a Template](#use-as-a-template)\n- [Use with a wrapper](#use-with-a-wrapper)\n- [Contributing](#contributing)\n\n## Usage\n\n```yaml\non:\n  workflow_dispatch:\njobs:\n  job1:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n    steps:\n      - name: \"Authenticate using Enhanced AuthFlow\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"enhanced\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          aws-account-id: \"111111111111\"\n          aws-region: \"eu-west-1\"\n          audience: \"cognito-identity.amazonaws.com\" # Default\n          set-in-environment: true\n\n      - name: \"Authenticate using Basic AuthFlow\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"basic\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          role-arn: \"arn:aws:iam::111111111111:role/GhaCognito\"\n          aws-account-id: \"111111111111\"\n          aws-region: \"eu-west-1\"\n          audience: \"cognito-identity.amazonaws.com\" # Default\n          set-in-environment: true\n          \n      - name: \"STS Get Caller Identity\"\n        run: |\n          aws sts get-caller-identity\n```\n\n## Standard Input Parameters\n\n- `cognito-identity-pool-id` and `auth-flow` are required.\n- `cognito-identity-provider-name` can be used if [issuer OIDC claim is customized](https://docs.github.com/en/enterprise-cloud@latest/actions/security-for-github-actions/security-hardening-your-deployments/about-security-hardening-with-openid-connect#customizing-the-issuer-value-for-an-enterprise).\n- `aws-account-id` and `aws-region` are required, but values can optionally be derived from environment variables, if this behaviour is wanted.\n- If providing `role-arn` and `auth-flow` is `enhanced`, then `aws-account-id` can be extracted from the ARN.\n- Input to action via parameters will supersede environment variables for `aws-account-id` and `aws-region`.\n  - **Env Var 1** supersedes **Env Var 2**.\n\n| Input Parameter Name           | Default                             | Example                             | Env Var 1                 | Env Var 2          |\n|--------------------------------|-------------------------------------|-------------------------------------|---------------------------|--------------------|\n| cognito-identity-pool-id       | -                                   | eu-west-1:11111111-example          | -                         | -                  |\n| cognito-identity-provider-name | token.actions.githubusercontent.com | token.actions.githubusercontent.com | -                         | -                  |\n| auth-flow                      | -                                   | basic or enhanced                   | -                         | -                  |\n| aws-account-id                 | -                                   | 1111111111111                       | CK_COGNITO_AWS_ACCOUNT_ID | AWS_ACCOUNT_ID     |\n| aws-region                     | -                                   | eu-west-1                           | AWS_REGION                | AWS_DEFAULT_REGION |\n| audience                       | cognito-identity.amazonaws.com      | cognito-identity.amazonaws.com      | -                         | -                  |\n| role-arn                       | -                                   | arn:aws:iam::111111111111:role/role | -                         | -                  |\n| set-as-profile                 | -                                   | cache                               | -                         | -                  |\n| set-in-environment             | -                                   | true                                | -                         | -                  |\n\n\n## Basic AuthFlow Parameters\nWhen using `auth-flow` `basic`, the following parameters are also available.\n\n| Input Parameter Name  | Default    |\n|-----------------------|------------|\n| role-session-name     | GhaActions |\n| role-duration-seconds | 3600       |\n\n## Role Chain Input Parameters\nRole chaining can optionally be performed after authenticating with Cognito Identity.\n\n- It's not possible to set both `set-in-environment` and `chain-set-in-environment` to `true`. Doing so will fail validation\n\n| Parameter Name              | Default    | Example                                                    |\n|-----------------------------|------------|------------------------------------------------------------|\n| chain-role-arn              | -          | arn:aws:iam::111111111111:role/github-actions/WorkloadRole |\n| chain-pass-claims           | -          | repository,actor,sha,ref,run_id                            |\n| chain-set-as-profile        | -          | workload                                                   |\n| chain-set-in-environment    | -          | true                                                       |\n| chain-role-session-name     | GhaActions | GhaActions                                                 |\n| chain-role-duration-seconds | 3600       | 3600                                                       |\n\n## Output\nIf performing a role-chain, those credentials are used as output.\n\n| Parameter             |\n|-----------------------|\n| aws_access_key_id     |\n| aws_secret_access_key |\n| aws_session_token     |\n| aws_region            |\n\n## Passing Claims (Session Tags)\n\nIt's possible to pass one or more claims from the initial role session to the next session when role chaining. This is done by specifying one or more GitHub Actions claims in `chain-pass-claims`.\n\n\u003e [!WARNING]\n\u003e Make sure the role being assumed allows `sts:TagSession` and that any claims being passed are validated by an `sts:AssumeRole` permissions policy. **If this is not done, it might be possible for an attacker to escalate privileges** if they manually make the same calls this action makes, but substitute their own values for the tags when chaining roles.\n\nFor example, if `chain-pass-claims` is `job_workflow_ref,repository`, then the following condition could be used in the IAM policy on the initial role:\n\n```json\n{\n  \"Sid\": \"AllowAssumptionIfTagsMatch\",\n  \"Effect\": \"Allow\",\n  \"Action\": \"sts:AssumeRole\",\n  \"Resource\": \"arn:aws:iam::*:role/pattern-matching-the-roles-to-allow-*\",\n  \"Condition\": {\n    \"Null\": {\n      \"aws:TagKeys\": \"false\"\n    },\n    \"ForAllValues:StringEquals\": {\n      \"aws:TagKeys\": [\"job_workflow_ref\", \"repository\"]\n    },\n    \"StringEquals\": {\n      \"sts:RoleSessionName\": \"GitHubActions\",\n      \"aws:PrincipalTag/Repository\": \"${aws:RequestTag/repository}\",\n      \"aws:PrincipalTag/job_workflow_ref\": \"${aws:RequestTag/job_workflow_ref}\"\n    }\n  }\n}\n```\n\nThis verifies that all the expected tags are set, and that the values match the ones we got from the GitHub token. The principal at this point is the initial role session, with `PrincipalTag` tags set by Cognito from the GitHub Actions claims. The `aws:RequestTag` tags are the tags passed by the caller of `AssumeRole` - i.e. this action or an attacker.\n\n\u003e [!IMPORTANT]\n\u003e The claims job_workflow_ref and environment is not available via an environment variable. Because of this, this action will parse the GitHub Actions access token already available and used in this action to find the value of these claims.\n\u003e\n\u003e This parsing will only occur if performing role-chaining and if passing the claim job_workflow_ref or environment.\n\u003e \n\u003e Find step with id \"missing_claims\" in action.yml to view details.\n\nThe following claims can be passed by this action: `actor`, `actor_id`, `base_ref`, `event_name`, `head_ref`, `job_workflow_ref`, `ref`, `ref_type`, `repository`, `repository_id`, `repository_name`, `repository_owner`, `repository_owner_id`, `run_attempt`, `run_id`, `run_number`, `runner_environment`, `sha`, and `environment`.\n\n| Input                        | Comment                                                                |\n|------------------------------|------------------------------------------------------------------------|\n| repository                   | Becomes --tags Key=repository,Value=${{ github.repository }}           |\n| repository,actor             | Appends Key,Value for actor claim                                      |\n| repository , actor, run_id   | Whitespaces are trimmed                                                |\n| repository=foo               | Explicitly set tag name. --tags Key=foo,Value=${{ github.repository }} |\n| repository=foo,actor, run_id | Only change tag name for one claim                                     |\n\n### Passing Repository Name\n\n`repository_name` is a special case. GitHub doesn't provide this as a claim, but it's derived from `repository` claim (which is of the form `repository_owner/repository_name`) as it is often used in IAM policies. As above, you **must** validate this claim. You can use a condition like:\n\n```json\n{\n  \"StringEquals\": {\n     // Validate repository_name\n    \"aws:PrincipalTag/repository\": \"${aws:RequestTag/repository_owner}/${aws:RequestTag/repository_name}\",\n     // Add if wanting to continue using the claim\n    \"aws:RequestTag/repository\": \"${aws:PrincipalTag/repository}\"\n  }\n}\n```\n\nto do this. Note that this requires you to also map `repository` and `repository_owner` in your Cognito Identity Pool.\n\n## Usage - Role Chain\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      environment:\n        required: true\n        description: Environment\njobs:\n  job1:\n    runs-on: ubuntu-latest\n    environment: ${{ inputs.environment }}\n    permissions:\n      contents: read\n      id-token: write\n    steps:\n      - uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"basic\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          aws-region: \"eu-west-1\"\n          aws-account-id: \"111111111111\"\n          role-arn: \"arn:aws:iam::111111111111:role/GhaCognito\"\n          set-as-profile: \"pool\"\n          chain-role-arn: \"arn:aws:iam::222222222222:role/github-actions/WorkloadDeploymentDev\"\n          chain-pass-claims: \"actor,ref,sha,repository,run_attempt,run_id,environment\"\n          chain-set-in-environment: true\n      - run: |\n          aws sts get-caller-identity\n          aws sts get-caller-identity --profile pool\n```\n\n## Environment Variables\n\n```yaml\non:\n  workflow_dispatch:\nenv:\n  CK_COGNITO_AWS_ACCOUNT_ID: \"${{ vars.CK_COGNITO_AWS_ACCOUNT_ID }}\"\n  AWS_DEFAULT_REGION: \"us-east-1\"\n  AWS_REGION: \"us-west-1\" # Overrides AWS_DEFAULT_REGION\njobs:\n  job1:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n    steps:\n      - name: \"Authenticate using Enhanced AuthFlow\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"enhanced\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          aws-region: \"eu-west-1\" # Overrides AWS_REGION env var\n\n      - name: \"STS Get Caller Identity\"\n        run: |\n          aws sts get-caller-identity\n```\n\n## Credentials Behaviour\n\n- Credentials are always available as output parameters from the action.\n  - The exception is when `auth-flow` is basic and no `role-arn` has been provided. Then only the `cognito_oidc_access_token` is available.\n- Set input option `set-in-environment` to `true` and standard AWS environment variables will be set.\n- Provide a profile name in input option `set-as-profile` to set credentials as a profile.\n- Providing `set-in-environment` as true, and `set-as-profile` with a value will both set environment variables and a profile.\n- When neither `set-in-environment` nor `set-as-profile` is provided, credentials are only available as outputs.\n\n### Behaviour when Role Chaining\nThis is in addition to what is listed above.\n\n- Action output will contain role-chained credentials\n- Set input option `chain-set-in-environment` to `true` and standard AWS environment variables will be set.\n  - It's not possible to set both `set-in-environment` and `chain-set-in-environment` to true. Doing so will fail validation before performing any authentication.\n- Provide a profile name in input option `chain-set-as-profile` to set credentials as a profile.\n- Providing `chain-set-in-environment` as `true`, and `chain-set-as-profile` with a value will both set environment variables and a profile.\n- When neither `chain-set-in-environment` nor `chain-set-as-profile` is provided, credentials are only available as outputs.\n\n```yaml\non:\n  workflow_dispatch:\n\njobs:\n  job1:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n    steps:\n      - id: aws-credentials\n        name: \"Credentials as output only\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"enhanced\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          aws-region: \"eu-west-1\"\n          aws-account-id: \"111111111111\"\n        \n      - name: \"Credentials in environment\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"enhanced\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          aws-region: \"eu-west-1\"\n          aws-account-id: \"111111111111\"\n          set-in-environment: true\n          \n      - name: \"Credentials in profile: tf-state\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"enhanced\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          aws-region: \"eu-west-1\"\n          aws-account-id: \"111111111111\"\n          set-as-profile: \"tf-state\"\n          \n      - name: STS Get Caller Identity\n        run: |\n          aws sts get-caller-identity\n          aws sts get-caller-identity --profile tf-state\n\n      - name: \"STS Get Caller Identity\"\n        env:\n          AWS_ACCESS_KEY_ID: \"${{ steps.aws-credentials.outputs.aws_access_key_id }}\"\n          AWS_SECRET_ACCESS_KEY: \"${{ steps.aws-credentials.outputs.aws_secret_access_key }}\"\n          AWS_SESSION_TOKEN: \"${{ steps.aws-credentials.outputs.aws_session_token }}\"\n        run: |\n          aws sts get-caller-identity\n          \n      - id: oidc_token\n        name: \"Get Cognito OIDC Access Token\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n          auth-flow: \"basic\"\n          cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n          aws-region: \"eu-west-1\"\n          aws-account-id: \"111111111111\"\n\n      - name: \"Assume Role\"\n        env:\n          OIDC_TOKEN: \"${{ steps.oidc_token.outputs.cognito_identity_oidc_access_token }}\"\n          AWS_DEFAULT_REGION: \"eu-west-1\"\n        run: |\n          awsCredentials=$(aws sts assume-role-with-web-identity \\\n          --role-session-name \"MySessionName\" \\\n          --role-arn \"arn:aws:iam::111111111111:role/GhaCognito\" \\\n          --duration-seconds 3600 \\\n          --web-identity-token \"$OIDC_TOKEN\")\n\n          awsAccessKeyId=$(echo \"$awsCredentials\" | jq -r \".Credentials.AccessKeyId\")\n          awsSecretAccessKey=$(echo \"$awsCredentials\" | jq -r \".Credentials.SecretAccessKey\")\n          awsSessionToken=$(echo \"$awsCredentials\" | jq -r \".Credentials.SessionToken\")\n\n          echo \"::add-mask::$awsAccessKeyId\"\n          echo \"::add-mask::$awsSecretAccessKey\"\n          echo \"::add-mask::$awsSessionToken\"\n```\n\n## Custom Role Arn (Enhanced AuthFlow only)\nA custom role arn can be provided during authentication. Read more at https://docs.aws.amazon.com/cognito/latest/developerguide/role-based-access-control.html#using-rules-to-assign-roles-to-users.\n\nInput `role-arn` is the custom role arn when `auth-flow` is also set to `enhanced`.\n\n```yaml\non:\n  workflow_dispatch:\njobs:\n  job1:\n    runs-on: ubuntu-latest\n    permissions:\n      id-token: write\n    steps:\n      - name: \"Authenticate\"\n        uses: catnekaise/cognito-idpool-auth@main\n        with:\n         cognito-identity-pool-id: \"eu-west-1:11111111-example\"\n         auth-flow: \"enhanced\"\n         role-arn: \"arn:aws:iam::111111111111:role/GhaCognitoCustom\"\n         set-in-environment: true\n         aws-region: \"eu-west-1\"\n         aws-account-id: \"111111111111\"\n         \n      - name: STS Get Caller Identity\n        run: |\n          aws sts get-caller-identity\n```\n\n## Use as a Template\nCopy and paste the existing action.yml in this repository to your own repository and customize it as you see fit.\n\n## Use with a wrapper\nUse the \"wrapper-template\" below and pin using of this action to a specific commit.\n\nOptionally set one or more defaults in inputs to reduce amount of repetitive input.\n\n```yaml\nname: Wrapped Cognito Identity Auth\ninputs:\n  aws-account-id:\n    required: false\n    # Optionally set defaults in inputs\n    default: \"111111111111\"\n    description: \"AWS Account ID\"\n  # Copy remaining inputs from ./action.yml\noutputs:\n  aws_access_key_id:\n    description: \"AWS Access Key Id\"\n    value: ${{ steps.auth.outputs.aws_access_key_id }}\n  aws_secret_access_key:\n    description: \"AWS Secret Access Key\"\n    value: ${{ steps.auth.outputs.aws_secret_access_key }}\n  aws_session_token:\n    description: \"AWS Session Name\"\n    value: ${{ steps.auth.outputs.aws_session_token }}\n  aws_region:\n    description: \"AWS Region\"\n    value: ${{ steps.auth.outputs.aws_region }}\n  cognito_identity_oidc_access_token:\n    description: \"Cognito Identity OIDC Access Token\"\n    value: ${{ steps.auth.outputs.cognito_identity_oidc_access_token }}\nruns:\n  using: composite\n  steps:\n    - id: auth\n      uses: catnekaise/cognito-idpool-auth@SHA_HERE\n      with: \n        cognito-identity-pool-id: \"${{ inputs.cognito-identity-pool-id }}\"\n        auth-flow: \"${{ inputs.auth-flow }}\"\n        aws-region: \"${{ inputs-aws-region }}\"\n        audience: \"${{ inputs.audience }}\"\n        aws-account-id: \"${{ inputs.aws-account-id }}\"        \n        role-arn: \"${{ inputs.role-arn }}\"\n        role-duration-seconds: \"${{ inputs.role-duration-seconds }}\"\n        role-session-name: \"${{ inputs.role-session-name }}\"\n        set-as-profile: \"${{ inputs.set-as-profile }}\"\n        set-in-environment: \"${{ inputs.set-in-environment }}\"\n        chain-role-arn: \"${{ inputs.chain-role-arn }}\"\n        chain-role-duration-seconds: \"${{ inputs.chain-role-duration-seconds }}\"\n        chain-role-session-name: \"${{ inputs.chain-role-session-name }}\"\n        chain-pass-claims: \"${{ inputs.chain-pass-claims }}\"\n        chain-set-as-profile: \"${{ inputs.chain-set-as-profile }}\"\n        chain-set-in-environment: \"${{ inputs.chain-set-in-environment }}\"\n```\n\n## Contributing\nContributions are welcome. This action can use more testing and reviews of the large amount of shell scripting.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatnekaise%2Fcognito-idpool-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcatnekaise%2Fcognito-idpool-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcatnekaise%2Fcognito-idpool-auth/lists"}