Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Excurs1ons/MonoRelay/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
How SSO login works

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

1

Create an OAuth app with your provider

Register a new OAuth application with GitHub or Google and set the callback URL to:
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.
2

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

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

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

FieldTypeDescription
enabledbooleanEnable or disable SSO.
providerstringOAuth provider: github, google, or prismaauth.
github_client_idstringClient ID from your GitHub OAuth app.
github_client_secretstringClient secret from your GitHub OAuth app.
google_client_idstringClient ID from your Google OAuth app.
google_client_secretstringClient secret from your Google OAuth app.
admin_usernameslistSSO usernames that receive admin role on first login.
sso_onlybooleanWhen 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
}
FieldDescription
enabledWhether SSO is turned on in config.
providerThe active OAuth provider.
configuredWhether the provider credentials are present and non-empty.
sso_onlyWhether 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us