credctl | Blog

credctl Now Supports GCP: One Hardware Identity, Two Clouds

Mon, 23 Mar 2026 00:00:00 GMT

When we launched credctl, the pitch was simple: replace the plaintext AWS keys on your laptop with hardware-bound credentials using the Secure Enclave. No keys on disk. Ever.

Today, we’re extending that to GCP.

credctl auth --provider gcp exchanges the same hardware-bound JWT for short-lived GCP access tokens via Workload Identity Federation. Same Secure Enclave key. Same OIDC provider. No new infrastructure. No GCP SDK dependency.

Why This Matters

If you work across AWS and GCP — and an increasing number of teams do — you now have a single device identity that works with both clouds. One credctl init, one OIDC provider, two clouds.

The security model is identical to AWS:

Private key lives in the Secure Enclave. Can’t be exported.
Credentials are short-lived (1 hour).
Touch ID required for every signing operation.
Nothing on disk to steal.

The difference is in the exchange mechanism. AWS uses a single AssumeRoleWithWebIdentity call. GCP uses a two-step exchange:

sequenceDiagram
    participant CLI as credctl CLI
    participant SE as Secure Enclave
    participant STS as GCP STS
    participant IAM as GCP IAM Credentials

    CLI->>SE: Sign JWT (Touch ID)
    SE-->>CLI: Signed JWT
    CLI->>STS: ExchangeToken (JWT)
    STS-->>CLI: Federated access token
    CLI->>IAM: GenerateAccessToken
    IAM-->>CLI: OAuth2 access token (1h)

The CLI signs a JWT with the Secure Enclave key (same as AWS, but with GCP’s Workload Identity Provider URI as the audience).
GCP STS validates the JWT against the OIDC provider and returns a federated access token.
The CLI exchanges the federated token for a service account access token via the IAM Credentials API.

The result: a standard GCP OAuth2 access token, usable with gcloud, Terraform, and all GCP client libraries.

Setup: Five Minutes

Prerequisites

You need credctl installed and initialised (credctl init), and AWS OIDC infrastructure deployed (credctl setup aws). GCP reuses the same OIDC provider — the CloudFront-hosted discovery documents that AWS validates are the same ones GCP validates.

You also need a GCP service account with the roles you want credctl to assume.

Step 1: Set up GCP federation

credctl setup gcp --service-account credctl@my-project.iam.gserviceaccount.com

This single command handles everything: OIDC hosting on GCS, Workload Identity Pool, OIDC Provider, service account binding, and generating the credential config file at ~/.credctl/gcp-credentials.json.

Step 2: Use it

export GOOGLE_APPLICATION_CREDENTIALS=~/.credctl/gcp-credentials.json
gcloud storage ls

Or authenticate gcloud directly:

gcloud auth login --cred-file=~/.credctl/gcp-credentials.json

That’s it. Every GCP API call now uses hardware-bound, short-lived credentials.

Terraform for Teams

If your team prefers infrastructure-as-code over CLI setup, there’s a Terraform module at deploy/terraform-gcp/:

module "credctl_gcp" {
  source = "github.com/credctl/credctl//deploy/terraform-gcp"

  project_id         = "my-project"
  device_fingerprint = "SHA256:oKz3i9Tg..."
  issuer_url         = "https://d1234.cloudfront.net"

  service_account_roles = [
    "roles/storage.objectViewer",
    "roles/bigquery.dataViewer",
  ]
}

This creates the same resources as credctl setup gcp — Workload Identity Pool, OIDC Provider, Service Account, and IAM bindings — but version-controlled and repeatable.

No GCP SDK

One design decision worth highlighting: credctl has zero GCP SDK dependency. The GCP STS token exchange and IAM Credentials API calls are implemented with Go’s net/http stdlib. This keeps the binary small, the dependency tree minimal, and the attack surface narrow.

The same is true for AWS — credctl’s only external Go dependency is spf13/cobra for CLI argument parsing.

How the OIDC Architecture Made This Easy

