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. Built-in accounts is the default mode.

For non-Docker deploys, enable it manually:

OMNIGENT_AUTH_ENABLED=1 omni server start

Create the first admin. The server never auto-generates a password. While no admin exists it reports needs_setup: open the web UI and create the admin account there, or run omni server on a terminal and answer the username and password prompt. For headless deploys, preset the password with --admin-password or OMNIGENT_ACCOUNTS_INIT_ADMIN_PASSWORD.

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.

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

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

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.