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.

​
1. JWT verification

In the Okta Admin Console:
  1. Pick the Authorization Server whose JWTs Alter should accept. Default is https://<org>.okta.com/oauth2/default.
  2. Note the Issuer URI and Audience from Security → API → Authorization Servers → the chosen server → Settings.
  3. JWKS is served at <issuer>/v1/keys — Alter discovers it automatically from the issuer URL.
In the Alter developer portal → app’s Identity page:
  1. Click Add Identity Provider.
  2. Paste the issuer URI, click Discover. Alter recognizes Okta and pre-fills the claim mappings.
  3. Paste the audience.
  4. For group-based authorization: Okta requires a group claim filter on the authorization server. In Okta, edit the authorization server → Claims → add a claim:
    • Name: groups
    • Include in token type: Access Token
    • Value type: Groups
    • Filter: Matches regex .* (or narrow as needed) Map that claim in the Alter portal before any user signs in.
  5. Click Add Provider.

​
2. OIDC sign-in (optional)

Required only for vault.authenticate() or the Wallet sign-in flow. In Okta:
  1. Applications → Applications → Create App Integration → OIDC → Web Application.
  2. Sign-in redirect URIs = both redirect URIs from the Alter portal.
  3. Sign-out redirect URIs = the Wallet logout URL from the Alter portal.
  4. Assignments: assign to the groups whose users should be able to sign into Alter Wallet.
  5. Copy Client ID and Client Secret from the application’s General tab.
In the Alter portal:
  1. Open the User Authentication (OIDC) section.
  2. Paste credentials and Save.

​
3. Webhook deprovisioning (optional)

Okta supports event hooks for user lifecycle changes. In the Alter portal → Identity page → Webhooks section:
  1. Click Enable Webhooks.
  2. Copy the generated signing secret (shown once) and the webhook endpoint URL.
In Okta:
  1. Workflow → Event Hooks → Create Event Hook.
  2. URL = the Alter webhook endpoint.
  3. Authentication field = Authorization, Authentication secret = the signing secret.
  4. Subscribe to:
    • user.lifecycle.delete.initiated
    • user.lifecycle.deactivate
    • user.lifecycle.suspend
  5. Verify the endpoint, then Activate.

​
Test

  1. Sign in as a test user through Okta → confirm the user appears in Alter.
  2. Deactivate or delete the test user → confirm their grants are revoked.

​
Common pitfalls

  • Custom Authorization Server. With a custom authorization server (not default), the issuer URI is https://<org>.okta.com/oauth2/<server-id>, not the org URL.
  • Missing group claim. Okta does not emit groups by default. Without the claim configured on the authorization server, group-based managed-secret access doesn’t work.
  • Audience mismatch. Okta’s default audience is api://default. JWTs with a different audience will fail verification.

​
See also