CLI tool for retrieving AWS temporary credentials using OIDC provider.
AWS Identity Providers and Federation supports IdPs that are compatible with OpenID Connect (OIDC) or SAML 2.0 (Security Assertion Markup Language 2.0). This tool works with both types of IdP if it supports OIDC because it works as OIDC client. If the federation between the AWS account and the IdP is established, and an OIDC client for this tool is registered in the IdP, you can get AWS temporary credentials via standard browser login. It means you don't need to pass your credential of the IdP to this tool.
Please refer the following diagrams how it works.
Note: The OIDC provider must support OAuth 2.0 Token Exchange for exchanging access token/ID token and SAML2 assertion.
Before using this tool, the system administrator need to setup the following configuration.
- Identity Federation using SAML2/OIDC between AWS and the OIDC provider. See https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers.html
- Registration OIDC/OAuth2 client for this CLI tool in the OIDC provider. Note: The OIDC provider must allow any port to be specified at the time of the request for loopback IP redirect URIs because this tool follows RFC 8252 OAuth 2.0 for Native Apps 7.3 Loopback Interface Redirection.
Also depending on the federation type between AWS and the OIDC provider, requirements for the OIDC providers will change.
Note: This tool has been updated to support PKCE.
- The OIDC provider only needs to support OIDC. SAML2 and OAuth 2.0 Token Exchange are not necessary. Very simple.
- However, the JWKS endpoint of the OIDC provider needs to export it to the Internet because AWS try to access the endpoint to obtain the public key and to verify the ID token which is issued by the provider.
- Of course, the OIDC provider must support not only OIDC but also SAML2 for federation between itself and AWS.
- The OIDC provider must support OAuth 2.0 Token Exchange for exchanging access token/ID token and SAML2 assertion.
aws-cli-oidcgets access token/ID token from the OIDC provider first, then it needs to get SAML2 assertion from the provider which is required for getting AWS temporary credentials using AWS STS API.
| OIDC Provider | OIDC | SAML2 |
|---|---|---|
| Google account | OK | - |
| Keycloak | OK | OK (Note 1) |
- Note 1: You need to use Keycloak 12 or higher that supports exchanging from access token to SAML2 assertion. Also, you need to enable Token Exchange feature.
Download from Releases page.
CLI tool for retrieving AWS temporary credentials using OIDC provider
Usage:
aws-cli-oidc [command]
Available Commands:
clear-secret Clear OS secret store that saves AWS credentials
completion generate the autocompletion script for the specified shell
get-cred Get AWS credentials and out to stdout
help Help about any command
setup Interactive setup of aws-cli-oidc
Flags:
-h, --help help for aws-cli-oidc
Use "aws-cli-oidc [command] --help" for more information about a command.
Use aws-cli-oidc setup command and follow the guide.
Use aws-cli-oidc get-cred -p <your oidc provider name> command. It opens your browser.
Now you can see the login page which the OIDC provider offers. Then do login.
If successful, AWS temporary credentials will be shown as below.
aws-cli-oidc get-cred -p myop
Using config file: /home/wadahiro/.aws-cli-oidc/config.yaml
Login successful!
Selected role: arn:aws:iam::123456789012:role/developer
PrincipalARN: arn:aws:iam::123456789012:saml-provider/myop
RoleARN: arn:aws:iam::123456789012:role/developer
export AWS_ACCESS_KEY_ID=ASIAT......
export AWS_SECRET_ACCESS_KEY=9bkS0whPelMYQ.......
export AWS_SESSION_TOKEN=FQoGZXIvYXdzENz.......
Sourcing credentials with an external process describes how to integrate aws-cli with external tool.
You can use aws-cli-oidc as the external process. Add the following lines to your .aws/config file.
[profile foo-developer]
credential_process=aws-cli-oidc get-cred -p myop -r arn:aws:iam::123456789012:role/developer -j -s -d 43200
Caution: The AWS temporary credentials will be saved into your OS secret store by using -s option to reduce authentication each time you use aws-cli tool.
Licensed under the MIT license.