Get temporary security credentials from IAM Roles Anywhere - IAM Roles Anywhere
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Get temporary security credentials from IAM Roles Anywhere

To obtain temporary security credentials from Amazon Identity and Access Management Roles Anywhere, use the credential helper tool that IAM Roles Anywhere provides. This tool is compatible with the credential_process feature available across the language SDKs. The helper manages the process of creating a signature with the certificate and calling the endpoint to obtain session credentials; it returns the credentials to the calling process in a standard JSON format. See Temporary security credentials in IAM for more information on session credentials.

To download the credential helper tool, use the following links. Releases for Darwin and Windows on or after version 1.1.1 are signed.

Platform Architecture Download URL SHA256 checksum

Linux

x86-64

https://rolesanywhere.amazonaws.com/releases/1.3.0/X86_64/Linux/aws_signing_helper

a2030e01273ee563166cd8ec52dc04c4561e6763b438bac082427d383d658cb6

Windows

x86-64

https://rolesanywhere.amazonaws.com/releases/1.3.0/X86_64/Windows/aws_signing_helper.exe

14ca7f271e6edd72b2275288c1bf0b500806a9b26815ef37185999fa42a860ad

Darwin

x86-64

https://rolesanywhere.amazonaws.com/releases/1.3.0/X86_64/Darwin/aws_signing_helper

3171839bea76d9014422042b4216bb0fb55e327022d3644456953c8e10515a91

Linux

Aarch64

https://rolesanywhere.amazonaws.com/releases/1.3.0/Aarch64/Linux/aws_signing_helper

8bf2e75f15a8eaeec0d270930625dc7a42dba564c606eac83f5d66caa4058fbe

Darwin

Aarch64

https://rolesanywhere.amazonaws.com/releases/1.3.0/Aarch64/Darwin/aws_signing_helper

495e4b257c1d0deeaa29d9c682482b6e289cceea4f024ebd3615b5b136a46269

Before you can obtain temporary credentials, you must have both an end-entity certificate from the certificate authority and a trust anchor in IAM Roles Anywhere. For more information, see Getting started.

Synopsis

./aws_signing_helper credential-process \ --certificate [--endpoint] [--region] [--intermediates] --private-key --profile-arn --role-arn [--session-duration] --trust-anchor-arn [--with-proxy] [--no-verify-ssl] [--role-session-name]

Options

--certificate (string)

Path to certificate file

--endpoint (string)

The IAM Roles Anywhere endpoint for the region. For a list of endpoints, see Service endpoints and quotas.

--region (string)

Signing region.

--intermediates (string)

Path to intermediate certificate bundle.

--private-key (string)

Path to private key file.

--profile-arn (string)

Profile to pull policies from.

--role-arn (string)

Target role to assume.

--session-duration (int)

Duration, in seconds, for the resulting session (corresponds to the durationSeconds parameter in the CreateSession request). This is optional and can range from 900 seconds (15 minutes) up to 43200 seconds (12 hours). Please see the Expiration subsection of the Credentials Object section for more details on how this value is used in determining the expiration of the vended session.

--trust-anchor-arn (string)

Trust anchor to use for authentication.

--with-proxy

To use the tool with a proxy. This is a boolean flag. Note that you will have to set the HTTPS_PROXY environment variable with the address of the proxy server.

--no-verify-ssl

To disable SSL verification. This is a boolean flag.

Important

Note that this disables TLS host authentication, and can open the connection to man-in-the-middle attacks. This option should only be used under specific, tightly controlled scenarios, such as debugging proxy connections.

--role-session-name

An identifier for the role session. Please see The relationship between CreateSession and AssumeRole section for more details on how this option will affect the CreateSession operation.

Output

The credential helper tool will return a JSON containing the credentials. This format allows the credentials to be consumed by the external credential process supported by the credential_process.

{ "Version":1, "AccessKeyId": String, "SecretAccessKey": String, "SessionToken": String, "Expiration": Timestamp }

Examples

Example Obtain temporary security credentials

To obtain temporary security credentials, use the following command.

$ ./aws_signing_helper credential-process \ --certificate /path/to/certificate \ --private-key /path/to/private-key \ --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \ --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \ --role-arn arn:aws:iam::account:role/role-name-with-path
Example Use temporary security credentials with Amazon SDKs and the Amazon CLI

To use temporary security credentials with Amazon SDKs and the Amazon CLI, you can configure the credential helper tool as a credential process. For more information, see Sourcing credentials with an external process.

The following example shows a the config file that sets the helper tool as the credential process.

[profile developer] credential_process = ./aws_signing_helper credential-process --certificate /path/to/certificate --private-key /path/to/private-key --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID --role-arn arn:aws:iam::account:role/role-name-with-path

Credential Helper on GitHub

The source code for the credential helper is available on GitHub so that you can adapt the helper to your needs. We encourage you to submit pull requests for changes that you would like to have included. However, Amazon doesn't provide support for running modified copies of this software.

Credential Helper Changelog

CredentialHelper version 1.3.0

On November 13, 2024, Amazon IAM Roles Anywhere released Credential Helper version 1.3.0. As a part of this release, TPM keys are supported for non-Windows systems, and a previously unhandled error when parsing certificate data from a file was fixed.

CredentialHelper version 1.2.1

On October 22, 2024, Amazon IAM Roles Anywhere released Credential Helper version 1.2.1. As a part of this release, some security vulnerabilities were patched.

CredentialHelper version 1.2.0

On August 23, 2024, Amazon IAM Roles Anywhere released Credential Helper version 1.2.0. As a part of this release, custom role session name is supported in the CreateSession request, a hop limit option is supported to limit the IP TTL on response packets for the serve command, and file updates for certificate and private key data are recognized by long-running commands and will be honored in subsequent credentialing requests.

CredentialHelper version 1.1.1

On October 12, 2023, Amazon IAM Roles Anywhere released Credential Helper version 1.1.1. As a part of this release, providers in Windows are attempted to be silenced when performing signing operations. Also, Windows user certificate store names can now be explicitly provided.

CredentialHelper version 1.1.0

On September 20, 2023, Amazon IAM Roles Anywhere released Credential Helper version 1.1.0. As a part of this release, PKCS#11 module integration is now supported. Also, any debug logs that previously went to stderr now go to stdout.

CredentialHelper version 1.0.6

On August 16, 2023, Amazon IAM Roles Anywhere released Credential Helper version 1.0.6. As a part of this release, certificates within OS secure stores that can't be parsed are now skipped. An issue relating to mismatched regions in the ARN inputs is also now fixed.

CredentialHelper version 1.0.5

On July 25, 2023, Amazon IAM Roles Anywhere released Credential Helper version 1.0.5. As a part of this release, some bugs relating to the update command were fixed. PKCS#12 containers that aren't password-protected are now supported. Lastly, MacOS Keychain Access and Windows CNG/CryptoAPI integrations are also now supported.

CredentialHelper version 1.0.4

On January 17, 2023, Amazon IAM Roles Anywhere released Credential Helper version 1.0.4. As a part of this release, some bugs specific to the serve command were fixed.

CredentialHelper version 1.0.3

On December 5, 2022, Amazon IAM Roles Anywhere released Credential Helper version 1.0.3. As a part of this release, the tool now supports the update and serve commands.

CredentialHelper version 1.0.2

On September 8, 2022, Amazon IAM Roles Anywhere released Credential Helper version 1.0.2. As a part of this release, the tool now sets the minimum TLS version to 1.2.

CredentialHelper version 1.0.1

On July 14, 2022, Amazon IAM Roles Anywhere released Credential Helper version 1.0.1. As a part of this release, the tool now has better error handling.