When we chose OIDC federation over AWS Roles Anywhere (see the technical deep dive), cross-cloud portability was a key reason. OIDC is a standard. AWS, GCP, and Azure all accept OIDC tokens for credential exchange. By building on OIDC, adding GCP support meant implementing the GCP-specific exchange protocol — not rebuilding identity infrastructure.

The only code change to the shared JWT package was making the audience claim configurable. AWS uses sts.amazonaws.com. GCP uses the Workload Identity Provider URI. Same key, same signature, different audience.

What’s Next

Azure Federated Identity Credentials — the third major cloud. Same OIDC architecture, Azure-specific exchange.
Linux TPM 2.0 — the same multi-cloud identity on Linux workstations.
Credential caching daemon — avoid redundant STS calls and Touch ID prompts within the credential TTL. (This is already available as an experimental feature: credctl daemon start.)

Try It

Update to the latest credctl:

brew upgrade credctl/tap/credctl

GCP setup guide: credctl.com/guides/gcp-setup
GitHub: github.com/credctl/credctl
Quickstart: credctl.com/quickstart

If you’re using credctl with both AWS and GCP, we’d love to hear about your experience. Open an issue or start a discussion on GitHub.

Stay up to date

Get notified about new credctl releases, security best practices, and hardware identity insights.

credctl: Eliminating Plaintext Cloud Keys with the Secure Enclave

Sat, 07 Mar 2026 00:00:00 GMT

The Problem Nobody Talks About

Here’s a number that should keep you up at night: 86% of breaches involve stolen credentials. In 2025 alone, infostealer malware exfiltrated 1.8 billion credentials from 5.8 million devices — an 800% surge over recent years.

And where are your cloud credentials right now?

If you’re like most developers, the answer is ~/.aws/credentials. A plaintext file. On your laptop. Readable by any process running as your user.

[default]
aws_access_key_id = AKIAIOSFODNN7EXAMPLE
aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

That file is the single most common credential pattern in cloud computing. It never expires. It works from any machine. And it can be stolen by any malware with file access, copied from disk images, committed to dotfile repos, or extracted from a stolen laptop.

Think about what that means in practice. You install a VS Code extension, a Homebrew package, or a Python library — any of them could read ~/.aws/credentials silently. You back up your disk, and those keys are in the backup. You sell your old laptop and don’t wipe it properly, and those keys go with it. You share your dotfiles on GitHub and accidentally include your credentials directory.

The breach data tells the same story, over and over:

CircleCI (2023): Malware on a developer laptop exfiltrated a session cookie. The attacker accessed production systems and forced all customers to rotate their secrets.
LastPass (2022): A developer workstation was compromised. Credentials from the first breach were used to access cloud storage containing customer vault backups. The result was one of the most catastrophic data breaches in password manager history.
Okta (2023): A stolen service account credential, stored in a personal Google account synced from a company device, gave attackers access to every customer’s support case files.
Uber (2022): Stolen contractor credentials combined with MFA fatigue bombing compromised internal systems. The former CISO was criminally convicted.
Codecov (2021): A modified CI script exfiltrated environment variables — including credentials — from thousands of downstream customers.

Every one of these traces back to the same pattern: long-lived credentials accessible on a developer machine. The attackers aren’t breaking encryption or exploiting zero-days. They’re reading files.

The Gap That Shouldn’t Exist

Here’s what’s strange. Your Mac has had a Secure Enclave since 2016. It’s a hardware security module — a dedicated chip that generates cryptographic keys, stores them in hardware, and never allows them to be exported. The private key physically cannot leave the chip. Not by malware, not by root access, not by forensic disk imaging.

Your Mac uses the Secure Enclave for Touch ID, Apple Pay, and FileVault. Banks use it. Governments use it. Apple’s corecrypto module is FIPS 140-2 validated.

Meanwhile, AWS has supported OIDC federation since 2014. Any service that can produce a signed JWT can exchange it for short-lived STS credentials via AssumeRoleWithWebIdentity. No long-lived keys required.

