gilmishal · Sep 28, 2026
diff --git a/docs.json b/docs.json
@@ -164,7 +164,17 @@
                     "group": "Users",
                     "pages": [
                       "floxhub-onprem/administration/users/overview",
-                      "floxhub-onprem/administration/users/identity"
+                      {
+                        "group": "User identity",
+                        "pages": [
+                          "floxhub-onprem/administration/users/identity",
+                          "floxhub-onprem/administration/users/identity/configure",
+                          "floxhub-onprem/administration/users/identity/oidc",
+                          "floxhub-onprem/administration/users/identity/entra-id",
+                          "floxhub-onprem/administration/users/identity/ldap",
+                          "floxhub-onprem/administration/users/identity/kerberos"
+                        ]
+                      }
                     ]
                   },
                   "floxhub-onprem/administration/factory",

diff --git a/floxhub-onprem/administration/users/identity.mdx b/floxhub-onprem/administration/users/identity.mdx
@@ -1,15 +1,59 @@
 ---
 title: "User identity"
-description: "Connecting FloxHub to your identity provider."
+description: "Choose an identity integration for FloxHub on-prem: identity providers through Dex or a deployment authentication override for Kerberos."
 ---
 
-<Info>
-  **This page is under construction.** FloxHub on-prem documentation is
-  being written section by section. This page is a placeholder so the
-  surrounding navigation and links are complete.
-</Info>
+FloxHub on-prem connects to your existing identity system. The default
+integration uses Dex, the OpenID Connect (OIDC) broker included with FloxHub.
+You can also override the deployment's authentication settings to use Kerberos.
 
-## Planned contents
+## Identity providers through Dex
 
