Berserk Docs

Guide: Enabling Single Sign-on

Connect your identity provider to Berserk, step by step — what to register at the provider, what to enter on the Single sign-on page, and how to bring your team over

At the end of this guide your team signs in to Berserk through your identity provider, and the admin account you start with still signs in with its password. You need a cluster admin in Berserk and someone who can register an application at the identity provider; often that is one person. The reference for every setting is Accounts and Sign-in.

Start from a local admin

Sign in to Berserk as a cluster admin with a password. If the cluster is new, that is the first admin from the setup link or the pre-provisioned admin. Keep this account: it is the one that can sign in and repair single sign-on if the provider stops working, and Berserk will not let you switch or delete the last local admin while single sign-on is on.

Copy the redirect URI

Open Settings → Single sign-on. The page shows the redirect URI, https://<your Berserk URL>/auth/oidc/callback. Copy it with the button next to it; the identity provider needs it in the next step, character for character.

Register Berserk at your identity provider

Create an OpenID Connect client for Berserk. Providers name things differently, but every one of them asks for the same four things:

  • Application type: a web application using the authorization code flow. Berserk also uses PKCE, which every provider accepts. Berserk is a confidential client, so the provider must issue a client secret.
  • Redirect URI: the one you copied. A provider that lets you add several only needs this one.
  • Scopes or claims: openid, email and profile. Berserk reads the email, email_verified, given_name and family_name claims from the ID token, so make sure the provider includes them; some providers call these "optional claims" or "profile mapping".
  • Who may sign in: assign the users or groups that should reach Berserk. Everyone the provider lets through can sign in, and the next step decides whether that creates an account.

Then write down three values:

ValueWhere it comes from
Issuer URLThe provider's discovery document at <issuer>/.well-known/openid-configuration states it in its issuer field. Copy it from there, exactly, trailing slash included or not: Berserk compares the two and refuses a mismatch.
Client IDShown on the client you created.
Client secretGenerated once by the provider; it shows the value only at creation. Berserk needs at least 32 characters, which every major provider's secrets have. Copy it now.

Where the issuer URL is for the common providers:

  • Microsoft Entra ID: https://login.microsoftonline.com/<tenant-id>/v2.0, from the app registration's endpoints page ("OpenID Connect metadata document").
  • Google Workspace: https://accounts.google.com.
  • Okta: your org's URL, https://<org>.okta.com, or a custom authorization server such as https://<org>.okta.com/oauth2/default.
  • Keycloak: https://<host>/realms/<realm>.
  • Others: open the provider's .well-known/openid-configuration and read issuer.

Enter the settings in Berserk

Back on Settings → Single sign-on, fill in the Issuer URL, the Client ID and the Client secret. Then decide two things:

  • New sign-ins create accounts. On, anyone the provider lets through gets an account at their first sign-in. Off, only members you add on Settings → Members can sign in through the provider.
  • Admin emails. The people who should be cluster admins when their account is created, one per line, including yourself if you also want to sign in through the provider later. Your current local admin account is not affected by this list.

Leave Require a verified email on unless your provider does not set the email_verified claim. Click Enable SSO. Berserk fetches the provider's discovery document and refuses the save if the issuer does not match or the provider does not answer; the message says what the provider stated. When it succeeds, the status shows Enabled, and the login page offers "Continue with SSO" above the password form.

Sign in once through the provider

In a private browser window, open your Berserk URL and click Continue with SSO. Sign in at the provider. You land in Berserk, and Settings → Members now lists your SSO account with the SSO badge, named from the provider's claims.

If the provider sends you back with an error, the table at the end of this guide has the common ones.

Bring your team over

Three ways, which you can mix:

  • Let them in. With New sign-ins create accounts on, everyone the provider admits gets an account the first time they click "Continue with SSO".
  • Add them first. With it off, add each member by email on Settings → Members: open the invite dialog and choose Add an SSO member instead. They sign in through the provider and their name arrives with the first sign-in. Pick the admin role for the ones who should have it.
  • Switch existing members. A local member's detail on Settings → Members offers Switch to SSO: the password goes, their sessions and roles stay, and from then on they sign in through the provider. Berserk keeps you from switching the last local admin.

Keep at least one local admin, and keep its password where you can find it.

If something goes wrong

Disable SSO on the Single sign-on page always works and never waits on the provider: the settings and the secret stay, SSO accounts cannot sign in until you enable it again, and nobody who is signed in is signed out. If no local admin exists and the provider is broken, the way back in is database access: UPDATE oidc_config SET enabled = FALSE in the gateway's auth database.

What you seeWhat it means
"the discovery document does not match the issuer … unexpected issuer URI …"The Issuer URL is spelled differently from the provider's issuer, often a trailing slash. Use the spelling the message quotes as the provider's.
"issuer URL unreachable" or "responded with 4xx"The gateway cannot fetch <issuer>/.well-known/openid-configuration: a typo in the issuer, or the provider is not reachable from the cluster.
The provider says the redirect URI is invalidThe URI registered at the provider differs from the one the page shows. Register exactly that one.
"OIDC token exchange rejected: invalid_client"The client secret or client ID is wrong. Enter the secret again on the page.
"OIDC id_token claim 'email_verified' is false"The provider does not vouch for the email. Verify it at the provider, or turn Require a verified email off if the provider never sets the claim.
"this account signs in with a password"The email belongs to a local account. Sign in with the password, or have an admin switch the account to SSO.
"user is not provisioned"New sign-ins create accounts is off and the email is not a member yet. Add it on Settings → Members.

Accounts and Sign-in

Local and SSO accounts, how the first admin comes to be, the Single sign-on settings, the trusted reverse proxy, and the Helm values behind each

Network Policies

Securing inter-service communication with Kubernetes NetworkPolicies

On this page

Start from a local adminCopy the redirect URIRegister Berserk at your identity providerEnter the settings in BerserkSign in once through the providerBring your team overIf something goes wrong