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. SetFLOXHUB_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
for where that setting lives.
Connect your provider
Three steps, the same for every provider. 1. Write the connector. Createdex/connectors.yaml in the deployment’s
cache directory, with a top-level connectors: key. The examples below give
the minimal shape for each provider.
2. Register the callback URL with your provider:
Okta
Create an OIDC — Web Application app integration in the Okta admin console, with the callback URL as the sign-in redirect URI.Entra ID
Register an application under App registrations — web platform, with the callback URL as the redirect URI — and create a client secret. Themicrosoft
connector handles the Entra specifics.
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.LDAP and Active Directory
The LDAP connector binds with a read-only service account and authenticates users by search-then-bind.SAML is not supported
FloxHub does not offer a SAML connector. The upstream implementation is unmaintained, is documented as likely vulnerable to authentication bypass, and is under consideration for removal. Every provider above — and most providers of the SAML era — also expose OIDC. Connect through that instead.Other providers
The four above are the configurations FloxHub documents. The broker supports more, and options beyond these minimal examples are documented upstream at dexidp.io/docs/connectors.What the deployment takes from your provider
On a successful sign-in, the deployment reads three things from the identity your provider asserts:
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.
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. Organization membership is managed inside FloxHub, and a person’s groups in your directory have no effect on it. Plan for that: adding somebody to a directory group gets them a working sign-in, not access to a shared namespace.Verify and troubleshoot
Confirm the broker is answering and advertising the issuer you expect: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:
404 here means the deployment has the broker disabled, which the Flox CLI
reads as “no sign-in available here”.
Broker logs carry the provider’s own error responses, which is where a
misconfigured client secret or an unregistered callback shows up. See
Log system.