SSO setup

Who this is for: Tenant owner
What you'll achieve: Enable Microsoft, Google, or Okta sign-in on your school login page

End-to-end IdP guides

For full pilot checklists (SCIM + SSO + groups + testing), use the IdP pilot runbooks:

• Microsoft Entra ID
• Okta
• Google Workspace

Requires role

sso.configure. Tenant owner

How it works

1. You save an OIDC config in Admin → People → School sign-in (IT) → Single sign-on
2. Register the redirect URI in your identity provider
3. Mark the config Active: a Sign in with … button appears on the login page
4. Staff authenticate at the IdP; SchoolRota creates or links their user and staff profile

SCIM provisioning (optional) can sync the roster first: see SCIM provisioning.

Redirect URI (all providers)

Register this exact callback URL in your IdP:

https://{your-portal-host}/api/auth/oidc/callback

Local dev example: http://localhost:3001/api/auth/oidc/callback

Admin steps

1. Sign in as tenant owner → Admin
2. Under Single sign-on (OIDC) enter:
   • Issuer URL: e.g. https://login.microsoftonline.com/{tenant-id}/v2.0
   • Client ID and Client secret from the IdP app registration
   • Group → role map: JSON mapping IdP group names to SchoolRota roles
3. Check Active when ready
4. Select Save OIDC config

Example group map:

{
  "SchoolRota Admin": "admin",
  "SchoolRota Duty Lead": "duty_lead",
  "All Teachers": "staff"
}

Valid roles: admin, duty_lead, office, staff, viewer.

Microsoft Entra ID

Full Entra pilot runbook

See Microsoft Entra ID pilot runbook for SCIM + SSO + groups in one checklist.

1. App registrations → New registration
2. Redirect URI: Web → your callback URL above
3. Certificates & secrets → new client secret
4. Copy Application (client) ID, Directory (tenant) ID, and secret into Admin
5. Issuer: https://login.microsoftonline.com/{tenant-id}/v2.0
6. Optional: Token configuration → add groups claim for role mapping

Okta

Full Okta pilot runbook

See Okta pilot runbook for the complete end-to-end checklist.

1. Applications → Create App Integration → OIDC → Web Application
2. Sign-in redirect URI: SchoolRota callback URL
3. Copy Client ID and Client secret
4. Issuer: your Okta org URL + /oauth2/default (or custom auth server)

Google Workspace

Full Google pilot runbook

See Google Workspace pilot runbook for SSO setup and roster sync options.

1. Google Cloud Console → APIs & Services → Credentials → OAuth client (Web)
2. Authorized redirect URI: SchoolRota callback URL
3. Issuer: https://accounts.google.com

TIP

Google group membership in tokens may require additional workspace/admin setup. Many schools use Entra or Okta as the primary SSO source.

Linking SCIM + SSO

Step	System
Roster sync	SCIM → creates users + staff profiles
Sign-in	SSO → links sub claim to existing email / provisions on first login

A user provisioned via SCIM can sign in with SSO once their email matches.

Troubleshooting

Problem	What to try
No SSO button	Config must be Active and tenant must have sso feature enabled
sso_state_mismatch	Retry login; cookie blocked or expired
Token exchange failed	Check client secret, redirect URI, and issuer URL
Wrong role	Update group → role JSON map; check IdP sends groups claim

Related

• IdP pilot runbooks. Entra, Okta, Google end-to-end checklists
• SCIM provisioning
• Microsoft profile photos
• Signing in
• Admin users