credential_process - AWS SDKs and Tools

credential_process

Specifies an external command that the SDK or tool runs on your behalf to generate or retrieve authentication credentials to use.

Details

When the SDK or developer tool you're using requires credentials, and you specify a profile that contains this setting, the SDK or tool runs the specified program on your behalf in the background. It must return information in the specified format. That information contains the credentials that the SDK or tool can use to authenticate you.

Specifying the path to the credentials program

The setting's value is a string that contains a path to a program that the SDK or development tool runs on your behalf:

  • The path and file name can consist of only these characters: A-Z, a-z, 0-9, hyphen ( - ), underscore ( _ ), period ( . ), and space.

  • If the path or file name contains a space, surround the complete path and file name with double-quotation marks (" ").

  • If a parameter name or a parameter value contains a space, surround that element with double-quotation marks (" "). Surround only the name or value, not the pair.

  • Don't include any environment variables in the strings. For example, don't include $HOME or %USERPROFILE%.

  • Don't specify the home folder as ~. You must specify the full path.

For examples, see Ways to set this value, later in this topic.

Expected output from the credentials program

The AWS CLI runs the command as specified in the profile and then reads data from the standard output stream. The command you specify, whether a script or binary program, must generate JSON output on STDOUT that matches the following syntax.

{ "Version": 1, "AccessKeyId": "an AWS access key", "SecretAccessKey": "your AWS secret access key", "SessionToken": "the AWS session token for temporary credentials", "Expiration": "ISO8601 timestamp for when the credentials expire" }
Note

As of this writing, the Version key must be set to 1. This might increment over time as the structure evolves.

The Expiration key is an ISO8601 formatted timestamp. If the Expiration key isn't present in the tool's output, the CLI assumes that the credentials are long-term credentials that don't refresh. Otherwise, the credentials are considered temporary credentials and are refreshed automatically by rerunning the credential_process command before they expire.

Note

The AWS CLI does not cache external process credentials the way it does assume-role credentials. If caching is required, you must implement it in the external process.

The external process can return a non-zero return code to indicate that an error occurred while retrieving the credentials.

Ways to set this value

Location Supported Example
config file Yes

Linux or macOS

credential_process = "/path/to/credentials.sh" parameterWithoutSpaces "parameter with spaces"

Windows

credential_process = "C:\Path\To\credentials.cmd" parameterWithoutSpaces "parameter with spaces"
credentials file -
Environment variable -
AWS CLI parameter -

Compatibility with AWS SDKS and tools