Admin Guide

Custom OAuth providers

Add any OIDC-compliant custom sign-in method

Besides the built-in OAuth providers, Root can add any OIDC-compliant custom sign-in method. Sign in with the Root account, open the system settings page (`/console/setting`) and find the "Custom OAuth" section. The web console follows the reference design and is still being wired up; for now, the demo data is linked to the sign-in page through localStorage.

Add a custom OAuth provider

Configure custom OAuth providers. Any identity provider compatible with OAuth 2.0 / OpenID Connect is supported, such as GitHub Enterprise, GitLab, Gitea, NextCloud, Keycloak and Casdoor. Callback URL format: {Site URL}/oauth/{slug}

+ Add OAuth provider

Icon	Name	Slug	Status	Client ID	Actions
No custom OAuth providers yet

Preview of the "Custom OAuth" section at the bottom of System settings: info banner, add button and empty list

Open the settings section

After signing in as Root, open /console/setting and scroll to the "Custom OAuth providers" card at the bottom of the page. Like the other tabs in System settings, it is part of the option / custom_oauth_provider configuration.

Add a provider

Click "+ Add OAuth provider" to open the form and fill in the name, Slug, Client ID/Secret and OAuth endpoints. Avoid changing the Slug after creation; otherwise you must update the callback URL on the IdP side as well.

Callback URL format

In the IdP app settings, set the Redirect URI to:

{Site URL}/oauth/{slug}

Here, "Site URL" is ServerAddress from System settings (e.g. https://ai.example.com), and {slug} matches the Slug field in the form.

Provider list

Column	Field	Description
Icon	`icon`	Provider logo URL or icon identifier
Name	`name`	Label shown on the sign-in button, e.g. "Company GitLab"
Slug	`slug`	Unique identifier used in the callback path `/oauth/{slug}`
Status	`enabled`	When enabled, the provider appears in the third-party section of the sign-in and sign-up pages
Client ID	`client_id`	Client ID issued after registering the app with the IdP (can be masked in the list)
Actions	—	Edit, enable/disable, delete

Configure Client ID / Secret

Create an OAuth / OIDC app in your IdP (GitLab, Keycloak, etc.) and note the Client ID and Client Secret.
Set the callback URL to `{ServerAddress}/oauth/{slug}`; the slug must exactly match the Slug entered in EasyAPI.
In EasyAPI, go to System settings → Custom OAuth → "Add OAuth provider" and fill in the endpoints and scopes; providing well_known simplifies endpoint setup.
Save and enable it (enabled=1). Only enabled providers appear in the third-party section at the bottom of `/login` and `/register`.

Form fields

Setting	Field	Description
Name	`name`	Required; shown on the sign-in button
Slug	`slug`	Required; lowercase letters, globally unique; determines the callback URL path
Icon	`icon`	Optional; icon URL
Client ID	`client_id`	Client ID of the OAuth app
Client Secret	`client_secret`	Secret of the OAuth app; not shown in plain text in the list after saving
Authorization endpoint	`authorization_endpoint`	OAuth authorize URL
Token endpoint	`token_endpoint`	OAuth token URL
User info endpoint	`user_info_endpoint`	API that returns the user profile
Scopes	`scopes`	Defaults to openid profile email; adjust as your IdP requires
Well-Known	`well_known`	Optional; OIDC `.well-known/openid-configuration` URL for automatic endpoint discovery
User ID field	`user_id_field`	Key used to read the unique ID from the userinfo JSON; defaults to sub
Username field	`username_field`	Mapped to the system username; defaults to preferred_username
Display name field	`display_name_field`	Mapped to nickname; defaults to name
Email field	`email_field`	Mapped to email; defaults to email
Auth style	`auth_style`	0 = send client_secret as a parameter; 1 = send it in a header (required by some IdPs)
Access policy	`access_policy`	Optional JSON that limits which users may sign in
Denial message	`access_denied_message`	Message shown to users when the policy denies access

The fields of the custom_oauth_provider table map one-to-one to the form above; the slug column has a unique index.

Endpoints and scopes

Standard OIDC: fill in well_known to resolve the authorization / token / userinfo endpoints automatically
Plain OAuth 2.0: fill in authorization_endpoint, token_endpoint and user_info_endpoint manually
Example scopes: openid profile email (OIDC) or read:user user:email (GitHub)
Built-in OAuth routes such as GET /api/oauth/github and wechat coexist with custom /oauth/{slug} routes without conflict

Test the OAuth callback

Sign out, open `/login` and check that the new OAuth button appears at the bottom.
Clicking the button should take you to the IdP authorization page; after authorizing, you are redirected to `{Site URL}/oauth/{slug}` and signed in or your account is linked.
Under "Profile settings → Account linking", verify that the third-party account is linked.
If it fails, check that the Client Secret, callback URL, scopes and userinfo field mappings match the JSON returned by the IdP.

For the user-side OAuth sign-in flow, see the "Third-party OAuth sign-in" section of the Sign up and sign in docs.

For an overview of system settings, see System settings
For account linking, see Profile settings (/setting)
Only providers with enabled=1 appear on the sign-in page; disabling a provider does not affect users who already linked it