OIDC Federation vs IAM Roles Anywhere

AWS offers two mechanisms for workload identity without long-lived access keys: OIDC federation (via AssumeRoleWithWebIdentity) and IAM Roles Anywhere (via CreateSession with X.509 certificates). credctl uses OIDC federation. This page explains what each does, how they differ, and why OIDC is a better fit for developer workstations.

How Each Works

OIDC Federation (what credctl uses)

sequenceDiagram
    participant CLI as credctl CLI
    participant SE as Secure Enclave
    participant CF as CloudFront (OIDC Provider)
    participant STS as AWS STS

    CLI->>SE: Sign JWT (ES256)
    SE-->>CLI: Signed JWT
    CLI->>STS: AssumeRoleWithWebIdentity (JWT + role ARN)
    STS->>CF: Fetch /.well-known/openid-configuration
    CF-->>STS: Discovery document
    STS->>CF: Fetch /keys.json
    CF-->>STS: JWKS (device public key)
    STS->>STS: Validate JWT signature against JWKS
    STS-->>CLI: Short-lived STS credentials (1h)

The Secure Enclave signs a JWT (ES256) containing the device identity.
The CLI sends the JWT to STS AssumeRoleWithWebIdentity.
STS fetches the OIDC discovery document and JWKS from a static endpoint (S3 + CloudFront) to verify the JWT signature.
STS returns temporary credentials.

Identity format: JWT signed by the hardware-bound private key. Infrastructure: Two static JSON files hosted on S3 + CloudFront.

IAM Roles Anywhere

sequenceDiagram
    participant CLI as CLI Tool
    participant SE as Secure Enclave
    participant RA as IAM Roles Anywhere

    CLI->>CLI: Build CMS/PKCS#7 signed request
    CLI->>SE: Sign with private key
    SE-->>CLI: Signature
    CLI->>RA: CreateSession (signed request + X.509 cert)
    RA->>RA: Validate cert against Trust Anchor CA
    RA-->>CLI: Short-lived STS credentials (1h)

The tool builds a signed request containing an X.509 certificate.
The Secure Enclave signs the request.
The tool sends the signed request and certificate to the Roles Anywhere CreateSession endpoint.
Roles Anywhere validates the certificate chain against a configured Trust Anchor (CA certificate) and returns temporary credentials.

Identity format: X.509 certificate signed by a Certificate Authority. Infrastructure: A Certificate Authority (CA), Trust Anchor registration, certificate lifecycle management.

Key Differences

	OIDC Federation	IAM Roles Anywhere
Identity format	JWT (JSON Web Token)	X.509 certificate
Signing algorithm	ES256 (ECDSA P-256)	RSA or ECDSA
Infrastructure needed	Two static JSON files on S3 + CloudFront	Certificate Authority, Trust Anchor
Setup complexity	`credctl setup aws` (one CloudFormation stack)	Create CA, issue certs, register Trust Anchor, create profile
Certificate management	None — no certificates involved	Generate, distribute, renew, revoke certificates
Credential lifetime	Configurable (default 1h, max 12h)	Configurable (default 1h, max 12h)
Multi-cloud	Same JWT works with AWS, GCP, and Azure	AWS only
Debugging	Paste JWT into jwt.io	Parse X.509 with openssl
Revocation	Remove IAM OIDC provider or role trust policy	CRL or remove Trust Anchor
AWS API	`AssumeRoleWithWebIdentity`	`CreateSession`

Why credctl Chose OIDC

1. Multi-cloud portability

This is the decisive factor. OIDC is a cross-cloud standard:

AWS accepts OIDC tokens via AssumeRoleWithWebIdentity
GCP accepts OIDC tokens via Workload Identity Federation
Azure accepts OIDC tokens via Federated Identity Credentials

Roles Anywhere is AWS-specific. If credctl used X.509 certificates for AWS, it would still need JWT construction for GCP and Azure — meaning two identity formats, two code paths, and two sets of infrastructure to maintain.

With OIDC, adding GCP support required implementing the GCP-specific token exchange protocol. The JWT construction, Secure Enclave signing, and OIDC provider infrastructure were reused unchanged.

2. No certificate management

X.509 certificates have a lifecycle: generation, distribution, renewal, and revocation. For a developer workstation tool, this is overhead:

Who is the CA? A self-signed CA per developer? A shared team CA?
How are certificates renewed before expiry?
How are certificates revoked when a device is lost?

OIDC sidesteps all of this. The device identity is a public key published as a JWKS. There are no certificates to issue, renew, or revoke. To decommission a device, you delete the CloudFormation stack (or remove the key from the JWKS).

3. Simpler infrastructure

The OIDC provider is two static JSON files:

/.well-known/openid-configuration    (discovery document)
/keys.json                           (JWKS — device public key)

These are hosted on S3 and served via CloudFront. No servers, no dynamic endpoints, no CA infrastructure. credctl setup aws deploys the entire stack with a single CloudFormation template.

Roles Anywhere requires configuring a Trust Anchor with a CA certificate, creating a Profile with role mappings, and managing the certificate chain.

4. Debuggability

JWTs are base64-encoded JSON. You can decode them with jwt.io, jq, or a one-liner:

credctl auth --provider aws --format credential_process 2>/dev/null | \
  jq -r '.SessionToken' | \
  cut -d. -f2 | base64 -d 2>/dev/null | jq .

X.509 certificates require openssl x509 -text and are harder to inspect at a glance.

When Roles Anywhere Makes More Sense

Roles Anywhere isn’t the wrong choice for all scenarios. It can be a better fit when:

You only use AWS and have no plans for GCP or Azure.
You already have a PKI (Certificate Authority) and certificate management tooling in place.
You need certificate-based revocation (CRLs) rather than OIDC provider removal.
You’re running server workloads (not developer workstations) where certificate lifecycle automation is already standard.
You want to avoid hosting any infrastructure — Roles Anywhere doesn’t require an OIDC endpoint.

The Trade-Off

OIDC federation requires hosting a discovery endpoint (S3 + CloudFront, ~$1/month). Roles Anywhere doesn’t require any hosted infrastructure.

For credctl, the small infrastructure cost is worth the multi-cloud portability, zero certificate management, and architectural simplicity. The OIDC foundation means the same device identity works across AWS, GCP, and (soon) Azure without changes.