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. See that page first.

​
1. JWT verification

Values to gather from the Keycloak Admin Console:
  • Realm: the realm whose JWTs Alter accepts.
  • Issuer URL: https://<keycloak-host>/realms/<realm-name>.
  • Audience: the client ID of the OIDC client used for sign-in.
Steps in the Alter developer portal → app’s Identity page:
  1. Add Identity Provider is selected.
  2. The issuer URL is provided, then Discover is used to autofill the claim mappings — Alter recognizes Keycloak and pre-fills the appropriate values.
  3. The audience is provided.
  4. For group-based authorization: Keycloak emits groups under the groups claim once a Group Membership protocol mapper is attached to the client scope. The mapper must be configured before any user signs in:
    • Path: Clients → <client> → Client scopes → <client>-dedicated → Add mapper → By configuration → Group Membership.
    • Token Claim Name: groups.
    • Add to access token: ON.
  5. Add Provider completes the wiring.

​
2. OIDC sign-in (optional)

Required only when vault.authenticate() or the Wallet sign-in flow is used. Values to gather from Keycloak:
  • A new OIDC client created via Clients → Create client with OpenID Connect as the type and Confidential as the access type.
  • Valid redirect URIs: both redirect URIs from the Alter portal.
  • Valid post-logout redirect URIs: the Wallet logout URL from the Alter portal.
  • Client ID and Client secret from the client’s Credentials tab.
Steps in the Alter portal:
  1. The User Authentication (OIDC) section is opened.
  2. Credentials are pasted and saved.

​
3. Webhook deprovisioning (optional)

Keycloak’s webhook support is community-supplied. Two common paths:
  • Keycloak Events Listener SPI (e.g., the open-source keycloak-event-listener-http extension) — posts lifecycle events to a configured URL.
  • Custom SPI that calls the Alter webhook endpoint on USER_DELETED and USER_DISABLED events.
Either path follows the same wiring:
  1. In the Alter portal → Identity page → Webhooks, Enable Webhooks is toggled. The signing secret and webhook URL are then copied.
  2. In the Keycloak listener config:
    • URL = the Alter webhook endpoint.
    • Authorization header = the signing secret.
    • Subscribed events: USER_DELETED and USER_DISABLED.

​
Test

  1. A test user signs in through Keycloak — the user should then appear in Alter.
  2. The same test user is deleted or disabled — the user’s grants should be revoked in Alter.

​
Common pitfalls

  • Realm vs master realm. The issuer URL must point at the realm whose users sign in, not the master realm.
  • Self-signed TLS. A Keycloak instance with a self-signed certificate breaks JWKS fetches from Alter. A publicly trusted certificate is required.
  • Group mapper not added. Keycloak does not emit groups by default. Without the protocol mapper, group-based managed-secret access does not work.

​
See also