The Secure Enclave can sign JWTs. AWS can accept them. Nothing connected the two.

That’s the gap credctl fills.

What credctl Does

credctl uses your Mac’s Secure Enclave to replace long-lived cloud access keys with short-lived, hardware-bound credentials. It works with both AWS and GCP today, with Azure on the roadmap.

The private key lives in the Secure Enclave — it can never be exported, copied, or stolen. When you need AWS credentials, credctl signs a JWT with that hardware-bound key and exchanges it for short-lived STS credentials via OIDC federation. The credentials last one hour. There’s nothing on disk to steal.

$ credctl init
✓ Generated ECDSA P-256 key pair in Secure Enclave
✓ Exported public key to ~/.credctl/device.pub
✓ Device ID: SHA256:oKz3i9Tg...

$ credctl setup aws --policy-arn arn:aws:iam::123456789012:policy/DevAccess
✓ Deployed CloudFormation stack (S3, CloudFront, OIDC provider, IAM role)
✓ OIDC issuer URL: https://d1234.cloudfront.net

$ credctl auth
✓ Built JWT (iss=https://d1234.cloudfront.net, sub=SHA256:oKz3i9Tg...)
✓ Signed with Secure Enclave (Touch ID)
✓ Exchanged for STS credentials (expires in 1h)

export AWS_ACCESS_KEY_ID=ASIA...
export AWS_SECRET_ACCESS_KEY=...
export AWS_SESSION_TOKEN=...

That’s it. Five minutes from install to working credentials. No server infrastructure. No SSO portal. No browser redirects.

How It Works

The architecture is straightforward:

sequenceDiagram
    participant Dev as Developer
    participant CLI as credctl CLI
    participant SE as Secure Enclave
    participant STS as AWS STS
    participant OIDC as OIDC Provider<br/>(S3 + CloudFront)

    Dev->>CLI: credctl auth
    CLI->>CLI: Build JWT (iss, sub, aud)
    CLI->>SE: Sign JWT (ECDSA P-256 / ES256)
    SE-->>CLI: Signed JWT
    CLI->>STS: AssumeRoleWithWebIdentity
    STS->>OIDC: Fetch JWKS (public key)
    STS->>STS: Validate signature, assume role
    STS-->>CLI: Short-lived credentials (1h)
    CLI-->>Dev: AWS credentials

credctl init generates an ECDSA P-256 key pair inside the Secure Enclave. The private key never leaves the hardware. The public key is exported.
credctl setup aws creates an S3 bucket to host OIDC discovery documents, an IAM OIDC identity provider that trusts the issuer URL, an IAM role configured for web identity federation, and configures the AWS CLI profile — all in a single command.
credctl auth builds a JWT with your issuer URL, device ID, and sts.amazonaws.com as the audience. The Secure Enclave signs it (Touch ID prompt). The CLI sends it to STS via AssumeRoleWithWebIdentity. STS fetches your JWKS, validates the signature, and returns short-lived credentials.

The CLI is written in Go. The Secure Enclave integration uses cgo to call Apple’s Security framework directly (SecKeyCreateRandomKey, SecKeyCreateSignature). The STS call is a raw HTTP POST — no AWS SDK dependency. The only external dependency is spf13/cobra for CLI argument parsing.

Multi-Cloud: AWS and GCP Today

credctl’s OIDC architecture was designed for cross-cloud portability from the start. The same Secure Enclave key and OIDC provider work with both AWS and GCP.

GCP setup is just as simple:

$ credctl setup gcp --service-account credctl@my-project.iam.gserviceaccount.com
✓ Created Workload Identity Pool
✓ Created OIDC Provider (using existing issuer URL)
✓ Bound service account to device identity

$ credctl setup gcp-cred-file
✓ Wrote credential config to ~/.credctl/gcp-credentials.json

$ export GOOGLE_APPLICATION_CREDENTIALS=~/.credctl/gcp-credentials.json
$ gcloud storage ls

One hardware identity. Two clouds. No keys on disk for either.

What It Doesn’t Do (Yet)

To be clear about scope — credctl today is:

macOS only. Secure Enclave integration works on Apple Silicon (M1–M4) and Intel Macs with T2 chip. Linux TPM 2.0 support is planned but not yet implemented.
AWS and GCP. Azure Federated Identity Credentials are on the roadmap.
Individual use. Direct Mode means each developer manages their own OIDC endpoint. A team broker with policy enforcement, audit trails, and device fleet management is planned for a future phase.

credctl doesn’t replace HashiCorp Vault for secrets management. It replaces the plaintext cloud keys on your laptop. Different problem, different tool.

What’s Next

The roadmap expands in concentric circles:

Azure: Federated Identity Credentials, completing the three major clouds with one hardware identity.
Linux TPM 2.0: The same architecture using TPM 2.0 on Linux workstations. Windows 11 requires TPM 2.0, so the hardware is already there.
Credential broker for teams: A centralised broker that sits between developers and cloud providers. Policy enforcement (who can assume which roles, from which devices), approval workflows, and a full audit trail mapped to SOC 2, NIS2, DORA, and ISO 27001 controls.

Try It

credctl is open source (Apache 2.0).

GitHub: github.com/credctl/credctl
Quickstart: Read the quickstart guide — install to working credentials in under 5 minutes
Technical deep dive: How credctl Uses the macOS Secure Enclave for Cloud Credentials

Questions and feedback welcome in GitHub Discussions.

Stay up to date

Get notified about new credctl releases, security best practices, and hardware identity insights.

How credctl Uses the macOS Secure Enclave for Cloud Credentials

Sat, 07 Mar 2026 00:00:00 GMT

This post explains the architecture of credctl — a CLI tool that replaces long-lived AWS access keys with short-lived, hardware-bound credentials using the macOS Secure Enclave. For the problem statement and product overview, read Eliminating Plaintext Cloud Keys. This post is the “how.”

What the Secure Enclave Actually Is

The Secure Enclave is a hardware security subsystem isolated from the main processor. On Apple Silicon Macs (M1–M4), it’s a dedicated core within the SoC. On Intel Macs with T2, it’s a separate chip. Either way, it has its own boot process, its own encrypted memory, and its own secure storage.

What matters for credctl:

Key generation happens inside the hardware. When you ask the Secure Enclave to create a key pair, the private key is generated inside the chip and never leaves it. There is no API to export it. There is no memory region to read it from. The hardware enforces this — it’s not a software policy.
Signing happens inside the hardware. You send data to the Secure Enclave, it signs it with the private key, and returns the signature. The private key is never exposed to the application, the operating system, or the CPU.
User presence verification. The Secure Enclave gates key operations behind biometric (Touch ID) or passcode verification. Even with root access, a process cannot silently use a Secure Enclave key without the user’s explicit approval.
FIPS 140-2 validated. Apple’s corecrypto module, which underpins Secure Enclave operations, has FIPS 140-2 validation. This is the same level of certification used by government and financial systems.

The Secure Enclave supports ECDSA with the P-256 curve (also known as secp256r1 or prime256v1). This maps directly to the ES256 algorithm in JWTs — which is exactly what credctl needs.

credctl’s Architecture

credctl is a Go CLI that bridges the Secure Enclave’s cryptographic capabilities to cloud provider credential APIs. The architecture has five components:

graph TB
    subgraph "credctl CLI"
        CMD[Command Layer<br/>cobra]
        CFG[Config Manager<br/>~/.credctl/config.json]
        ENC[Enclave Interface<br/>cgo → Security.framework]
        JWT[JWT Builder<br/>ES256 tokens]
        STS_C[AWS STS Client<br/>AssumeRoleWithWebIdentity]
    end

    subgraph "Hardware"
        SE[Secure Enclave<br/>ECDSA P-256]
    end

    subgraph "AWS"
        STS[AWS STS]
        OIDC_P[OIDC Provider<br/>S3 + CloudFront]
    end

    CMD --> CFG
    CMD --> ENC
    CMD --> JWT
    CMD --> STS_C

    ENC --> SE
    JWT --> ENC
    STS_C --> STS
    STS --> OIDC_P

The Enclave Interface

This is the critical piece. The Secure Enclave is accessed through Apple’s Security framework, which is an Objective-C/C API. Go doesn’t call C APIs natively, so credctl uses cgo — Go’s foreign function interface for C code.

The Enclave interface abstracts hardware operations:

type Enclave interface {
    Available() bool
    GenerateKey(tag string) (*ecdsa.PublicKey, error)
    LoadKey(tag string) (*ecdsa.PublicKey, error)
    DeleteKey(tag string) error
    Sign(tag string, data []byte) ([]byte, error)
}

On macOS, the implementation calls Security framework functions via cgo:

GenerateKey calls SecKeyCreateRandomKey with kSecAttrTokenIDSecureEnclave to create an ECDSA P-256 key pair inside the Secure Enclave. The key is tagged with a unique identifier so it can be loaded later. The function returns the public key — the private key stays in hardware.
Sign calls SecKeyCreateSignature with the kSecKeyAlgorithmECDSASignatureMessageX962SHA256 algorithm. The Secure Enclave signs the data and returns the DER-encoded signature. By default (--biometric=any), this triggers a Touch ID prompt with passcode fallback. This behaviour is configurable via the --biometric flag at credctl init time.
LoadKey retrieves a previously generated key by its tag using SecItemCopyMatching.

Build tags dispatch the implementation:

darwin.go — the real Secure Enclave implementation via cgo
other.go — a stub that returns clear errors on unsupported platforms

This cgo dependency is a deliberate architectural choice. It means credctl can’t be cross-compiled with a simple go build — it needs Xcode and an Apple provisioning profile. That’s a trade-off: harder distribution in exchange for real hardware security. The binary is distributed as a code-signed, notarised macOS app bundle.

The OIDC Flow

This is where the Secure Enclave connects to AWS. The flow uses OIDC (OpenID Connect) federation — specifically, AWS STS AssumeRoleWithWebIdentity. Here’s how the pieces fit together:

Setup (one-time)

credctl init generates the key pair in the Secure Enclave. It exports the public key to ~/.credctl/device.pub and derives a device ID (SHA-256 fingerprint of the public key).
credctl setup aws deploys a CloudFormation stack that creates:
- An S3 bucket to host OIDC discovery documents
- A CloudFront distribution in front of S3 (AWS requires OIDC issuers to use HTTPS)
- An IAM OIDC identity provider that trusts the CloudFront URL as an OIDC issuer
- An IAM role with a trust policy that allows AssumeRoleWithWebIdentity from the OIDC provider
The command also generates and uploads the OIDC discovery documents (.well-known/openid-configuration and keys.json JWKS) automatically.

After setup, you have a self-hosted OIDC provider backed by your device’s hardware identity. AWS trusts this provider because it’s registered as an IAM OIDC identity provider.

Authentication (every time)

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

    CLI->>CLI: Build JWT claims:<br/>iss = CloudFront URL<br/>sub = device ID (SHA-256)<br/>aud = sts.amazonaws.com<br/>iat = now<br/>exp = now + 5min<br/>jti = random UUID
    CLI->>SE: Sign JWT (ES256)
    Note over SE: Touch ID prompt
    SE-->>CLI: Signature
    CLI->>CLI: Assemble signed JWT<br/>(header.payload.signature)
    CLI->>STS: AssumeRoleWithWebIdentity<br/>(JWT + role ARN)
    STS->>CF: GET /.well-known/openid-configuration
    CF-->>STS: Discovery document
    STS->>CF: GET /keys.json
    CF-->>STS: JWKS (device public key)
    STS->>STS: Verify JWT signature<br/>against JWKS public key
    STS->>STS: Validate claims<br/>(issuer, audience, expiry)
    STS->>STS: Assume IAM role
    STS-->>CLI: AccessKeyId +<br/>SecretAccessKey +<br/>SessionToken<br/>(valid 1 hour)

credctl auth builds a JWT with these claims:
- iss — the CloudFront URL (OIDC issuer)
- sub — the device ID (SHA-256 fingerprint of the public key)
- aud — sts.amazonaws.com
- iat — current timestamp
- exp — current timestamp + 5 minutes (short-lived token)
- jti — a random UUID (prevents replay)
The JWT header specifies alg: ES256 and includes a kid (key ID) matching the key in the JWKS.
The CLI sends the JWT payload to the Secure Enclave for signing. With the default biometric policy (--biometric=any), this triggers a Touch ID prompt with passcode fallback. The Secure Enclave returns an ECDSA signature.
The CLI assembles the complete JWT (header.payload.signature, base64url-encoded) and calls STS AssumeRoleWithWebIdentity with the JWT and the IAM role ARN.
STS fetches the OIDC discovery document from CloudFront, follows it to the JWKS endpoint, retrieves the device’s public key, and validates the JWT signature.
If validation passes and the role’s trust policy allows it, STS returns temporary credentials — an access key ID, secret access key, and session token valid for one hour (default, configurable up to 12 hours).

Why OIDC Over Roles Anywhere

AWS offers two X.509-based credential mechanisms: OIDC federation (via AssumeRoleWithWebIdentity) and IAM Roles Anywhere (via CreateSession). credctl uses OIDC federation. Here’s why:

Portability. OIDC is a cross-cloud standard. GCP’s Workload Identity Federation and Azure’s Federated Identity Credentials both accept OIDC tokens. By building on OIDC, credctl’s architecture extends to multi-cloud without fundamental changes. Roles Anywhere is AWS-specific.

Simplicity. OIDC federation requires hosting two static JSON files. Roles Anywhere requires managing X.509 certificates, certificate authorities, and certificate lifecycle. For a developer workstation tool, the OIDC approach is simpler.

JWT ecosystem. OIDC uses JWTs, which are well-understood, easy to debug (paste into jwt.io), and have mature library support. X.509 certificate handling is more complex and error-prone.

Existing infrastructure. The Secure Enclave supports ECDSA P-256 signing, which maps directly to ES256 JWTs. No certificate generation or CA infrastructure needed.

The trade-off: OIDC requires hosting a discovery endpoint (the S3 + CloudFront stack). Roles Anywhere doesn’t require any hosted infrastructure — it uses the X.509 certificate directly. For credctl’s use case, the simplicity and portability of OIDC outweigh the small infrastructure requirement.

Code Walkthrough: Key Generation to Credential Exchange

Here’s the flow through credctl’s code, step by step.

Step 1: Key Generation (`credctl init`)

The init command calls the Enclave interface to generate a key:

Enclave.GenerateKey(tag) → *ecdsa.PublicKey

Under the hood (on macOS), this calls SecKeyCreateRandomKey with attributes specifying:

Token: kSecAttrTokenIDSecureEnclave (create in Secure Enclave, not software)
Key type: kSecAttrKeyTypeECSECPrimeRandom (ECDSA)
Key size: 256 bits (P-256 curve)
Access control: determined by the --biometric flag (default: any)

The --biometric flag controls the Secure Enclave access control policy for signing:

`--biometric` value	Access control	Behaviour
`any` (default)	`kSecAccessControlPrivateKeyUsage` + `kSecAccessControlUserPresence`	Touch ID with passcode fallback
`fingerprint`	`kSecAccessControlPrivateKeyUsage` + `kSecAccessControlBiometryCurrentSet`	Touch ID only, no passcode fallback. Key is invalidated if fingerprints change.
`none`	`kSecAccessControlPrivateKeyUsage` only	No user verification. Signing happens silently when the device is unlocked.

The biometric policy is set at key creation time and cannot be changed afterward. To change it, reinitialise with credctl init --force --biometric=<policy>.

The public key is exported to ~/.credctl/device.pub in PEM format. The device ID is the SHA-256 fingerprint of the public key bytes. The config is written to ~/.credctl/config.json.

Step 2: JWT Construction (`credctl auth`)

The JWT builder constructs the token in three parts:

Header:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "<key-id-matching-jwks>"
}

