Auth & SSO

Goalrail 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:

GOALRAIL_AUTH_ENABLED=1 goalrail 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 goalrail server in a terminal and answer the username and password prompt.
   • For headless deploys, preset the password with --admin-password or GOALRAIL_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:

GOALRAIL_OIDC_ISSUER=https://accounts.google.com
GOALRAIL_DOMAIN=agents.yourcompany.com
GOALRAIL_OIDC_CLIENT_ID=...
GOALRAIL_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, Goalrail can read the user identity directly from X-Forwarded-Email. No additional auth configuration is needed on the Goalrail 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.

Domain allowlist

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

allowed_domains: [yourcompany.com]
admins: [[email protected]]

Invite outsiders

Need to let in someone outside your domain, like a contractor? Set GOALRAIL_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:

goalrail 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.