Skip to main content
By default, the Datris OSS install runs single-tenant with no login screen — anyone who reaches the UI URL has full access. For shared installs (a team running Datris on a server, a managed deployment, anything past your laptop), turn on user authentication so the UI requires a login and the Configuration tab is admin-only.

​
What it does

When USE_USER_AUTH=true:
  • The UI shows a login screen before any tab is reachable.
  • Sensitive Configuration sub-tabs (Secrets, API-Keys, Audit Log, Agent Policy) are gated to admin users. The AI Providers, Data Sources, and Code Repository sub-tabs remain visible to all roles. The Users and API-Keys sub-tabs appear based on the active flags (see the matrix for full visibility rules).
  • A new Users sub-tab appears under Configuration for adding, removing, and changing roles (admin-only by virtue of being inside Configuration).
  • Sessions are server-side, with a TTL index cleaning them up automatically.
When the flag is off, the toggle has zero effect on data — pipelines, taps, secrets, and run history all work the same.

​
Enabling it

  1. Read and save the seed account’s bootstrap password. The server generates it at random when it seeds admin (on the first boot, whether or not USE_USER_AUTH is on) and prints it once, in the log of that container only. Recreating the container (step 3) discards that log, so read it first:
    If nothing is printed, the container has been upgraded or recreated since admin was seeded and the line is gone; see Recovering admin access. If you already set your own admin password, use that.
  2. Add the flag to your .env:
  3. Recreate the Datris container:
  4. Open the UI. You’ll see the login screen.
  5. Log in as admin with the password from step 1, then change it right away (your username in the top-right → Change password, minimum 5 characters). After that, admin is your administrator account.
A new install can switch on login, API keys, the audit log and the agent policy in one step: run the installer with DATRIS_GOVERNED=1. See Switch on the governance controls.
The default admin row is seeded on every startup (idempotent — only when the user table is empty), regardless of whether USE_USER_AUTH is on, with a fresh bootstrap password printed once to that container’s log. The line does not survive an upgrade or a recreate of the container, so save it when you first install. That means flipping the flag on later “just works” — there’s no separate provisioning step.

​
Roles

All roles see the Configuration tab in the top nav, but the sub-tabs differ: admins see Secrets, API-Keys, Audit Log, and Agent Policy; editors and viewers see only AI Providers, Data Sources, Code Repository, and Users. Everything outside Configuration (Pipelines, Taps, Search, etc.) is accessible to all roles per the read/write rules above.

​
Adding users

As an admin: Configuration → Users → Add user. Fill in username + role and an initial password (type one, or click the generate button for a strong random one). Send the user their username and password out-of-band, and ask them to change it after their first login. Through the API, a POST /api/v1/auth/users body that omits password generates a random temporary password and returns it once as temporaryPassword. You can change a user’s role or delete them from the same screen. Datris won’t let you remove the last admin — there’s an adminCount guard on delete and role-change.

​
Changing your own password

Click your username in the top-right → Change password. Enter your current password and the new one (min 5 chars). If you’ve forgotten your password and there’s another admin: have them delete and re-add your user with a new initial password and send it to you; log in with it and change it. If you’re the only admin and you’ve lost the password, see Recovering admin access.

​
Recovering admin access

Use this when you are the only admin and cannot log in: you lost the password, or the admin bootstrap password is no longer in the server log (it is printed once, and an upgrade or recreate of the container discards it). At startup the server gives every account that has no password a new random bootstrap password and prints it once. So clear the account’s password in MongoDB, then recreate the server. With the bundled MongoDB and the default environment oss, users live in the oss-user collection of the oss database (the server’s internal database):
The last line prints User 'admin' had no password set ... Assigned a bootstrap password: <password>. Log in as admin with it and change it right away. Other users are untouched. Until you recreate the server, the cleared account cannot log in at all. With the audit log on, the rotation is also recorded as user / rotate-password on the account, with the system actor and the time, just before that boot’s system / start entry. The password itself is never in the audit log: it was printed to the log of the server container that started at that time, so if you find a rotate-password row you did not expect, that container’s log is where the password went. An admin clearing a password from Configuration → Users is recorded separately as user / reset-password, with the admin as the actor.

​
Single sign-on (OIDC)

With user authentication on, Datris can also sign people in through your company identity provider (Okta, Microsoft Entra ID, Google Workspace, Keycloak, Auth0, or any OpenID Connect provider). The login screen gains a Sign in with SSO button next to the username and password form. Sign-in uses the OIDC authorization code flow with PKCE. Someone who signs in this way becomes an ordinary Datris user with one of the three roles above, so sessions, role checks, the Users screen and the audit log work exactly as they do for password users. API keys, the CLI and MCP clients are unaffected: SSO is for people using the UI.

​
MFA and password rules

