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