OAuth and SSO

Let people sign in to your panel with an account they already have.

License required

Single sign-on needs the OAuth / SSO license feature. Without it the OAuth / SSO tab does not appear.

With single sign-on, a user signs in to BadgerPanel with an account from another service.

Navigate to Admin > Settings > General, then click the OAuth / SSO tab.

Global settings

These four switches apply to every provider. Each switch saves as soon as you click it. There is no Save button on this card.

Setting	Description
Enable OAuth / SSO	Permits sign-in through a third-party provider.
Allow Registration via OAuth	Permits a new account from a provider.
Auto-Link by Email	Links a provider account to a panel account with the same email address.
Require Email Verification	The provider must report the email address as verified.

TIP

The panel has no "SSO only" mode and no role mapping. A user with a password can still sign in with that password.

Supported providers

The panel ships with five providers:

• Google
• Microsoft
• Discord
• GitHub
• Twitter / X

Each provider is a card. The header shows the provider name, the state (Configured or Not configured), and a pill that reads Enabled or Disabled. Click the header to open the card.

Configuring a provider

1. Open the provider card.
2. Copy the Callback URL from the grey box at the bottom of the card. The form is https://your-panel/api/auth/oauth/PROVIDER/callback.
3. Create an application at the provider and register that callback URL. The steps for each provider are below.
4. Paste the Client ID and the Client Secret into the card. Leave the secret blank to keep a stored value.
5. Set the four switches:
   • Enabled - the provider is live.
   • Allow Login - an existing user with a linked account can sign in.
   • Allow Registration - a new user can create an account.
   • Auto-Link - the panel links by email address.
6. Click Test Provider to check the credentials.
7. Click Save Google, Save Discord, or the matching button for that provider.

TIP

The scopes are fixed. The page has no scope field.

Google

1. Open the Google Cloud Console. Create a project, or select one.
2. Navigate to APIs & Services > Credentials and create an OAuth 2.0 Client ID.
3. Add the panel callback URL as an authorized redirect URI.
4. Copy the client ID and the client secret.

Microsoft

1. Open the Azure Portal and navigate to Microsoft Entra ID > App registrations.
2. Create a registration. Set the redirect URI to the panel callback URL.
3. Navigate to Certificates & secrets and create a client secret.
4. Copy the application (client) ID and the secret value.

Discord

1. Open the Discord Developer Portal and create an application.
2. Navigate to OAuth2.
3. Add the panel callback URL as a redirect.
4. Copy the client ID and the client secret.

GitHub

1. Open the GitHub developer settings and create an OAuth App.
2. Set the authorization callback URL to the panel callback URL.
3. Copy the client ID and the client secret.

Twitter / X

1. Open the X developer portal and create an app with OAuth 2.0.
2. Set the callback URL to the panel callback URL.
3. Copy the client ID and the client secret.

What a user sees

The login page and the registration page show a divider that reads "or continue with". Under it the panel shows one button for each live provider, for example Continue with Google.

A button appears only when the provider is enabled and holds a client ID. When no provider qualifies, the panel shows no divider and no buttons.

Linking an account

A user manages links from Account > Profile, in the Linked Accounts card. The card lists each linked provider with the account name, the email address, the link date, and the last use.

• To link an account, use the "Continue with" button on the login page.
• To unlink an account, click the unlink icon on the row, then click Confirm.

Security notes

• Auto-Link by Email matches on the email address. A person who controls a provider account with the email address of a panel account gains that panel account. Turn auto-link on only for a provider that verifies email addresses.
• A user who registers through a provider has no password. That user can set a password later from the account pages.
• When you disable a provider, the existing links stay. Only new sign-ins and new registrations stop.
• If a provider becomes unreachable, a user with a password can still sign in. A user without a password cannot.

Login error messages

Message	Cause
OAuth access was denied.	The user cancelled at the provider.
OAuth session expired, please try again.	The sign-in took too long.
The OAuth provider returned an error.	The provider rejected the request.
An account with this email already exists.	Auto-link is off and the address is in use.
This OAuth provider is not configured.	The provider has no client ID or no secret.
Email address is required from the OAuth provider.	The provider returned no email address.