aws-oidc-cli is a small tool for obtaining short-lived AWS credentials through AWS OIDC federation. For most organizations that can use AWS IAM Identity Center (formerly known as AWS Single Sign-On), I would generally start elsewhere: synfinatic/aws-sso-cli is usually the simpler and more complete fit for that model.

aws-oidc-cli is aimed at a narrower case: environments that need direct federation from an external OIDC provider into AWS roles. In that setting, it offers a straightforward credential_process integration for the AWS CLI while keeping some security and auditability concerns in mind.

AWS IAM Identity Center vs AWS OIDC Federation Link to heading

AWS IAM Identity Center and AWS OIDC federation are easy to blur together, but they solve different problems. AWS IAM Identity Center is AWS’s workforce-access story and is often the simplest option for human access across multiple AWS accounts. AWS OIDC federation is a better fit when an external identity provider needs to be trusted directly and AWS roles need to be assumed through web identity federation.

How It Works Link to heading

aws-oidc-cli plugs into the AWS CLI through credential_process, so it can return ordinary short-lived STS credentials without wrapping every AWS command. The CLI handles the local browser flow, while a small AWS-side service performs the code exchange and STS call. That avoids storing long-lived AWS credentials on disk and avoids leaving OIDC client credentials unencrypted on each client machine. It also produces an AWS session identity tied to the authenticated OIDC user, which is useful for audit purposes.

At a high level, the flow looks like this:

sequenceDiagram actor User as User participant CLI as CLI Tool participant Browser as Browser participant Auth as Lambda /auth participant Creds as Lambda /creds participant IdP as OIDC Provider participant STS as AWS STS User ->>+ CLI: Request creds for account, role CLI ->>+ Browser: Open /auth with state, challenge Browser ->>+ Auth: Request /auth Auth -->>- Browser: Redirect to OIDC auth URL Browser ->>+ IdP: Authenticate user IdP -->>- Browser: Redirect back with code Browser ->>- CLI: Return code CLI ->>+ Creds: Send code, verifier, account, role Creds ->>+ IdP: Exchange code for tokens IdP -->>- Creds: ID token Creds ->>+ STS: AssumeRoleWithWebIdentity STS -->>- Creds: Temporary AWS creds Creds -->>- CLI: Credential_process JSON

If you want the implementation details and setup steps, the project page has the rest: aws-oidc-cli.

Alternatives Link to heading

If AWS IAM Identity Center is available, I would generally start with aws-sso-cli. It is more feature-complete for that model, and it avoids the extra AWS-side deployment that aws-oidc-cli requires.

If Identity Center is not the right fit, there are several other tool alternatives depending on what tradeoffs you are comfortable with:

  • aws-vault is a solid option if wrapping commands with aws-vault exec ... is acceptable, or if duplicating profiles for credential_process use is not a problem.

  • chanzuckerberg/aws-oidc and stensonb/aws-cli-oidc both address similar direct-federation use cases. aws-oidc-cli may be interesting if you want to avoid unencrypted OIDC client credentials on disk and prefer a session identity that is less dependent on locally supplied role-session naming.

The right choice depends on whether AWS IAM Identity Center is available, how much infrastructure you want to manage, and which security and operational tradeoffs matter most in your environment.