{"id":13602632,"url":"https://github.com/saml-to/assume-aws-role-action","last_synced_at":"2025-04-11T09:30:40.343Z","repository":{"id":44914934,"uuid":"445429736","full_name":"saml-to/assume-aws-role-action","owner":"saml-to","description":"Assume AWS IAM Roles using SAML.to in GitHub Actions","archived":false,"fork":false,"pushed_at":"2024-01-09T14:28:52.000Z","size":2013,"stargazers_count":182,"open_issues_count":10,"forks_count":6,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-07T05:39:49.584Z","etag":null,"topics":["assume","assume-role","aws","aws-iam","github-actions","saml","saml-to","scaffoldly"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/saml-to.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"publiccode":null,"codemeta":null}},"created_at":"2022-01-07T07:03:28.000Z","updated_at":"2024-07-18T14:49:45.000Z","dependencies_parsed_at":"2024-01-18T05:15:17.438Z","dependency_job_id":"cccb3a07-0bac-4783-b023-e148a8ef3e43","html_url":"https://github.com/saml-to/assume-aws-role-action","commit_stats":{"total_commits":175,"total_committers":4,"mean_commits":43.75,"dds":0.5085714285714286,"last_synced_commit":"27e89d88ed0bf09ea85e9fe73d70516b91894e15"},"previous_names":[],"tags_count":83,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-to%2Fassume-aws-role-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-to%2Fassume-aws-role-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-to%2Fassume-aws-role-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/saml-to%2Fassume-aws-role-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/saml-to","download_url":"https://codeload.github.com/saml-to/assume-aws-role-action/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248368167,"owners_count":21092312,"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":["assume","assume-role","aws","aws-iam","github-actions","saml","saml-to","scaffoldly"],"created_at":"2024-08-01T18:01:32.261Z","updated_at":"2025-04-11T09:30:39.946Z","avatar_url":"https://github.com/saml-to.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","aws"],"sub_categories":[],"readme":"# assume-aws-role-action\n\n![GitHub release (latest by date)](https://img.shields.io/github/v/release/saml-to/assume-aws-role-action?label=version) ![GitHub issues](https://img.shields.io/github/issues/saml-to/assume-aws-role-action) ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/saml-to/assume-aws-role-action/Push%20to%20Main) [![Gitter](https://img.shields.io/gitter/room/saml-to/assume-aws-role-action)](https://gitter.im/saml-to/assume-aws-role-action)\n\nThis action enables workflows to obtain AWS Access Credentials for a desired IAM Role using **AWS IAM SAML** and a **GitHub Actions Repository Token**.\n\nBenefits:\n\n- No need to copy/paste AWS Access Tokens into GitHub Secrets\n- No need to rotate AWS Access Tokens\n\nThis action uses [SAML.to](https://saml.to) and an [AWS IAM Identity Provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_saml.html) to exchange a [GitHub Actions Token](https://docs.github.com/en/actions/security-guides/automatic-token-authentication) for AWS Access Credentials.\n\nThis action will set the following environment variables:\n\n- `AWS_ACCESS_KEY_ID`\n- `AWS_SECRET_ACCESS_KEY`\n- `AWS_SESSION_TOKEN`\n- `AWS_DEFAULT_REGION`\n\n## Usage\n\nSee [action.yml](action.yml)\n\n```yaml\nsteps:\n  - uses: saml-to/assume-aws-role-action@v1\n    with:\n      role: arn:aws:iam::123456789012:role/admin\n    env:\n      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n  - run: aws sts get-caller-identity\n  - run: aws ec2 describe-instances\n```\n\n## Examples\n\nSee [aws-assume-role-action-examples](https://github.com/saml-to/aws-assume-role-action-examples)\n\n## Configuration\n\n1. [Download Your Metadata](https://saml.to/metadata) from SAML.to\n1. Create a new **SAML** [Identity Provider](https://console.aws.amazon.com/iamv2/home?#/identity_providers/create) in AWS IAM\n   1. **Provider Name**: _Repository Name_ (the name of the repository running the action)\n   1. **Metadata Document**: _Upload the Metadata Document from SAML.to_\n   1. Make note of the **`Provder ARN`** in the AWS console\n1. Create or update the [Trust Relationship](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/edit_trust.html) on a new or existing IAM Role to contain the following:\n   ```\n   {\n     \"Version\": \"2012-10-17\",\n     \"Statement\": [\n       {\n         \"Effect\": \"Allow\",\n         \"Principal\": {\n           \"Federated\": \"PROVIDER_ARN\"\n         },\n         \"Action\": \"sts:AssumeRoleWithSAML\",\n         \"Condition\": {\n           \"StringEquals\": {\n             \"SAML:aud\": \"https://signin.aws.amazon.com/saml\"\n           }\n         }\n       }\n     ]\n   }\n   ```\n   - Replace `PROVIDER_ARN` with the newly created ARN of the provider, e.g. `arn:aws:iam::123456789012:saml-provider/my-repository`\n   - Make note of the **`Role ARN`** for this Role\n1. Add a new file named _`saml-to.yml`_ to the repository that needs AWS Access Credentials during GitHub Actions:\n\n   `your-repository/saml-to.yml`:\n\n   ```\n   ---\n   version: \"20220101\"\n   variables:\n     awsProviderArn: \"PROVIDER_ARN\"\n     awsRoleArn: \"ROLE_ARN\"\n   providers:\n     aws:\n       entityId: https://signin.aws.amazon.com/saml\n       acsUrl: https://signin.aws.amazon.com/saml\n       attributes:\n         https://aws.amazon.com/SAML/Attributes/RoleSessionName: \"\u003c#= repo.name #\u003e\"\n         https://aws.amazon.com/SAML/Attributes/SessionDuration: \"3600\"\n         https://aws.amazon.com/SAML/Attributes/Role: \"\u003c#= repo.selectedRole #\u003e,\u003c$= awsProviderArn $\u003e\"\n   permissions:\n     aws:\n       roles:\n         - name: \u003c$= awsRoleArn $\u003e\n           self: true\n   ```\n\n   - Replace `PROVIDER_ARN` with the ARN of the provider created above (e.g. `arn:aws:iam::123456689012:saml-provider/my-repository`)\n   - Replace `ROLE_ARN` with the ARN of the IAM Role modified above. (e.g. `arn:aws:iam::123456689012:role/admin`)\n\n1. Modify the GitHub Action Workflow to obtain AWS Access Credentials\n\n   `your-repository/.github/workflows/action-name.yml`:\n\n   ```\n      jobs:\n        prerelease:\n          runs-on: ubuntu-latest\n          steps:\n            - uses: actions/checkout@v2\n            ...\n            - uses: saml-to/assume-aws-role-action@v1\n              env:\n                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n              with:\n                role: \"ROLE_ARN\"\n            ...\n   ```\n\n   - Replace `ROLE_ARN` with the ARN of the IAM Role modified above. (e.g. `arn:aws:iam::123456689012:role/admin`)\n\n## Inputs\n\n### `role` (**Required**)\n\nThe ARN of the role to assume. This Role ARN must also be defined in the `saml-to.yml` configuration file under `permissions`.\n\n### `region` (_Optional_)\n\nThe AWS Region to use. This will also be set as the `AWS_DEFAULT_REGION` environment variable and the `region` output.\n\n**Default**: `us-east-1`\n\n### `provider` (_Optional_)\n\nIf there are multiple `provider` entries in the `saml-to.yml` configuration file, set a specific provider.\n\n**Note**: If multiple providers are configured, and this is absent, the Action will fail.\n\n**Default**: `` (_Empty String_)\n\n### `configPath` (_Optional_)\n\nSpecify an alternative path to the `saml-to.yml` configuration file.\n\n### `profile` (_Optional_)\n\nStore the credentials to the provided named profile in `~/.aws` (instead of writing them to Environment Variables)\n\n**Default**: `` (_Empty String_)\n\n**Default**: `saml-to.yml`\n\n## Outputs\n\n### `region`\n\nThe AWS Region authenitcated with (default: `us-east-1`)\n\nCan be modified with the `region` input.\n\nThis will also be set in the `AWS_DEFAULT_REGION` environment variable.\n\n### `accountId`\n\nThe AWS Account ID authenticated with (e.g. `123456789012`)\n\n### `userId`\n\nThe ephemeral user ID (e.g. `AROAYOAAAAAAAAAAAAAAA:my-repository`)\n\n### `roleArn`\n\nThe ARN of the Role.\n\nIt will be identical to the `role` input.\n\n### `assumedRoleArn`\n\nThe effective ARN of the Assumed Role (e.g. `arn:aws:sts::123456789012:assumed-role/admin/my-repository`)\n\n### `accessKeyId`\n\nThe generated AWS Access Key ID.\n\nThis is also be set in the `AWS_ACCESS_KEY_ID` environment variable.\n\n### `secretAccessKey`\n\nThe generated AWS Secret Access Key.\n\nThis is also be set in the `AWS_SECRET_ACCESS_KEY` environment variable.\n\n### `sessionToken`\n\nThe generated AWS Session Toke.\n\nThis is also be set in the `AWS_SESSION_TOKEN` environment variable.\n\n## FAQs\n\nSee [FAQs](FAQS.md)\n\n## Maintainers\n\n- [Scaffoldly](https://github.com/scaffoldly)\n- [cnuss](https://github.com/cnuss)\n\n## Help \u0026 Support\n\n- [Message us on Gitter](https://gitter.im/saml-to/assume-aws-role-action)\n- [Support via Twitter](https://twitter.com/SamlToSupport)\n- [Discussions](https://github.com/saml-to/assume-aws-role-action/discussions)\n\n## License\n\n[Apache-2.0 License](LICENSE)\n\n![](https://sso.saml.to/github/px?action)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaml-to%2Fassume-aws-role-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsaml-to%2Fassume-aws-role-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsaml-to%2Fassume-aws-role-action/lists"}