Configure OAuth single sign-on with GitHub or Google

MonoRelay supports OAuth single sign-on via GitHub, Google, or PrismaAuth for dashboard login. When SSO is enabled, users click “Login with GitHub” or “Login with Google”, complete the OAuth flow on the provider’s website, and are redirected back to MonoRelay with a local JWT token — the same kind used by local accounts. When a user initiates an SSO login, MonoRelay redirects them to the OAuth provider’s authorization page. After they grant access, the provider sends an authorization code back to MonoRelay’s callback endpoint (/api/auth/sso/callback). MonoRelay exchanges this code for the user’s profile, finds or creates a matching local account, and issues a JWT token. From that point on, the user authenticates with their JWT exactly like any other user.

SSO users receive a standard MonoRelay JWT after login. They use it identically to local account tokens — pass it as Authorization: Bearer <token> on every API request.

Setup

Create an OAuth app with your provider

http://your-domain/api/auth/sso/callback

GitHub: Go to github.com/settings/developers → “OAuth Apps” → “New OAuth App”. Set the “Authorization callback URL” to the value above.Google: Go to the Google Cloud Console → “APIs & Services” → “Credentials” → “Create credentials” → “OAuth client ID”. Add the callback URL to the list of authorized redirect URIs.After creating the app, copy the client ID and client secret — you will need them in the next step.

Add SSO configuration to config.yml

Add an sso section to your config.yml. The example below shows GitHub; for Google, replace the github_* fields with google_* fields.GitHub:

sso:
  enabled: true
  provider: "github"
  github_client_id: "your-github-client-id"
  github_client_secret: "your-github-client-secret"
  admin_usernames:
    - "your-github-username"
  sso_only: false

Google:

sso:
  enabled: true
  provider: "google"
  google_client_id: "your-google-client-id"
  google_client_secret: "your-google-client-secret"
  admin_usernames:
    - "your-google-username"
  sso_only: false

MonoRelay picks up configuration changes without a restart when hot-reload is active.

Optionally promote SSO users to admin

Add usernames to admin_usernames to automatically grant the admin role to those users when they first log in via SSO. The username is the login name from the OAuth provider (for example, your GitHub username).

sso:
  admin_usernames:
    - "alice"
    - "bob"

Users already in the database will be promoted to admin on their next SSO login if their username appears in this list.

Optionally disable local password login

Set sso_only: true to prevent anyone from logging in with a local username and password. Only SSO login will be accepted.

sso:
  sso_only: true

Enabling sso_only will lock out all local accounts, including the super admin. Make sure at least one SSO user with admin rights can sign in before enabling this option.

Configuration reference

Field	Type	Description
`enabled`	boolean	Enable or disable SSO.
`provider`	string	OAuth provider: `github`, `google`, or `prismaauth`.
`github_client_id`	string	Client ID from your GitHub OAuth app.
`github_client_secret`	string	Client secret from your GitHub OAuth app.
`google_client_id`	string	Client ID from your Google OAuth app.
`google_client_secret`	string	Client secret from your Google OAuth app.
`admin_usernames`	list	SSO usernames that receive admin role on first login.
`sso_only`	boolean	When `true`, disables local username and password login.

Check SSO status

You can check whether SSO is enabled and correctly configured without authenticating by calling the status endpoint.

curl https://your-domain/api/auth/sso/status

{
  "enabled": true,
  "provider": "github",
  "configured": true,
  "sso_only": false
}

Field	Description
`enabled`	Whether SSO is turned on in config.
`provider`	The active OAuth provider.
`configured`	Whether the provider credentials are present and non-empty.
`sso_only`	Whether local password login is disabled.

Use this endpoint in your deployment health checks to verify that SSO credentials were loaded correctly after a configuration change.

Get Started

Configuration

Admin Dashboard

Authentication

Configure OAuth single sign-on with GitHub or Google

Setup

Configuration reference

Check SSO status

​How SSO login works

​Setup

​Configuration reference

​Check SSO status

How SSO login works

Setup

Configuration reference

Check SSO status