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.

This page is the per-provider supplement to the IDP overview. Read that first. Use this guide for any OIDC-compliant provider not covered by the dedicated pages — Firebase, Cognito, OneLogin, Ping, Stytch, Supabase Auth, Microsoft Entra (Azure AD), etc.

​
1. JWT verification

Find these from the provider’s documentation:
  • Issuer URL (the value of the iss claim in JWTs)
  • JWKS URL (usually <issuer>/.well-known/jwks.json per OIDC discovery)
  • Audience (the value of the aud claim — typically the provider client ID)
  • User-ID claim (default sub)
  • Group claim (provider-specific; common values: groups, cognito:groups, roles)
In the Alter developer portal → app’s Identity page:
  1. Click Add Identity Provider.
  2. Paste the issuer URL and click Discover. When the provider exposes OIDC discovery at <issuer>/.well-known/openid-configuration, Alter pulls JWKS automatically.
  3. Override the claim mappings when the JWT uses non-standard claim names. Set group / role claims before any user signs in — they lock after first authentication.
  4. Click Add Provider.

​
2. OIDC sign-in (optional)

Required only for vault.authenticate() or the Wallet sign-in flow. In the IDP:
  1. Create an OIDC application (sometimes called “Web App” or “Confidential Client”).
  2. Add both redirect URIs from the Alter portal as allowed callbacks.
  3. When the IDP supports post_logout_redirect_uri, add the Wallet logout URL.
  4. Copy the Client ID and Client Secret.
In the Alter portal:
  1. Open the User Authentication (OIDC) section.
  2. Paste Client ID and Client Secret.
  3. Save.

​
3. Webhook deprovisioning (optional)

When the IDP supports outbound webhooks for user lifecycle events:
  1. In the Alter portal → Identity page → Webhooks → Enable Webhooks.
  2. Copy the signing secret (shown once) and the webhook endpoint URL.
  3. In the IDP, configure a webhook with:
    • URL = the Alter webhook endpoint.
    • Authorization header value = the signing secret.
    • Subscribe to whatever the IDP names “user deleted” and “user disabled” events.
When the IDP does not support webhooks, deprovisioning waits until the deleted user’s JWT expires.

​
Common pitfalls

  • Issuer mismatch. Some providers (Firebase, Cognito) include a path segment in the issuer (https://securetoken.google.com/<project-id>, https://cognito-idp.<region>.amazonaws.com/<pool-id>). The portal value must exactly match the JWT iss claim.
  • Audience formatting. Some providers send a single audience as a string ("aud": "client-id"); some send an array ("aud": ["client-id"]). Alter handles both, but the portal value must match one of the entries.
  • Custom claim names. When the provider emits the user ID under something other than sub (e.g., user_id for Firebase), set the user-ID claim mapping accordingly before first sign-in.

​
Common provider quick-reference

ProviderIssuer patternGroup claim
Firebasehttps://securetoken.google.com/<project-id>firebase.identities (no native groups)
Cognitohttps://cognito-idp.<region>.amazonaws.com/<user-pool-id>cognito:groups
Microsoft Entrahttps://login.microsoftonline.com/<tenant>/v2.0groups (configure manifest)
Stytchhttps://test.stytch.com/v1/sessions (use the public JWKS endpoint they document)member.organization.organization_id for B2B
When in doubt, decode a JWT from the provider with jwt.io and check the actual claim names.

​
See also