Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.alterauth.com/llms.txt

Use this file to discover all available pages before exploring further.

An Identity Provider (IDP) is the external service that authenticates an app’s end users. When one is configured per app, Alter verifies the JWTs the IDP issues, resolves which user is making each call, and looks up that user’s grants automatically. This page covers the IDP model. For the runtime SDK pattern, see JWT identity. For step-by-step setup of a specific provider, see the per-IDP guides:

Auth0

Clerk

Okta

Keycloak

WorkOS

Custom OIDC

​
What an IDP integration provides

CapabilityWhat it means
JWT verificationAlter validates the signature against the IDP’s JWKS on every call. Replaced/rotated keys are picked up automatically.
User resolutionThe JWT sub claim maps to an Alter user record. New users are lazy-created on first sight.
Group syncIf the JWT carries a group claim, Alter syncs group memberships into the user record. Group-bound managed secrets become accessible to the user.
OIDC sign-in (optional)Lets vault.authenticate() and the Wallet show a sign-in flow through the IDP.
Webhook deprovisioning (optional)Real-time revocation: deleting a user in the IDP revokes their grants in Alter.

​
What gets configured

Three concentric layers, each optional after the previous one.
1

JWT validation (required)

Issuer URL, JWKS URL, audience, claim mappings (sub, group, role). Once configured, the SDK can pass JWTs and Alter resolves users from them.
2

OIDC sign-in (optional)

Client ID + secret + redirect URIs. Adds a browser-based sign-in flow for vault.authenticate() and Alter Wallet.
3

Webhook deprovisioning (optional)

Webhook endpoint + signing secret. Pushes user lifecycle events from the IDP into Alter for real-time revocation.

​
One IDP per app

Each app has at most one active IDP configuration. To switch IDPs, remove the existing one and add the replacement. Existing user records survive the switch, but JWT-based sign-ins reset until users re-authenticate against the new IDP.

​
Claim mappings lock after first sign-in

The user-ID claim, group claim, and role claim cannot be changed after the first user authenticates through the IDP. Alter Vault auto-detects sensible defaults (sub for user ID, groups or provider-specific equivalents for groups), but when an IDP needs a custom action to emit a group claim (Auth0, Okta), set it up before the first user signs in.

​
Auto-detection

Pasting an issuer URL into the developer portal and clicking Discover triggers detection:
  • Auth0, Clerk, Okta, Keycloak, WorkOS are recognized from the URL pattern; sensible claim mappings are pre-filled.
  • Anything else falls back to custom_oidc and uses standard OIDC defaults (sub for user ID).
Any mapping can be overridden before saving.

​
Lazy user sync

The first time Alter sees a JWT for a previously-unknown user:
  1. The JWT signature is verified against the IDP’s JWKS.
  2. A user record is created keyed by the sub claim.
  3. Group memberships are synced from the configured group claim.
  4. The call result is returned.
Subsequent calls update the user’s profile (name, email, group membership) on each request. There is no manual provisioning step.

​
What happens on deprovisioning

When webhooks are enabled and the IDP fires a user-deletion event:
  1. Alter sets the user’s status to deprovisioned.
  2. All linked OAuth grants are revoked immediately.
  3. Tokens for those grants are deleted from the vault.
  4. Subsequent calls with that user’s JWT (which may still be valid until expiry) fail with GrantNotFoundError.
Without webhooks, deprovisioning waits until the IDP rejects the JWT (typically at expiry). Webhooks close that gap.

​
See also