Skip to main content
Version: v0.25.0 (Latest)

Tenant Federation

Once the tenant owner is active, the tenant decides how its users sign in. There are two modes.

  • Platform-hosted (default): the platform's hosted Authorisation Server acts as the tenant's IdP. Nothing to configure; the tenant's users authenticate against the hosted AS.
  • External: the tenant federates to its own OIDC identity provider (Azure AD, Okta, Keycloak, or any OIDC IdP). The tenant registers that IdP through the federation admin REST.

Tenant context comes from the JWT, so a tenant configures only its own identity providers. External federation is gated by the federation license feature; without it the federation endpoints are unavailable for the tenant.

The IdP Admin REST​

External identity providers are managed under the platform-admin federation surface, scoped to the acting tenant from the JWT:

GET    /api/platform-admin/v1/federation/idps                 # listTenantIdps
POST   /api/platform-admin/v1/federation/idps                 # createTenantIdp
GET    /api/platform-admin/v1/federation/idps/{idpId}         # getTenantIdp
PUT    /api/platform-admin/v1/federation/idps/{idpId}         # replaceTenantIdp
DELETE /api/platform-admin/v1/federation/idps/{idpId}         # deleteTenantIdp
POST   /api/platform-admin/v1/federation/idps/{idpId}/test    # probe connectivity and metadata
POST   /api/platform-admin/v1/federation/idps/{idpId}/enable  # enable for sign-in
POST   /api/platform-admin/v1/federation/idps/{idpId}/disable # disable

List the tenant's identity providers with GET /federation/idps (listTenantIdps). Each record carries its issuer, clientId, scopes, claimsMapping, and enabled state, plus a clientSecretRef (never the plaintext secret). See the Platform Admin API reference for the response schema.

Creating an External IdP​

Create an IdP with POST /federation/idps. The decision here is what to put in clientSecret: supply the plaintext OIDC client secret exactly once. It is write-only in, stored through the selected secret backend, and returned only as a clientSecretRef; the plaintext is never echoed in any response. Supply the non-secret metadata (issuer, clientId, scopes, claimsMapping) alongside it, and leave enabled false so the IdP is probed before it goes live.

Supply the non-secret IdP metadata (issuer, clientId, scopes, claimsMapping) plus the write-only clientSecret. The response returns only clientSecretRef. Leave enabled false so the IdP is probed before it goes live.

POST /api/platform-admin/v1/federation/idps

The full request and response schema is in the API reference, or open the API reference tab to read it inline.

On a PUT replacement (replaceTenantIdp), supply clientSecret to rotate it, supply clientSecretRef to preserve the existing reference, or omit both to clear it. The request and response schemas for both operations are in the Platform Admin API reference.

Claims Mapping​

claimsMapping maps the external IdP's token claims onto the tenant user identity the EDK uses:

  • subject is the IdP claim that carries the stable user identifier (typically sub).
  • email is the IdP claim that carries the user's email.
  • displayName is the IdP claim that carries the human-readable name (typically name).

A deployment whose IdP emits non-standard claim names overrides these so the EDK reads the right fields.

Test, Enable, Disable​

A new IdP starts disabled. Probe it first with POST /federation/idps/{idpId}/test, which checks that the issuer is reachable and its metadata is valid. When the probe passes, enable the IdP for sign-in with POST /federation/idps/{idpId}/enable; suspend it later with POST /federation/idps/{idpId}/disable without deleting the record. Both return the updated IdP. The probe response and the enable/disable schemas are in the Platform Admin API reference.

The application tenant always keeps its hosted AS regardless of a customer tenant's external-IdP choice, so an operator can still sign in to repair a broken external-IdP setup. See Application Tenant and Bootstrap.