Payload:

{
  "iss": "https://d1234.cloudfront.net",
  "sub": "sha256:a1b2c3d4e5f6...",
  "aud": "sts.amazonaws.com",
  "iat": 1709800000,
  "exp": 1709800300,
  "jti": "550e8400-e29b-41d4-a716-446655440000"
}

The header and payload are base64url-encoded and concatenated with a dot: base64url(header).base64url(payload). This becomes the signing input.

Step 3: Hardware Signing

The signing input bytes are sent to the Secure Enclave:

Enclave.Sign(tag, signingInput) → []byte (DER-encoded signature)

The Secure Enclave computes the ECDSA-SHA256 signature and returns it. The DER-encoded signature is converted to the raw r || s format that JWTs expect, then base64url-encoded.

The final JWT: base64url(header).base64url(payload).base64url(signature)

Step 4: Credential Exchange

The CLI calls AWS STS AssumeRoleWithWebIdentity via a raw HTTP POST (no AWS SDK):

POST https://sts.amazonaws.com/
Content-Type: application/x-www-form-urlencoded

Action=AssumeRoleWithWebIdentity
&RoleArn=arn:aws:iam::123456789012:role/credctl-role
&RoleSessionName=credctl-session
&WebIdentityToken=<signed-jwt>
&Version=2011-06-15