-The identity components, connector configuration, the browser login flow,
-issuer and callback settings, identity mapping, and troubleshooting.
+Dex authenticates users against your identity provider and presents a consistent
+OIDC interface to FloxHub. You configure the connection through a Dex connector.
+The provider can use OIDC, LDAP, or another protocol that its connector supports.
+
+| Integration | Providers and systems | Configuration |
+| --- | --- | --- |
+| OpenID Connect | Okta, AD FS, and other OIDC providers | [OpenID Connect](/floxhub-onprem/administration/users/identity/oidc) |
+| Microsoft | Microsoft Entra ID | [Microsoft Entra ID](/floxhub-onprem/administration/users/identity/entra-id) |
+| LDAP | Active Directory and other LDAP directories | [LDAP and Active Directory](/floxhub-onprem/administration/users/identity/ldap) |
+| Git providers | GitHub, GitLab, Gitea, and Bitbucket Cloud | [Dex connectors](https://dexidp.io/docs/connectors/) |
+| Other Dex integrations | Google, LinkedIn, OpenShift, Atlassian Crowd, and OpenStack Keystone | [Dex connectors](https://dexidp.io/docs/connectors/) |
+
+Use the connectors available in the Dex version shipped with your FloxHub
+release. Connector maturity, refresh-token support, and available identity
+claims vary; the [Dex connector reference](https://dexidp.io/docs/connectors/)
+describes those differences.
+
+Start with [Configure identity providers](/floxhub-onprem/administration/users/identity/configure)
+for shared setup, required claims, and verification. The provider guides above
+contain the connector examples.
+
+### SAML
+
+FloxHub does not offer a SAML integration. Dex's
+[SAML connector documentation](https://dexidp.io/docs/connectors/saml/)
+warns that the connector is unmaintained. Use OIDC or LDAP when your provider
+supports it.
+
+## Custom authentication overrides
+
+You can supply deployment-specific authentication settings through your Flox
+environment. Kerberos/SPNEGO uses this override mechanism to authenticate
+requests at FloxHub's front door and resolve the verified principal to a
+FloxHub identity.
+
+This integration uses FloxHub's trusted identity path independently of Dex
+connectors. You supply the Kerberos realm, HTTP service principal, and keytab.
+See [Kerberos authentication](/floxhub-onprem/administration/users/identity/kerberos)
+for the configuration contract.
+
+## Identity and access
+
+Your identity integration establishes who a person is. FloxHub manages their
+account and access to namespaces separately. Directory groups do not currently
+map to FloxHub organizations or roles.
+
+See [Administer users](/floxhub-onprem/administration/users/overview) for account
+provisioning, handles, organization membership, and access revocation.
diff --git a/floxhub-onprem/administration/users/identity/configure.mdx b/floxhub-onprem/administration/users/identity/configure.mdx
@@ -0,0 +1,140 @@
+---
+title: "Configure identity providers"
+description: "Shared setup, identity claims, and verification for identity providers connected through Dex."
+---
+
+Connect an identity provider through the Dex broker included with FloxHub.
+For the available integration paths, see [User identity](/floxhub-onprem/administration/users/identity).
+
+## Before your first sign-in
+
+The external URL you choose is baked into every token the deployment issues,
+and the broker advertises it as its issuer. Set `FLOXHUB_SITE_URL` to the real
+external URL **before** anyone signs in, not after — changing it later
+invalidates the tokens already issued against the old value.
+
+See [Environment variables](/floxhub-onprem/administration/environment-variables)
+for where that setting lives.
+
+## Connect your provider
+
+These steps apply to providers connected through Dex.
+
+**1. Write the connector.** Create `$FLOX_ENV_CACHE/dex/connectors.yaml`
+from inside the deployment's activation, with a top-level `connectors:` key.
+Use the example from your provider guide and replace its placeholders with
+your provider's values.
+
+**2. Register the callback URL** when your provider uses an OIDC or OAuth
+application registration. LDAP directories do not need a callback registration:
+
+```text
+${FLOXHUB_SITE_URL}/dex/callback
+```
+
+**3. Render the configuration and restart the broker:**
+
+```bash
+flox activate -- bash -c 'floxhub render && flox services restart dex'
+```
+
+The connector file is yours to protect — it holds a client secret or a bind
+password:
+
+```bash
+flox activate -c 'chmod 600 "$FLOX_ENV_CACHE/dex/connectors.yaml"'
+```
+
+<Warning>
+  Rendering refuses to proceed when a required value is unset or a required
+  file is missing, and it rejects a broker configuration that does not parse.
+  Until a render has succeeded, the front door and the broker refuse to start.
+  Run `floxhub check` to see the same report without rendering.
+</Warning>
+
+Choose a connector example:
+
+- [OpenID Connect: Okta, AD FS, and other providers](/floxhub-onprem/administration/users/identity/oidc)
+- [Microsoft Entra ID](/floxhub-onprem/administration/users/identity/entra-id)
+- [LDAP and Active Directory](/floxhub-onprem/administration/users/identity/ldap)
+
+## What the deployment takes from your provider
+
+On a successful sign-in, the deployment reads three things from the identity
+your provider asserts:
+
+| Claim | What it becomes |
+| --- | --- |
+| Issuer and subject | The stable link between the person and their FloxHub user |
+| `preferred_username`, or `name` if absent | The starting point for their FloxHub handle |
+| `email`, `name`, avatar | Their displayed profile |
+
+Because the issuer and subject are what identify the person, the FloxHub user
+survives a change of display name or email address. For how a handle is
+derived from that username claim, and what happens when it cannot be, see
+[Administer users](/floxhub-onprem/administration/users/overview).
+
+<Note>
+  Your provider must send `preferred_username` or `name`. An identity carrying
+  neither cannot be provisioned, and the sign-in fails.
+</Note>
+
+## What your provider does not decide
+
+Authenticating proves who somebody is. It does not grant them anything beyond
+their own personal namespace.
+
+Directory group membership does not currently map to FloxHub organizations or
+roles. Configure organization membership inside FloxHub separately from the
+identity-provider connection.
+
+## Verify and troubleshoot
+
+Confirm the broker is answering and advertising the issuer you expect:
+
+```bash
+curl -fsS "${FLOXHUB_SITE_URL}/dex/.well-known/openid-configuration"
+```
+
+The `issuer` in the response must match `${FLOXHUB_SITE_URL}/dex` exactly. If
+it does not, `FLOXHUB_SITE_URL` is wrong — fix it, re-render, and restart.
+
+Confirm the CLI can discover sign-in:
+
+```bash
+curl -fsS "${FLOXHUB_SITE_URL}/.well-known/oauth-protected-resource"
+```
+
+A `404` here means the deployment has the broker disabled, which the Flox CLI
+reads as "no sign-in available here".
+
+| Symptom | Where to look |
+| --- | --- |
+| Broker will not start | `floxhub check` — the render is missing or older than its inputs |
+| Sign-in reaches your provider but fails on return | The callback URL registered with your provider, and `redirectURI` in the connector |
+| Tokens rejected as issued by the wrong issuer | `FLOXHUB_SITE_URL` changed after the first sign-in |
+| Sign-in fails for one person only | Their username claim, or a handle already taken — see [Administer users](/floxhub-onprem/administration/users/overview) |
+
+Broker logs carry the provider's own error responses, which is where a
+misconfigured client secret or an unregistered callback shows up. Read the
+broker's output from the deployment environment:
+
+```bash
+flox activate -- flox services logs dex
+```
+
+See [Log system](/floxhub-onprem/administration/logs) for the wider logging
+guidance.
+
+## Re-render after any change
+
+The rendered configuration is derived from your settings, your secrets, and
+the connector file. Any change to those means rendering again — including
+after you upgrade the deployment:
+
+```bash
+flox activate -- bash -c 'floxhub render && flox services restart dex'
+```
+
+Activation warns you when the rendered files are older than their inputs, and
+the front door and broker refuse to start until you have re-rendered.
diff --git a/floxhub-onprem/administration/users/identity/entra-id.mdx b/floxhub-onprem/administration/users/identity/entra-id.mdx
@@ -0,0 +1,35 @@
+---
+title: "Microsoft Entra ID"
+description: "Connect Microsoft Entra ID through the Dex Microsoft connector."
+---
+
+Complete the [shared setup](/floxhub-onprem/administration/users/identity/configure) and use the
+`${FLOXHUB_SITE_URL}/dex/callback` URL when registering your application.
+
+## Register the application and write the connector
+
+Register an application under **App registrations** — web platform, with the
+callback URL as the redirect URI — and create a client secret. The `microsoft`
+connector handles the Entra specifics.
+
+```yaml
+connectors:
+  - type: microsoft
+    id: entra
+    name: Entra ID
+    config:
+      tenant: <tenant id or domain>
+      clientID: <application id>
+      clientSecret: <client secret>
+      redirectURI: https://<host>/dex/callback
+```
+
+## Apply and verify
+
+Follow the [render and verification steps](/floxhub-onprem/administration/users/identity/configure#connect-your-provider).
+Confirm that the identity returned through Dex includes `preferred_username`
+or `name`, as described in the
+[required claims](/floxhub-onprem/administration/users/identity/configure#what-the-deployment-takes-from-your-provider).
+
+See the [Dex Microsoft connector reference](https://dexidp.io/docs/connectors/microsoft/)
+for provider-specific options.
diff --git a/floxhub-onprem/administration/users/identity/kerberos.mdx b/floxhub-onprem/administration/users/identity/kerberos.mdx
@@ -0,0 +1,57 @@
+---
+title: "Kerberos authentication"
+description: "Use deployment authentication overrides to integrate Kerberos and SPNEGO with FloxHub."
+---
+
+Kerberos/SPNEGO is an authentication override for the deployment. FloxHub's
+front door verifies the Kerberos credential, and Accounts resolves the verified
+principal to a FloxHub identity. This path operates independently of Dex
+connectors.
+
+## Deployment configuration
+
+Supply the following overrides in your deployment's Flox environment:
+
+| Setting | Value |
+| --- | --- |
+| `FLOXHUB_SITE_NGINX_AUTH_MODE` | `kerberos` |
+| `FLOXHUB_SITE_AUTH` | `reverse_proxy` |
+| `FLOXHUB_SITE_BACKEND_AUTHN_MODE` | `trusted_identity` |
+| `FLOXHUB_SITE_KERBEROS_REALM` | Your Kerberos realm |
+| `FLOXHUB_SITE_KERBEROS_SERVICE_NAME` | Your HTTP service principal |
+| `FLOXHUB_SITE_KERBEROS_KEYTAB` | Path to the service keytab |
+
+The nginx package included with FloxHub contains the SPNEGO module. You supply
+the realm configuration and service credentials. Restrict access to the keytab
+to the service identity that needs it.
+
+The authentication front door also needs the Accounts internal API credential
+in `$FLOX_ENV_CACHE/secrets/accounts-internal-api-keys`. It uses this credential
+to resolve the verified Kerberos principal through Accounts. Keep internal
+Accounts endpoints accessible only to trusted services.
+
+Render the configuration after changing authentication settings, the keytab
+path, or the Accounts credential:
+
+```bash
+flox activate -- floxhub render
+```
+
+Restart the affected services through your deployment's service manager to
+apply the rendered configuration. Dex is enabled independently; selecting
+Kerberos does not automatically disable it.
+
+## Identity and trust
+
+FloxHub verifies the configured realm and keeps a stable Accounts identifier
+for each full realm-qualified principal. The username portion is preserved for
+POSIX lookups. Kerberos handles accept ASCII letters, digits, underscores, and
+hyphens; unsupported characters are rejected.
+
+The front door replaces incoming identity assertions with the verified
+Accounts identity before forwarding requests. Backend services must only
+accept trusted identity assertions from that authentication boundary.
+
+Organization membership and authorization are configured separately from
+Kerberos authentication. See [Administer users](/floxhub-onprem/administration/users/overview)
+for the user administration topics.
diff --git a/floxhub-onprem/administration/users/identity/ldap.mdx b/floxhub-onprem/administration/users/identity/ldap.mdx
@@ -0,0 +1,41 @@
+---
+title: "LDAP and Active Directory"
+description: "Connect an LDAP directory or Active Directory through Dex."
+---
+
+Complete the [shared setup](/floxhub-onprem/administration/users/identity/configure) and provide a
+read-only directory account for the connector.
+
+## Write the connector
+
+The LDAP connector binds with a read-only service account and authenticates
+users by search-then-bind.
+
+```yaml
+connectors:
+  - type: ldap
+    id: ldap
+    name: Directory
+    config:
+      host: ldap.example.com:636
+      bindDN: cn=floxhub,ou=services,dc=example,dc=com
+      bindPW: <service account password>
+      userSearch:
+        baseDN: ou=people,dc=example,dc=com
+        filter: "(objectClass=person)"
+        username: uid          # sAMAccountName for Active Directory
+        idAttr: uid
+        emailAttr: mail
+        nameAttr: cn
+```
+
+Group search is deliberately omitted. Group membership from your directory
+does not currently drive authorization in FloxHub; see
+[What your provider does not decide](/floxhub-onprem/administration/users/identity/configure#what-your-provider-does-not-decide).
+
+## Apply and verify
+
+Follow the [render and verification steps](/floxhub-onprem/administration/users/identity/configure#connect-your-provider).
+
+See the [Dex LDAP connector reference](https://dexidp.io/docs/connectors/ldap/)
+for TLS, directory search, and attribute-mapping options.