Identity Providers

Permix uses provider-agnostic JWKS resolution. Any OIDC-compliant identity provider — Keycloak, Auth0, Okta, Cognito, or your own — can be registered as long as it exposes a JWKS endpoint.

Supported token formats#

Registering an IdP#

See Tenant Management for the full /admin/tenants/{id}/identity-providers API. A minimal registration payload:

{
  "issuer_url": "https://your-idp.example.com/realms/myrealm",
  "jwks_uri": "https://your-idp.example.com/realms/myrealm/protocol/openid-connect/certs",
  "claim_config": {
    "roles_claim": "realm_access.roles",
    "domain_claim": "dom",
    "admin_domain_claim": "adm"
  }
}

Claim configuration#

The claim_config block tells the service where to find authorization data inside the JWT payload.

Nested claim paths use dot-notation (realm_access.roles means payload.realm_access.roles).

Self-hosted mode claim config#

In selfhost mode, claim config is set via environment variables (no IdP registration needed):

ROLES_CLAIM=realm_access.roles
DOMAIN_CLAIM=dom
ADMIN_DOMAIN_CLAIM=adm
EXCLUDED_ROLES=offline_access,uma_authorization

Keycloak example (self-hosted)#

MODE=selfhost
OIDC_ENABLED=true
AUTH_SERVER_URL=https://keycloak.example.com/realms/myrealm
JWKS_URI=https://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs
ROLES_CLAIM=realm_access.roles
DOMAIN_CLAIM=dom

Auth0 example (SaaS tenant)#

{
  "issuer_url": "https://your-tenant.us.auth0.com/",
  "jwks_uri": "https://your-tenant.us.auth0.com/.well-known/jwks.json",
  "claim_config": {
    "roles_claim": "https://your-app.com/roles",
    "domain_claim": "https://your-app.com/tenant"
  }
}

JWKS caching and refresh#

The ValidatorCache caches JWKS responses per issuer. Cache entries are lazily created on first token validation. If a JWKS fetch fails, the previous cached validator is used as a fallback, preventing a hard failure on transient IdP downtime.