STS validates the JWT by:

Fetching https://d1234.cloudfront.net/.well-known/openid-configuration
Following the jwks_uri to https://d1234.cloudfront.net/keys.json
Matching the kid in the JWT header to a key in the JWKS
Verifying the ES256 signature against the public key
Checking claims: issuer matches, audience is sts.amazonaws.com, token is not expired

If valid, STS assumes the IAM role and returns temporary credentials.

Security Properties

credctl’s architecture provides several security guarantees:

Private key never leaves hardware. The Secure Enclave enforces non-exportability at the hardware level. Even with root access, an attacker cannot read the private key. They would need physical possession of the specific device AND the user’s biometric (or passcode) to sign a JWT.

Short-lived credentials. The STS credentials returned by AssumeRoleWithWebIdentity are temporary — one hour by default, configurable up to 12 hours. There are no long-lived credentials on disk.

Replay protection. Each JWT includes a unique jti (JWT ID) and a short exp (5 minutes). Even if a JWT were intercepted, it would expire before it could be meaningfully reused.

User presence required (default). With the default biometric policy (--biometric=any), every signing operation requires Touch ID or passcode verification. Malware cannot silently use the Secure Enclave key to obtain credentials. This can be disabled with --biometric=none at credctl init time for headless environments, at the cost of losing user-presence protection.

