Skip to main content

Identity Provider (IdP)

How openDesk handles authentication and SSO. Today every deployment ships with Nubus (a Keycloak fork shipped by the openDesk upstream) as the embedded IdP; external-IdP integration is wired into the deployer (externalIdp config + step 23 post-sync verification + LDAP usernameAttribute patch). This topic answers: "Where is the Keycloak admin password?", "Why did Element go degraded after Keycloak ingress changed?", "What is the bootstrap deadlock and how do I get out of it?", "What does step 26 do with Keycloak credentials?", "How do I federate Entra ID / Google Workspace where usernames are emails?".

Audience: engineers configuring SSO, debugging IdP-related sync failures, or planning the external-IdP integration.

What lives here​

  • Components: the Nubus chart and how it sits in the cluster.
  • Concepts: the high-level five-layer model of instance.yaml.externalIdp flowing through helmfile / policy / Ansible playbooks / Keycloak Admin REST.
  • Incidents: IdP-specific failures — bootstrap deadlocks, Keycloak ingress changes that ripple to Element, step-26 race against Keycloak readiness.
  • Runbooks: operational tasks like fetching the admin password.

What does NOT live here:

  • The Nubus PreSync hook deployer mechanics — see deployment (step-16-ensure-2fa-browser-flow, step-23-configure-idp-federation, step-25-register-matrix-accounts, step-26-store-keycloak-credentials, concept-argocd-hooks).
  • Per-app OIDC config (Element, OX, Synapse, OpenProject) — see the relevant page in apps.
  • Storage of Keycloak credentials in Secrets Manager — see security.

Pages​

Components​

  • app-keycloak-nubus — Nubus (Keycloak fork) shipped as the embedded IdP; how the chart, realm bootstrap, and ingress fit together

Concepts​

  • concept-idp-integration — high-level model for embedded vs external IdP modes

Incidents​

  • incident-bootstrap-deadlock — UMS hook Jobs stuck "Pending deletion" for hours; realm-creation ordering; recovery procedure
  • incident-element-degraded-keycloak-ingress — Element goes degraded when Keycloak's ingress is rewritten; root cause and fix
  • incident-step-20-keycloak-secret-race — step 26 (StoreKeycloakCredentials) racing with Keycloak readiness; symptom and resolution (page name kept for git history)

Runbooks​

  • runbook-get-keycloak-admin-password — how to retrieve the Keycloak admin password from the cluster
  • runbook-wire-saml-sso — register Wire (messenger) as a SAML SP so Keycloak is its IdP; export realm metadata, repoint the portal Chat tile to the Wire SSO link
  • deployment — Keycloak-touching deployer steps live there: step-16-ensure-2fa-browser-flow (auth-flow safety net), step-23-configure-idp-federation (post-sync IdP entry verification + LDAP usernameAttribute patch), step-25-register-matrix-accounts (relies on Keycloak being up), step-26-store-keycloak-credentials (writes admin pwd to SM)
  • security — Keycloak admin credentials are stored in STACKIT Secrets Manager; that flow is documented under security
  • apps — Element / Synapse / OX integrations all consume Keycloak as an OIDC provider; the per-app config lives in apps
  • config — IdP-related fields in instance.yaml (when external-IdP support lands, the input-side surface goes there)
  • infrastructure — Keycloak's TLS certificate flows through the same cert-manager / ACME pipeline as the rest of the platform

When to add a page here​

  • A new IdP-related concept — realm layout, OIDC client conventions, federation model (concept-*)
  • A specific runbook for IdP operations — rotate admin password, add realm, add federated user, federate to external IdP (runbook-*)
  • A new IdP-related incident with a distinct root cause (incident-*)
  • A decision on IdP architecture — switch defaults from Nubus to plain Keycloak, drop a federation source (decision-*)

Per-app OIDC configuration lives with the app in apps. Steps that deploy Keycloak / Nubus (clone, render, sync) live in deployment — only IdP-specific behavior belongs here. Secret material (admin password, OIDC client secrets) lives in security.