From 2b06b053af3358f118440efb89153bbc87d97955 Mon Sep 17 00:00:00 2001 From: Isaac Karrer Date: Mon, 28 Sep 2026 16:36:09 -0500 Subject: [PATCH] docs(floxhub-onprem): document identity integrations (ENT-361) Add a User identity overview covering Dex connector integrations and deployment authentication overrides for Kerberos. Separate shared setup and provider configuration into linked guides for OpenID Connect, Microsoft Entra ID, LDAP, and Kerberos. Document the configuration and trust boundaries for the Kerberos override. Update the navigation and generated agent index for the identity section. Co-Authored-By: Morgan Helton Co-Authored-By: Claude Opus 5 --- docs.json | 12 +- .../administration/users/identity.mdx | 62 ++++++-- .../users/identity/configure.mdx | 140 ++++++++++++++++++ .../users/identity/entra-id.mdx | 35 +++++ .../users/identity/kerberos.mdx | 57 +++++++ .../administration/users/identity/ldap.mdx | 41 +++++ .../administration/users/identity/oidc.mdx | 60 ++++++++ llms.txt | 10 +- styles/config/vocabularies/Flox/accept.txt | 5 + 9 files changed, 411 insertions(+), 11 deletions(-) create mode 100644 floxhub-onprem/administration/users/identity/configure.mdx create mode 100644 floxhub-onprem/administration/users/identity/entra-id.mdx create mode 100644 floxhub-onprem/administration/users/identity/kerberos.mdx create mode 100644 floxhub-onprem/administration/users/identity/ldap.mdx create mode 100644 floxhub-onprem/administration/users/identity/oidc.mdx diff --git a/docs.json b/docs.json index 42cee04..0e167be 100644 --- 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 index a74e16b..c3f8510 100644 --- 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." --- - - **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. - +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 new file mode 100644 index 0000000..cd9e059 --- /dev/null +++ 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"' +``` + + + 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. + + +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). + + + Your provider must send `preferred_username` or `name`. An identity carrying + neither cannot be provisioned, and the sign-in fails. + + +## 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 new file mode 100644 index 0000000..129141f --- /dev/null +++ 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: + clientID: + clientSecret: + redirectURI: https:///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 new file mode 100644 index 0000000..44d38ad --- /dev/null +++ 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 new file mode 100644 index 0000000..267096f --- /dev/null +++ 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: + 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. diff --git a/floxhub-onprem/administration/users/identity/oidc.mdx b/floxhub-onprem/administration/users/identity/oidc.mdx new file mode 100644 index 0000000..e114c7f --- /dev/null +++ b/floxhub-onprem/administration/users/identity/oidc.mdx @@ -0,0 +1,60 @@ +--- +title: "OpenID Connect" +description: "Connect Okta, AD FS, or another OpenID Connect identity provider through Dex." +--- + +Use Dex's `oidc` connector for an OpenID Connect provider. Complete the +[shared setup](/floxhub-onprem/administration/users/identity/configure), including registering +`${FLOXHUB_SITE_URL}/dex/callback` with your provider. + +## Provider configuration + +You need the provider's issuer URL, a client ID, and a client secret. The +connector must return the identity claims described in +[Configure identity providers](/floxhub-onprem/administration/users/identity/configure#what-the-deployment-takes-from-your-provider). +Dex's OIDC connector requests the `profile` and `email` scopes by default; +configure additional scopes or claim mappings if your provider requires them. + +## Okta + +Create an **OIDC — Web Application** app integration in the Okta admin +console, with the callback URL as the sign-in redirect URI. + +```yaml +connectors: + - type: oidc + id: okta + name: Okta + config: + issuer: https://.okta.com + clientID: + clientSecret: + redirectURI: https:///dex/callback +``` + +## AD FS + +AD FS 2016 and later expose OIDC directly, so connect through OIDC rather than +SAML. Create an **Application Group** with a Server application, register the +callback URL, and generate a shared secret. + +```yaml +connectors: + - type: oidc + id: adfs + name: AD FS + config: + issuer: https:///adfs + clientID: + clientSecret: + redirectURI: https:///dex/callback +``` + +## Other OpenID Connect providers + +Use the same connector type with your provider's issuer and client registration. +See the [Dex OIDC connector reference](https://dexidp.io/docs/connectors/oidc/) +for scopes, claim mapping, and additional options. + +After writing the connector, follow the +[render and verification steps](/floxhub-onprem/administration/users/identity/configure#connect-your-provider). diff --git a/llms.txt b/llms.txt index af9c734..3b8841c 100644 --- a/llms.txt +++ b/llms.txt @@ -165,7 +165,15 @@ Key terms: ## FloxHub on-prem: Administer: Users - [Administer users](https://flox.dev/docs/floxhub-onprem/administration/users/overview.md): Provisioning and managing the people who use your deployment. -- [User identity](https://flox.dev/docs/floxhub-onprem/administration/users/identity.md): Connecting FloxHub to your identity provider. + +## FloxHub on-prem: Administer: Users: User identity + +- [User identity](https://flox.dev/docs/floxhub-onprem/administration/users/identity.md): Choose an identity integration for FloxHub on-prem: identity providers through Dex or a deployment authentication override for Kerberos. +- [Configure identity providers](https://flox.dev/docs/floxhub-onprem/administration/users/identity/configure.md): Shared setup, identity claims, and verification for identity providers connected through Dex. +- [OpenID Connect](https://flox.dev/docs/floxhub-onprem/administration/users/identity/oidc.md): Connect Okta, AD FS, or another OpenID Connect identity provider through Dex. +- [Microsoft Entra ID](https://flox.dev/docs/floxhub-onprem/administration/users/identity/entra-id.md): Connect Microsoft Entra ID through the Dex Microsoft connector. +- [LDAP and Active Directory](https://flox.dev/docs/floxhub-onprem/administration/users/identity/ldap.md): Connect an LDAP directory or Active Directory through Dex. +- [Kerberos authentication](https://flox.dev/docs/floxhub-onprem/administration/users/identity/kerberos.md): Use deployment authentication overrides to integrate Kerberos and SPNEGO with FloxHub. ## FloxHub on-prem: Upgrade diff --git a/styles/config/vocabularies/Flox/accept.txt b/styles/config/vocabularies/Flox/accept.txt index bc0431b..1382bbd 100644 --- a/styles/config/vocabularies/Flox/accept.txt +++ b/styles/config/vocabularies/Flox/accept.txt @@ -48,6 +48,7 @@ dotenv dotfile dotfiles eksctl +Entra env envs formatters @@ -65,8 +66,10 @@ libiconv liveness lockfile lockfiles +lowercased mailcap manpages +misconfigured monorepo monorepos namespace @@ -76,12 +79,14 @@ Nodejs npm Nvidia nvm +Okta papercuts personalizations postgres rc repo repos +rollout runtimes sandboxed sandboxing