Revocation via JWKS. To revoke a device’s access, remove its public key from the JWKS and delete the IAM OIDC identity provider trust. STS will no longer validate JWTs from that device.

No credential caching on disk. credctl does not cache STS credentials to disk in plaintext. The credentials are output to stdout or set as environment variables for the current session.

What This Doesn’t Protect Against

No security architecture is complete without stating its limitations:

A compromised device with the user present. If an attacker has remote access to a device and the user approves a Touch ID prompt (social engineering or confusion), the attacker gets valid short-lived credentials. The mitigation is that the credentials are short-lived and the attack window is narrow.
Credential misuse after issuance. Once STS credentials are issued, they’re standard AWS temporary credentials. If they’re logged, written to a file, or used in a shared terminal, they can be used by anyone until they expire.
OIDC provider compromise. If an attacker gains write access to the S3 bucket hosting the JWKS, they could add their own public key and sign JWTs that STS would accept. The CloudFormation stack configures bucket access controls, but the OIDC provider is a critical trust boundary. The brokered mode (planned) eliminates this risk by centralising OIDC management.

Comparison to Alternative Approaches

It’s worth comparing credctl’s security properties to common alternatives:

Approach	Key Storage	Exportable?	Credential Lifetime	Device Binding
`~/.aws/credentials`	Plaintext file	Yes	Permanent	None
1Password Shell Plugins	Encrypted software vault	Yes (if vault decrypted)	Permanent (stored key)	None
AWS Identity Center	Browser session cookie	Yes (cookie theft)	8–12 hours	None
credctl	Secure Enclave hardware	No (hardware-enforced)	1 hour (STS)	Hardware-bound

