rolesanywhere-credential-helper implements the signing process for IAM Roles Anywhere's CreateSession API and returns temporary credentials in a standard JSON format that is compatible with the credential_process feature available across the language SDKs. More information can be found here. It is released and licensed under the Apache License 2.0.
In order to build the source code, you will need to install git, gcc, make, and golang.
On Debian-based systems, you can do so using sudo apt-get install git build-essential golang-go. For other Linux distributions, replace apt-get with the package manager on your system.
You can download Apple clang through the following link if you don't already have it installed on your system. You can install git, make, and golang through Homebrew through brew install git, brew install make and brew install go, respectively.
In order to get gcc on Windows, one option is to use MinGW-w64. After obtaining gcc, you can install golang through the installer. Lastly, you can install git and make through Chocolatey with choco install git and choco install make, respectively.
After obtaining these tools, and making sure they are on your PATH, you can build the package (assuming you are currently at the package root):
make release
After building, you should see the aws_signing_helper binary built for your system at build/bin/aws_signing_helper. Usage can be found in AWS's documentation. A later section also goes into how you can use the scripts provided in this repository to test out the credential helper binary.
The project also comes with two bash scripts at its root, called generate-certs.sh and generate-credential-process-data.sh. The former script is used strictly for unit testing, and it generates certificate and private key data with different parameters that are supported by IAM Roles Anywhere. You can run the bash script using /bin/bash generate-certs.sh, and you will see the generated certificates and keys under the tst/certs directory. The latter script is used both for unit testing and can also be used for testing the credential-process command after having built the binary. It will create a CA certificate/private key as well as a leaf certificate/private key. When testing IAM Roles Anywhere, you will have to upload the CA certificate a trust anchor and create a profile within Roles Anywhere before using the binary along with the leaf certificate/private key to call credential-process (more instructions can be found in the next section). You can run the bash script using /bin/bash generate-credential-process-data.sh, and you will see the generated certificate hierarchy (and corresponding keys) under the credential-process-data directory. Note that the unit tests that require these fixtures to exist will run the bash script themselves, before executing those tests that depend on the fixtures existing. Please note that these scripts currently only work on Unix-based systems and require openssl to be installed.
Reads a certificate that is on disk. The path to the certificate must be provided with the --certificate parameter.
Signs a string from standard input. Useful for validating your on-disk private key and digest. The path to the private key must be provided with the --private-key parameter. Other parameters that can be used are --digest, which must be one of SHA256 (*default*) | SHA384 | SHA512, and --format, which must be one of text (*default*) | json | bin.
Vends temporary credentials by sending a CreateSession request to the Roles Anywhere service. The request is signed by the private key whose path must be provided with the --private-key parameter. Other required parameters include --certificate (the path to the end-entity certificate), --role-arn (the ARN of the role to obtain temporary credentials for), --profile-arn (the ARN of the profile that provides a mapping for the specified role), and --trust-anchor-arn (the ARN of the trust anchor used to authenticate). Optional parameters that can be used are --debug (to provide debugging output about the request sent), --no-verify-ssl (to skip verification of the SSL certificate on the endpoint called), --intermediates (the path to intermediate certificates), --with-proxy (to make the binary proxy aware), --endpoint (the endpoint to call), --region (the region to scope the request to), and --session-duration (the duration of the vended session).
Updates temporary credentials in the credential file. Parameters for this command include those for the credential-process command, as well as --profile, which specifies the named profile for which credentials should be updated (if the profile doesn't already exist, it will be created), and --once, which specifies that credentials should be updated only once. Both arguments are optional. If --profile isn't specified, the default profile will have its credentials updated, and if --once isn't specified, credentials will be continuously updated. In this case, credentials will be updated through a call to CreateSession five minutes before the previous set of credentials are set to expire. Please note that running the update command multiple times, creating multiple processes, may not work as intended. There may be issues with concurrent writes to the credentials file.
Vends temporary credentials through an endpoint running on localhost. Parameters for this command include those for the credential-process command, as well as an optional --port, to specify the port on which the local endpoint will be exposed. By default, the port will be 9911. Once again, credentials will be updated through a call to CreateSession five minutes before the previous set of credentials are set to expire. Note that the URIs and request headers are the same as those used in IMDSv2 (only the address of the endpoint changes from 169.254.169.254 to 127.0.0.1). In order to make the credentials served from the local endpoint available to the SDK, set the AWS_EC2_METADATA_SERVICE_ENDPOINT environment variable appropriately.
The project also comes with two bash scripts at its root, called generate-certs.sh and generate-credential-process-data.sh. Note that these scripts currently only work on Unix-based systems and require openssl to be installed.
Used by unit tests to generate test certificates and private keys supported by IAM Roles Anywhere. The test data is stored in the tst/certs directory.
Used by unit tests and for manual testing of the credential-process command. Creates a CA certificate/private key pair as well as a leaf certificate/private key. Test data is stored in the credential-process-data directory. When testing IAM Roles Anywhere, you will have to upload the CA certificate as a trust anchor and create a profile within Roles Anywhere before using the binary along with the leaf certificate/private key to call credential-process.
/bin/bash generate-credential-process-data.sh
TA_ARN=$(aws rolesanywhere create-trust-anchor \
--name "Test TA" \
--source "sourceType=CERTIFICATE_BUNDLE,sourceData={x509CertificateData=$(cat credential-process-data/root-cert.pem)}" \
--enabled | jq -r '.trustAnchor.trustAnchorArn')
PROFILE_ARN=$(aws rolesanywhere create-profile \
--name "Test Profile" \
--role-arns '["<your-role-arn>"]' \
--enabled | jq -r '.profile.profileArn')
/path/to/aws_signing_helper credential-process \
--certificate credential-process-data/client-cert.pem \
--private-key credential-process-data/client-key.pem \
--role-arn <your-role-arn> \
--trust-anchor-arn ${TA_ARN} \
--profile-arn ${PROFILE_ARN}
In the above example, you will have to create a role with a trust policy as documented here. After having done so, record the role ARN and use it both when creating a profile and when obtaining temporary security credentials through credential-process.
See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.