Process credentials - AWS SDKs and Tools

Process credentials

SDKs provide a way to extend the credential provider chain for custom use cases.

Warning

The following describes a method of sourcing credentials from an external process. This can potentially be dangerous, so proceed with caution. Other credential providers should be preferred if at all possible. If using this option, you should make sure that the config file is as locked down as possible using security best practices for your operating system. Confirm that your custom credential tool does not write any secret information to StdErr, because the SDKs and AWS CLI can capture and log such information, potentially exposing it to unauthorized users.

Configure this functionality by using the following:

credential_process - shared AWS config file setting

Specifies an external command that the SDK or tool runs on your behalf to generate or retrieve authentication credentials to use. The setting specifies the name of a program/command that the SDK will invoke. When the SDK invokes the process, it waits for the process to write JSON data to stdout. The custom provider must return information in a specific 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 ( . ), forward slash ( / ), backslash ( \ ), 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 either the full path or a base file name. If there is a base file name, the system attempts to find the program within folders specified by the PATH environment variable.

    Linux/macOS example of setting environment variables via command line:

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

    Windows example of setting environment variables via command line:

    credential_process = "C:\Path\To\credentials.cmd" parameterWithoutSpaces "parameter with spaces"

Valid output from the credentials program

The SDK 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": "RFC3339 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 RFC3339 formatted timestamp. If the Expiration key isn't present in the tool's output, the SDK assumes that the credentials are long-term credentials that don't refresh. Otherwise, the credentials are considered temporary credentials, and they are automatically refreshed by rerunning the credential_process command before the credentials expire.

Note

The SDK 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.

Compatibility with AWS SDKS

The following SDKs support the features and settings described on this page, any partial exceptions are noted: