IdP Federation

Identity provider federation is configured by a PLATFORM_ADMIN and must be approved by a second PLATFORM_ADMIN before it becomes public discovery metadata.

Routes

ActionRoute
Read organization IdP metadataGET /admin/api/v1/organizations/{id}/idp
Configure IdP metadataPOST /admin/api/v1/organizations/{id}/idp
Approve IdP metadataPOST /admin/api/v1/organizations/{id}/idp/approve
Home realm discoveryPOST /api/v1/auth/discover

Configure IdP

Example request:

  {
  "tenant_id": "11111111-1111-4111-8111-111111111111",
  "provider": "saml",
  "metadata_url": "https://idp.example/metadata",
  "idp_url": "https://idp.example/login",
  "entity_id": "https://idp.example/entity",
  "display_name": "Example IdP"
}

The backend stores the metadata with status=PENDING_APPROVAL, requested_by, and requested_at. Pending metadata is not exposed by auth discovery.

Approve IdP

Approval request:

  {
  "tenant_id": "11111111-1111-4111-8111-111111111111",
  "comment": "Reviewed metadata and callback configuration."
}

The approver must be a different platform admin from the requester when requested_by is present. Approval writes status=APPROVED, approved_by, and approved_at, then provisions Keycloak when the provisioner is configured.

Outbound URL Policy

IdP URLs pass the same SSRF policy as branding and webhook URLs. By default the backend rejects:

URL classReason
localhost, loopback, link-local, private IP rangesPrevents internal network SSRF.
Credential-bearing URLsPrevents secret leakage in metadata.
Non-HTTP(S) schemesRestricts remote fetch surface.

Use SECURITY_OUTBOUND_ALLOWED_HOSTS for explicit public hosts or controlled internal hosts. Use private-network overrides only in controlled internal deployments.

Failure Semantics

FailureBackend behavior
Unsupported providerBAD_REQUEST, provider must be saml or oidc.
Tenant mismatchBAD_REQUEST, body tenant_id must match the organization.
Self-approvalFORBIDDEN, approval requires a second platform admin.
Keycloak provisioning failureSERVICE_UNAVAILABLE, approval transaction is rolled back.
Pending IdP discoveryDiscovery does not expose the pending IdP URL.

Admin Checklist

StepCheck
Configure IdPStatus is PENDING_APPROVAL; requester is correct.
Second admin reviewMetadata URL, login URL, entity ID, redirect/callback behavior, and display name are correct.
ApproveStatus is APPROVED; audit record exists.
DiscoverPOST /api/v1/auth/discover returns IdP details only after approval.