Auth & SSO

Omnigent supports three ways to authenticate users. Pick the one that fits your setup:

Built-in accounts

If you deployed with Docker or a cloud platform, auth is already enabled by default with built-in accounts.

Non-Docker deploys

For non-Docker deploys, enable built-in accounts manually:

OMNIGENT_AUTH_ENABLED=1 omni server start

1. Create the first admin.
   • For better security, the server never auto-generates a password. When no admin is configured, the server will report needs_setup.
   • To configure, open the web UI and create an admin account or run omni server in a terminal and answer the username and password prompt.
   • For headless deploys, preset the password with --admin-password or OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD.
2. Invite teammates.
   • Go to Admin > Members > Invite to create a single-use invite link.
   • No email server needed; just send the link directly. Signup is invite-only.

Single sign-on (OIDC)

Let your team sign in with Google, GitHub, Okta, or Microsoft. Adding an OIDC issuer flips the mode to SSO. No extra flag needed.

Set the following in deploy/docker/.env:

OMNIGENT_OIDC_ISSUER=https://accounts.google.com
OMNIGENT_DOMAIN=agents.yourcompany.com
OMNIGENT_OIDC_CLIENT_ID=...
OMNIGENT_OIDC_CLIENT_SECRET=...

docker compose up -d    # restart to apply

The only outside step is creating an app with your provider (e.g. Google Cloud Console, or GitHub > Settings > Developer settings) to get the client ID and secret. Set its callback URL to https://<your-domain>/auth/callback.

Skipping the email-verified check

By default, Omnigent requires the id_token to carry a truthy email_verified claim before it will trust the email as the user's identity — a signed token proves the IdP issued it, not that the mailbox was verified. An absent or false email_verified claim is a hard reject that surfaces as "Could not determine user email" at login.

Some IdPs omit the claim for directory-provisioned users even though the directory is authoritative for the address — for example Okta without custom API Access Management. To admit those users, set:

OMNIGENT_OIDC_SKIP_EMAIL_VERIFICATION=1

This is off by default. When enabled, Omnigent accepts any signed email claim from the issuer as the user's identity, and logs a warning at startup. Only enable it when the issuer is a trusted enterprise directory. It affects the generic-OIDC path only — the GitHub sign-in path always requires a verified primary email.

Header-based auth

If your server sits behind an existing SSO proxy (e.g. OAuth2 Proxy, Cloudflare Access) that injects a trusted header, Omnigent can read the user identity directly from X-Forwarded-Email. No additional auth configuration is needed on the Omnigent side.

Access control

Once auth is enabled, control who can sign in and what they can access.

Scope depends on the auth mode. allowed_domains applies to OIDC sign-ins only; leaving it empty means no domain restriction. Built-in accounts are invite-only, so domain allowlists do not apply there, and header-based auth delegates identity entirely to your proxy. The admins list works in both built-in accounts and OIDC modes.

Admins and the management surface

Admins are the identities in the admins list (above), plus anyone you add to the runtime-editable <data_dir>/admins file (reloaded without a restart). Listed identities are promoted to admin on their next sign-in.

Admins get two management sections in the web UI under Settings, in both built-in accounts and OIDC modes:

• Settings > Members — the user roster (username, role, last login).
• Settings > Policies — server-wide contextual policies.

In built-in accounts mode, Members also carries the management actions (Invite member, per-user Reset password, and Remove); under OIDC it is a read-only roster, since identities are owned by your IdP and provisioned on first sign-in. Separately, every signed-in account (built-in or OIDC) gets a Settings > Account section showing who they're signed in as, with a sign-out control and, in built-in accounts mode only, Change password.

Domain allowlist

Restrict sign-ups to specific email domains. In your server config (/data/config.yaml):

allowed_domains: [yourcompany.com]
admins: [you@yourcompany.com]

Invite outsiders

Need to let in someone outside your domain, like a contractor? Set OMNIGENT_OIDC_ALLOW_INVITES=1 and send them a one-time invite link.

Migration

Already using one auth mode and want to switch? These commands move your existing users across without losing sessions or admin rights.

From built-in accounts to SSO

If you started with built-in accounts and want to switch to OIDC, one command brings everyone across so they keep their sessions and admin rights:

omni debug migrate-accounts-to-oidc <database-url> --domain yourcompany.com --commit

Without --commit the command is a dry run that reports what would change without modifying anything.