SSO providers

dockmesh supports four SSO protocols as first-class providers — all part of the single binary, no paid add-on:

OIDC (OpenID Connect) — Azure AD / Entra ID, Google Workspace, Keycloak, Authentik, Okta, Dex, Auth0, Zitadel, GitLab, anything with a .well-known/openid-configuration document
OAuth2 — providers that expose an OAuth-only auth flow without an OIDC discovery doc (e.g. GitHub, GitLab.com when using a personal OAuth app, custom internal SSO)
SAML 2.0 — Azure AD, Okta, OneLogin, Keycloak, ADFS, etc. dockmesh acts as Service Provider; XML assertions land at the dockmesh callback
LDAP / LDAPS — bind to your existing directory (Active Directory, OpenLDAP, FreeIPA) and authenticate users against it

Each protocol has its own provider list under Authentication in the sidebar. You can configure many providers of any kind simultaneously — the sign-in screen shows a button per enabled provider.

Configuring a provider

Authentication → pick the protocol → Add provider. The form has a common header and a protocol-specific config block.

Common header (all four kinds)

Field	Example
Slug	`azure-ad` — used in the callback URL and as a stable id
Display name	`Azure AD`
Enabled	checkbox
Default role	role assigned to new users when no group mapping matches (defaults to `viewer`)

OIDC config

Field	Example
Issuer URL	`https://login.microsoftonline.com/<tenant>/v2.0`
Client ID	`xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
Client secret	`•••••••`
Scopes	`openid,profile,email,groups` (comma-separated)
Group claim	`groups` — the claim in the ID token carrying group memberships

Test connection runs the discovery request against the issuer URL and reports whether .well-known/openid-configuration parses.

OAuth2 config asks for the same fields as OIDC plus the auth + token + userinfo URLs explicitly (OAuth2 has no discovery doc).

SAML config asks for the IdP metadata URL (or pasted XML), the entity ID, and the assertion-consumer-service URL dockmesh should advertise. dockmesh generates its SP signing keypair on first save and exposes the metadata at /api/v1/auth/saml/<slug>/metadata for import into the IdP.

LDAP config asks for the server URL (ldaps://…), bind DN + password, search base, user filter, and the attribute that carries group memberships. Bind credentials are encrypted at rest with the dockmesh age key.

The callback URL is auto-built from the slug and shown at the top of every form. Whitelist it in your IdP — the exact path differs per protocol (/api/v1/auth/oidc/<slug>/callback, /api/v1/auth/saml/<slug>/acs, etc.).

Group mapping

Each provider has its own group mappings table — pairs of (group_value, role_name). On every login, dockmesh reads the group claim (or LDAP group attribute, or SAML group assertion), walks the mappings list, and assigns the first matching role. If nothing matches, the provider’s default role is used.

The mapping is fully generic — you can map any group string to any built-in role or any custom role you’ve defined in the Roles tab. So dockmesh-admins → admin, dockmesh-ops → operator, dockmesh-team-frontend → Team-Frontend-Operator (custom) all work side-by-side. Order matters in the list: the first match wins.

Scope tags (host:/stack:/host_tag:) are not set by SSO groups today — they live on the user record and on the assigned role. If you need “group X gets scoped to host_tag=prod”, map the group to a custom role whose role-scope already restricts to that tag (see RBAC scopes).

Tested providers

Provider	Issuer URL format	Group claim
Azure AD / Entra ID	`https://login.microsoftonline.com/<tenant>/v2.0`	`groups`
Google Workspace	`https://accounts.google.com`	via a custom scope + claim mapping
Okta	`https://<org>.okta.com`	`groups`
Keycloak	`https://kc.example.com/realms/<realm>`	`groups` or custom mapper
Authentik	`https://authentik.example.com/application/o/<slug>/`	`groups`
Dex	`https://dex.example.com`	`groups`

If your provider speaks OIDC and exposes a discovery document, it will work — the tested list is not an allow-list.

First user

On a fresh install, the first user to log in via any configured provider is automatically promoted to Admin regardless of group mappings — otherwise nobody would have permission to set up group mappings in the first place. After the first admin exists, group mapping applies normally.

This behaviour is backend-only; there is no UI toggle to change it. Once there is at least one admin on the system you can demote or delete the original if needed.

Local accounts

OIDC and local username+password coexist. Local accounts are created from Users & Roles → Users tab → New user. There is currently no UI toggle to disable local login after SSO is set up — if you need to lock out local auth entirely, remove every local user except one break-glass admin and keep that account’s password in a vault.