The fundamental difference is the transition from software-stored credentials (which can be copied) to hardware-bound credentials (which physically cannot be copied). This is not an incremental improvement — it’s an architectural change in where trust is anchored.

Performance

Credential issuance involves three operations:

JWT construction: Microseconds. String formatting and base64 encoding.
Secure Enclave signing: Typically 20–50ms for the cryptographic operation, plus Touch ID interaction time (user-dependent).
STS API call: 100–300ms depending on network latency.

Total time from credctl auth to credentials: under one second of compute, plus Touch ID interaction. This is faster than browser-based SSO flows, which typically require 5–15 seconds of page loads, redirects, and MFA prompts.

STS caches the OIDC discovery document and JWKS, so subsequent credential requests in the same session don’t require CloudFront fetches. The signing operation itself is constant-time — the Secure Enclave processes ECDSA signatures at the same speed regardless of the data being signed.

What’s Next

The architecture is designed to extend in two directions:

Platform expansion. The Enclave interface abstracts hardware operations, so adding Linux TPM 2.0 support means implementing the same interface against go-tpm instead of Apple’s Security framework. The JWT builder, OIDC generator, and STS client remain unchanged. The same applies to Windows TPM via a Windows-specific build.

Multi-cloud. The OIDC-based architecture was chosen specifically because GCP Workload Identity Federation and Azure Federated Identity Credentials accept OIDC tokens. Adding GCP support means implementing a GCP token exchange client; adding Azure means implementing an Azure AD token exchange client. The hardware identity, JWT construction, and OIDC provider infrastructure remain the same.

