HashiCorp Vault

This setup guide is for making a private Vault issuer verifiable from outside your network. You configure Vault to mint tokens for your oidc.pub URL, then publish its discovery document and JWKS through oidc.pub so external relying parties can validate those tokens.

Vault OIDC Identity Tokens documentation

Prerequisites

A HashiCorp Vault instance with the identity secrets engine enabled
An oidc.pub account with a registered service (e.g. vault.oidc.pub)
An API token from the oidc.pub dashboard, or another auth method

Step 1: Configure Vault's issuer URL

Update the OIDC issuer in Vault so that tokens it mints carry the oidc.pub URL as the iss claim. This must happen before uploading the configuration, otherwise the issuer in your tokens will not match the discovery endpoint.

vault write identity/oidc/config \
  issuer="https://vault.oidc.pub"

After this change, any new OIDC tokens minted by Vault will have "iss": "https://vault.oidc.pub" in their claims.

Vault API: Configure OIDC Settings

Step 2: Sync OIDC config to oidc.pub

Vault exposes its OIDC discovery document and JWKS at well-known paths. Sync them to oidc.pub using the sync worker or manually. The API automatically rewrites the issuer and jwks_uri fields to point to your oidc.pub subdomain.

Run the sync worker alongside Vault to keep your oidc.pub service in sync automatically, including during key rotations.

docker run -d --name oidcpub-sync \
  -e OIDC_SOURCE_URL=$VAULT_ADDR/v1/identity/oidc \
  -e OIDCPUB_SERVICE_ID=<your-service-subdomain> \
  -e OIDCPUB_API_KEY=<your-api-key> \
  registry.gitlab.com/oidc.pub/cli:latest-sync

# Fetch from Vault
OIDC_CONFIG=$(curl -s $VAULT_ADDR/v1/identity/oidc/.well-known/openid-configuration)
JWKS=$(curl -s $VAULT_ADDR/v1/identity/oidc/.well-known/keys)

# Upload to oidc.pub
curl -X PUT https://oidc.pub/api/services/$SERVICE_SUBDOMAIN/config \
  -H "Authorization: Bearer $OIDCPUB_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n \
    --argjson oidc "$OIDC_CONFIG" \
    --argjson jwks "$JWKS" \
    '{ openidConfiguration: $oidc, jwks: $jwks }'
  )"

# SERVICE_SUBDOMAIN is the preferred public reference. Service IDs remain
# accepted for compatibility.

Step 3: Verify

Within 60 seconds, your OIDC discovery endpoint is publicly reachable.

curl https://vault.oidc.pub/.well-known/openid-configuration | jq .

curl https://vault.oidc.pub/.well-known/jwks.json | jq .

Next steps

Sync Worker — configuration reference, authentication options, and one-shot mode
Key Rotation — how OIDC providers rotate signing keys and what it means for your sync interval
Check out one of the integration guides, for example the AWS Integration Guide — a concrete relying-party setup for identity published through oidc.pub