{"id":19391089,"url":"https://github.com/spiffe/aws-spiffe-workload-helper","last_synced_at":"2026-02-17T00:06:09.483Z","repository":{"id":258280589,"uuid":"873586618","full_name":"spiffe/aws-spiffe-workload-helper","owner":"spiffe","description":"AWS SPIFFE Workload Helper is a light-weight tool intended to assist in providing a workload with credentials for AWS using its SPIFFE identity.","archived":false,"fork":false,"pushed_at":"2025-07-23T12:38:47.000Z","size":89,"stargazers_count":9,"open_issues_count":4,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-07-23T14:36:30.078Z","etag":null,"topics":["aws","spiffe","workload-identity","workload-identity-federation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spiffe.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,"zenodo":null}},"created_at":"2024-10-16T12:20:10.000Z","updated_at":"2025-07-23T12:31:06.000Z","dependencies_parsed_at":"2025-04-14T03:51:38.983Z","dependency_job_id":"1c627cca-61dc-4c86-88f8-2a1096346fde","html_url":"https://github.com/spiffe/aws-spiffe-workload-helper","commit_stats":null,"previous_names":["spiffe/aws-spiffe-workload-helper"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/spiffe/aws-spiffe-workload-helper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Faws-spiffe-workload-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Faws-spiffe-workload-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Faws-spiffe-workload-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Faws-spiffe-workload-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spiffe","download_url":"https://codeload.github.com/spiffe/aws-spiffe-workload-helper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spiffe%2Faws-spiffe-workload-helper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274956108,"owners_count":25380670,"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","status":"online","status_checked_at":"2025-09-13T02:00:10.085Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["aws","spiffe","workload-identity","workload-identity-federation"],"created_at":"2024-11-10T10:24:39.385Z","updated_at":"2026-02-17T00:06:09.436Z","avatar_url":"https://github.com/spiffe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AWS SPIFFE Workload Helper\n\n[![Apache 2.0 License](https://img.shields.io/github/license/spiffe/helm-charts)](https://opensource.org/licenses/Apache-2.0)\n[![Development Phase](https://github.com/spiffe/spiffe/blob/main/.img/maturity/dev.svg)](https://github.com/spiffe/spiffe/blob/main/MATURITY.md#development)\n\nAWS SPIFFE Workload Helper is a light-weight tool intended to assist in\nproviding a workload with credentials for AWS using its SPIFFE identity.\n\nIt provides a more native experience when using SPIFFE identities compared to\nthe [`rolesanywhere-credential-helper`](https://github.com/aws/rolesanywhere-credential-helper)\nreleased by AWS, and is intended to be used in place of\n`rolesanywhere-credential-helper`.\n\nCurrently, the helper only supports authenticating to AWS using an X.509 SVID\nvia [AWS Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html).\n\n## Usage\n\n### Getting Started\n\nFollow the guidance at\n\u003chttps://docs.aws.amazon.com/rolesanywhere/latest/userguide/getting-started.html\u003e\nand substitute the usage of `rolesanywhere-credential-helper` with this utility.\n\n### Installation\n\n#### Binary\n\nThe `aws-spiffe-workload-helper` binary is available for a range of\narchitectures within the\n[GitHub Releases](https://github.com/spiffe/aws-spiffe-workload-helper/releases)\nof this repository.\n\nDownload the appropriate artifact for your architecture, and extract the\n.tar.gz. The binary can then be placed somewhere on the system where it will be\naccessible to workloads that use the AWS SDKs or CLIs. It may be beneficial to\nensure it is in a location that is within your PATH.\n\n#### OCI Image\n\nThe `aws-spiffe-workload-helper` is also distributed within an OCI image. This\nmay be useful as a source of the binary if you are building your own image and\nrequire this binary within it.\n\nThese images are published to the GitHub Container Registry: [ghcr.io/spiffe/aws-spiffe-workload-helper:latest](https://github.com/spiffe/aws-spiffe-workload-helper/pkgs/container/aws-spiffe-workload-helper)\n\n```dockerfile\nCOPY --from=ghcr.io/spiffe/aws-spiffe-workload-helper:latest /ko-app/cmd /aws-spiffe-workload-helper\n```\n\n### CLI Commands\n\n#### `x509-credential-process`\n\nThe `x509-credential-process` command exchanges an X509 SVID for a short-lived\nset of AWS credentials using the AWS Roles Anywhere API. It returns the\ncredentials to STDOUT, in the format expected by AWS SDKs and CLIs when invoking\nan external credential process.\n\nThe command fetches the X509-SVID from the SPIFFE Workload API. The location of\nthe SPIFFE Workload API endpoint should be specified using the\n`SPIFFE_ENDPOINT_SOCKET` environment variable or the `--workload-api-addr` flag.\n\nExample usage:\n\n```sh\n$ aws-spiffe-workload-helper x509-credential-process \\\n    --trust-anchor-arn arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/0000000-0000-0000-0000-000000000000 \\\n    --profile-arn arn:aws:rolesanywhere:us-east-1:123456789012:profile/0000000-0000-0000-0000-000000000000 \\\n    --role-arn arn:aws:iam::123456789012:role/example-role \\\n    --workload-api-addr unix:///opt/workload-api.sock\n```\n\n##### Reference\n\n| Flag              | Required | Description                                                                                                                                                                              | Example                                                                                         |\n|-------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|\n| role-arn          | Yes      | The ARN of the role to assume. Required.                                                                                                                                                 | `arn:aws:iam::123456789012:role/example-role`                                                   |\n| profile-arn       | Yes      | The ARN of the Roles Anywhere profile to use. Required.                                                                                                                                  | `arn:aws:rolesanywhere:us-east-1:123456789012:profile/0000000-0000-0000-0000-00000000000`       |\n| trust-anchor-arn  | Yes      | The ARN of the Roles Anywhere trust anchor to use. Required.                                                                                                                             | `arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/0000000-0000-0000-0000-000000000000` |\n| region            | No       | Overrides AWS region to use when exchanging the SVID for AWS credentials. Optional.                                                                                                      | `us-east-1`                                                                                     |\n| session-duration  | No       | The duration, in seconds, of the resulting session. Optional. Can range from 15 minutes (900) to 12 hours (43200).                                                                       | `3600`                                                                                          |\n| workload-api-addr | No       | Overrides the address of the Workload API endpoint that will be use to fetch the X509 SVID. If unspecified, the value from the SPIFFE_ENDPOINT_SOCKET environment variable will be used. | `unix:///opt/my/path/workload.sock`                                                             |\n\n#### `x509-credential-file`\n\nThe `x509-credential-file` command starts a long-lived daemon which exchanges\nan X509 SVID for a short-lived set of AWS credentials using the AWS Roles\nAnywhere API. It writes the credentials to a specified file in the format \nsupported by AWS SDKs and CLIs as a \"credential file\".\n\nIt repeats this exchange process when the AWS credentials are more than 50% of\nthe way through their lifetime, ensuring that a fresh set of credentials are\nalways available.\n\nWhilst the `x509-credentials-process` flow should be preferred as it does not \ncause credentials to be written to the filesystem, the `x509-credentials-file`\nflow may be useful in scenarios where you need to provide credentials to legacy\nSDKs or CLIs that do not support the `credential_process` configuration.\n\nThe command fetches the X509-SVID from the SPIFFE Workload API. The location of\nthe SPIFFE Workload API endpoint should be specified using the\n`SPIFFE_ENDPOINT_SOCKET` environment variable or the `--workload-api-addr` flag.\n\n```sh\n$ aws-spiffe-workload-helper x509-credential-file \\\n    --trust-anchor-arn arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/0000000-0000-0000-0000-000000000000 \\\n    --profile-arn arn:aws:rolesanywhere:us-east-1:123456789012:profile/0000000-0000-0000-0000-000000000000 \\\n    --role-arn arn:aws:iam::123456789012:role/example-role \\\n    --workload-api-addr unix:///opt/workload-api.sock \\\n    --aws-credentials-path /opt/my-aws-credentials-file\n```\n\n###### Reference\n\n| Flag                 | Required | Description                                                                                                                                                                              | Example                                                                                         |\n|----------------------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------|\n| role-arn             | Yes      | The ARN of the role to assume. Required.                                                                                                                                                 | `arn:aws:iam::123456789012:role/example-role`                                                   |\n| profile-arn          | Yes      | The ARN of the Roles Anywhere profile to use. Required.                                                                                                                                  | `arn:aws:rolesanywhere:us-east-1:123456789012:profile/0000000-0000-0000-0000-00000000000`       |\n| trust-anchor-arn     | Yes      | The ARN of the Roles Anywhere trust anchor to use. Required.                                                                                                                             | `arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/0000000-0000-0000-0000-000000000000` |\n| region               | No       | Overrides AWS region to use when exchanging the SVID for AWS credentials. Optional.                                                                                                      | `us-east-1`                                                                                     |\n| session-duration     | No       | The duration, in seconds, of the resulting session. Optional. Can range from 15 minutes (900) to 12 hours (43200).                                                                       | `3600`                                                                                          |\n| workload-api-addr    | No       | Overrides the address of the Workload API endpoint that will be use to fetch the X509 SVID. If unspecified, the value from the SPIFFE_ENDPOINT_SOCKET environment variable will be used. | `unix:///opt/my/path/workload.sock`                                                             |\n| aws-credentials-path | Yes      | The path to the AWS credentials file to write.                                                                                                                                           | `/opt/my-aws-credentials-file`                                                                  |\n| force                | No       | If set, failures loading the existing AWS credentials file will be ignored and the contents overwritten.                                                                                 |                                                                                                 |\n| replace              | No       | If set, the AWS credentials file will be replaced if it exists. This will remove any profiles not written by this tool.                                                                  |                                                                                                 |\n\n## Configuring AWS SDKs and CLIs\n\nTo configure AWS SDKs and CLIs to use Roles Anywhere and SPIFFE for\nauthentication, you will modify the AWS configuration file.\n\nBy default, AWS SDKs and CLIs will expect this file to be located at \n`~/.aws/config`. This location can be customized using the `AWS_CONFIG_FILE`\nenvironment variable.\n\nExample configuration:\n\n```toml\n[default]\ncredential_process = /usr/bin/aws-spiffe-workload-helper x509-credential-process --profile-arn arn:aws:rolesanywhere:us-east-1:123456789012:profile/0000000-0000-0000-0000-000000000000\n--trust-anchor-arn arn:aws:rolesanywhere:us-east-1:123456789012:trust-anchor/0000000-0000-0000-0000-000000000000 --role-arn arn:aws:iam::123456789012:role/example-role\n```\n\nYou can learn more about external credential processes at\n\u003chttps://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sourcing-external.html\u003e\n\n## Contributing\n\nWe welcome contributions to this project. If you require any assistance, please\nget in contact via the SPIFFE Slack.\n\n### Governance\n\nThis is a [\"tiny-project\"](https://github.com/spiffe/spiffe/blob/main/NEW_PROJECTS.md#tiny-projects).\n\nDispute resolution is handled via escalation to the [SPIFFE Steering Committee (SSC)](https://github.com/spiffe/spiffe/blob/main/GOVERNANCE.md#the-spiffe-steering-committee-ssc).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiffe%2Faws-spiffe-workload-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspiffe%2Faws-spiffe-workload-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspiffe%2Faws-spiffe-workload-helper/lists"}