Brokered mode. For teams, the CLI will authenticate to a centralised credctl broker instead of directly to cloud providers. The broker verifies device identity, evaluates policy (who can assume which roles from which devices), brokers credentials from cloud providers, and logs everything for audit. The hardware identity foundation is the same — the broker trusts the device’s signed assertion because it has the device’s public key in its registry.

credctl | Blog

credctl Now Supports GCP: One Hardware Identity, Two Clouds

Why This Matters

Setup: Five Minutes

Prerequisites

Step 1: Set up GCP federation

Step 2: Use it

Terraform for Teams

No GCP SDK

How the OIDC Architecture Made This Easy

What’s Next

Try It

Stay up to date

credctl: Eliminating Plaintext Cloud Keys with the Secure Enclave

The Problem Nobody Talks About

The Gap That Shouldn’t Exist

What credctl Does

How It Works

Multi-Cloud: AWS and GCP Today

What It Doesn’t Do (Yet)

What’s Next

Try It

Stay up to date

How credctl Uses the macOS Secure Enclave for Cloud Credentials

What the Secure Enclave Actually Is

credctl’s Architecture

The Enclave Interface

The OIDC Flow

Setup (one-time)

Authentication (every time)

Why OIDC Over Roles Anywhere

Code Walkthrough: Key Generation to Credential Exchange

Step 1: Key Generation (credctl init)

Step 2: JWT Construction (credctl auth)

Step 3: Hardware Signing

Step 4: Credential Exchange

Security Properties

What This Doesn’t Protect Against

Comparison to Alternative Approaches

Performance

What’s Next

Further Reading

Stay up to date

Step 1: Key Generation (`credctl init`)

Step 2: JWT Construction (`credctl auth`)