Datris does not run its own multi-factor authentication. For people who sign in with SSO, MFA, password rules and lockout are whatever your identity provider enforces, so turn MFA on there. Local accounts (including admin) still use a password with a minimum length only and no lockout.

​
Settings

The client secret is never put in .env or the compose file. Store it in Vault under oss/oidc, key clientSecret:
No tap or pipeline can reference this secret. At the provider, register a confidential client (one with a client secret) that uses the authorization code flow, with /api/v1/auth/oidc/callback on your UI host as its redirect URI, and PKCE method S256 if the provider asks. The client authenticates to the token endpoint with HTTP Basic (client_secret_basic). Recreate the Datris container after changing any setting:
The server checks the settings once at startup, without contacting the identity provider. If OIDC_ISSUER, OIDC_CLIENT_ID or OIDC_REDIRECT_URI is missing, the issuer or redirect URI is not an http(s) URL, or the Vault secret oss/oidc (key clientSecret) is not there, the server still starts and password login keeps working: SSO is switched off, the reason is logged once at ERROR, and the button is hidden. OIDC_ENABLED=true without USE_USER_AUTH=true also leaves SSO off (logged once at WARN). An identity provider that is down or unreachable is different: the server does not contact it until someone presses the button, so it starts normally and the Sign in with SSO button stays visible. Each press then fails: the person lands back on the login screen with a “could not be completed” message (or, if the provider went down after a recent successful sign-in, the browser cannot reach the provider’s sign-in page), and the server logs one ERROR line per failed attempt. Password login is unaffected. SSO works again as soon as the provider is reachable; no restart is needed.

​
How a person maps to a user and role

  • Username. The value of the OIDC_USERNAME_CLAIM claim, trimmed and lower-cased, is the Datris username. It must use letters, digits and . _ @ - only. When the claim is email and the provider says the address is not verified (email_verified: false), sign-in is refused.
  • Existing user. Keeps the role set on Configuration → Users. To let someone in with a role you choose, add them there first (for example alice@example.com as editor); the password you set for them is not needed for SSO.
  • Unknown person. Refused with “ask an administrator to add you” unless OIDC_DEFAULT_ROLE is viewer or editor, in which case the user is created with that role and a random password nobody is told. Promote people to admin on the Users screen.
  • The recovery account. The built-in admin account can never be reached through SSO; it always signs in with its password.
  • Identity binding. The first SSO sign-in stores the provider’s subject id (sub) on the user. A later sign-in with the same username and a different subject (an email address reassigned to someone else) is refused. To allow it, delete the user and add them again.
Every SSO sign-in, and every refusal, is recorded in the audit log as auth / login with method: oidc in the metadata.

​
Removing access

Disable or remove the person at your identity provider. Datris does not check back with the provider during a session, so a session already open stays valid for up to its 8-hour sliding lifetime (it is extended while the person keeps using the UI). Deleting the user on Configuration → Users stops further SSO sign-ins only when OIDC_DEFAULT_ROLE is empty.

​
Trying it with Keycloak

A local walkthrough on macOS with Docker Desktop. The browser and the datris container must reach Keycloak under the same host name, because that name is part of the issuer:
Add to .env:
Then docker compose up -d --force-recreate datris. curl -s http://localhost:8080/api/v1/version now reports "oidcEnabled": "true". Sign in as admin with the password, add alice@example.com as editor on Configuration → Users, sign out, press Sign in with SSO and log in at Keycloak as alice / alice-pass. To clean up: docker rm -f keycloak and remove the OIDC_* lines from .env.
SSO is single-tenant: with MULTI_TENANT=true it is not verified and signs people in to the default environment’s users. One identity provider per install.

​
Reverting

Set USE_USER_AUTH=false (or remove the line) and recreate the Datris container. The login screen disappears; the Configuration tab is unrestricted again. User rows persist in the database — they just aren’t checked. Flipping back on later returns you to the same set of users with the same passwords.

​
Production checklist

  • Run Datris behind HTTPS before turning auth on. Sessions are cookie-based; without TLS, the login is exposed in transit.
  • Review your CORS allow-list (cors.allowedOrigins in application.yaml) — the default "*" is for local dev only.
  • To sign people in with your company identity provider and its MFA, turn on single sign-on.
  • Pair this with USE_API_KEYS=true for any shared install — user auth gates the UI, API-key gating handles programmatic clients (CLI, MCP, external scripts). API keys are meant to be used alongside user auth: enable the two together. Turning on USE_API_KEYS=true without USE_USER_AUTH=true leaves the browser with no coherent auth mechanism — see supported configurations; the two are designed to compose.
  • API Keys — the paired flag. Required for any deployment where the UI or CLI talks to a real install.
  • Configuring Claude — connecting AI agents via MCP. MCP clients use the API-key path, not user auth.
  • Configuration Reference — the underlying useUserAuth, useApiKeys, multiTenant and oidc.* keys in application.yaml.