Single sign-on (SSO)
Set up SSO so staff and students sign in with the school’s identity provider — Microsoft Entra ID, Google Workspace, Okta and others — through SAML or OpenID Connect.
Admins
With SSO, people sign in to ValidBridge with the account they already use at school, managed by your identity provider (IdP). There are two ways to connect:
- SAML and managed connections (WorkOS)
- — the simplest route for Microsoft Entra ID (Azure AD), Google Workspace, Okta, Keycloak, Auth0 or any SAML provider. Your IT team completes a guided setup portal.
- Custom OIDC
- — connect directly to any OpenID Connect provider using a client ID and secret from your IdP.
Who can use it
SSO is an Enterprise plan feature and is set up by an organization admin under Developers → SSO (open SSO).
Option A — SAML via WorkOS
- In SSO Provider, choose WorkOS.
- Enter your WorkOS Organization ID (it starts with
org_). If you do not have one, email [email protected] and we will set it up for your school. - Click Save Configuration.
- Click Configure Identity Provider. The setup portal opens and walks your IT team through connecting your IdP step by step — it shows the values to paste into Entra ID, Google or Okta.
- Finish the options below and switch on Enable SSO.
Option B — Custom OIDC
First, register ValidBridge as an application (web app) in your IdP:
- Set the redirect URI (also called callback URL). It ends in
/api/v1/auth/sso/callback; email [email protected] to confirm the exact address for your organization, especially if you use your own domain. - Allow the
openid,emailandprofilescopes. - Copy the application's client ID and create a client secret.
Then, in ValidBridge:
- In SSO Provider, choose Custom OIDC.
- Issuer URL: your IdP's issuer, e.g.
https://login.microsoftonline.com/<tenant-id>/v2.0orhttps://accounts.google.com. Sign-in endpoints are discovered from it automatically. - Paste the Client ID and Client Secret.
- Leave Scopes as
openid email profileunless your IdP needs more (space-separated). - Finish the options below and click Save Configuration.
Options for both
- Allowed Email Domains
- — a comma-separated list such as
school.ac.ke, students.school.ac.ke. Only these addresses can sign in with SSO. Leave it empty to allow any. - Auto-provision Users
- — create an account automatically the first time someone signs in with SSO. When it is off, only people who already have an account (matched by email) can use SSO.
- Enable SSO
- — shows the SSO button on your sign-in page.
SSO must also be allowed under Users → Sign-in Methods — see Add and manage users.
What people see
- On your organization's sign-in page they click Sign in with SSO.
- They sign in at your identity provider as usual.
- They come back to ValidBridge, see Authenticating…, and land signed in. Existing accounts are matched by email address.
If your organization requires two-factor authentication, it still applies after SSO.
Troubleshooting
The SSO button does not appear
Check that Enable SSO is on, the configuration is saved, and SSO is allowed under Sign-in Methods.
“Your email domain is not allowed for this organization”
The person's address is not in Allowed Email Domains. Add the domain or have them use their school address.
Sign-in fails for someone new
Auto-provision Users is off and they have no account yet. Invite them first, or turn auto-provisioning on.
“Failed to authenticate with the identity provider”
Usually a wrong client secret, an expired secret, or a redirect URI that does not match. Check them in your IdP and in ValidBridge.
Keep a way back in
Before relying on SSO alone, make sure at least one admin can still sign in another way, in case the identity provider is unavailable. Treat the client secret like a password.
Was this article helpful?