SCIM provisioning

Who this is for: Tenant owner at a larger school or trust (100 or more seats, or more than one school)
What you'll achieve: Connect Entra ID, Okta, Google Workspace, or any SCIM 2.0 provider to auto-sync staff into SchoolRota

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

scim.configure. Tenant owner only

SCIM is on for new trusts (more than one school) and schools with 100 or more seats. Smaller single schools upload a staff list during setup. Platform operators can still turn SCIM on as an exception.

One endpoint for all providers

SchoolRota exposes a single standard SCIM 2.0 API: You do not configure a different integration per vendor: every IdP uses the same tenant URL and bearer token.

Setting	Value
SCIM base URL	https://{your-portal-host}/api/scim/v2
Authentication	Bearer token (generated in Admin)
Provisioned resource	Users (login + staff person, matched when possible)

Copy the exact base URL from Admin → People → School sign-in (IT) → SCIM provisioning: it reflects your environment.

Before you begin

1. Sign in as tenant owner.
2. Open Admin → People → School sign-in (IT) → SCIM provisioning.
3. Enter a token label (e.g. Entra provisioning) and select Generate bearer token.
4. Copy the token immediately: it is shown once only.
5. Paste the URL and token into your identity provider (steps below vary by vendor).

Provisioned users and sign-in

SCIM creates user accounts and links them to the staff directory:

1. Match existing people by IdP external id, then email
2. Otherwise create a new staff person

That keeps My schedule, duties, and teaching imports on the same person record when staff were imported before SCIM.

For sign-in:

• Enable SSO setup so staff use Sign in with Microsoft/Google/Okta
• Or send a manual Admin → Invite with a temporary password

Groups and roles

SCIM Groups are supported at /Groups. When your IdP syncs group membership:

• Group display names containing Admin, Duty Lead, Office, or Viewer auto-map to roles
• Or set explicit role mapping in your IdP custom schema if supported
• Member roles update when group membership changes

Supported group operations: create, replace, patch members, deactivate.

Supported SCIM operations

Operation	Supported
Create user (POST /Users)	✓
Update user (PUT / PATCH /Users/{id})	✓
Deactivate user (active: false or DELETE)	✓
List / filter users (GET /Users?filter=…)	✓
Groups (GET/POST /Groups, member sync)	✓
Group → role mapping	✓ (via group name or mappedRole)
Bulk	✗

Filters supported: userName eq "…", externalId eq "…", id eq "…".

Default SchoolRota role for new users: staff: If your IdP sends a roles value matching admin, duty_lead, office, staff, or viewer, that role is applied.

Microsoft Entra ID (Azure AD)

Full Entra pilot runbook

See Microsoft Entra ID pilot runbook for the complete end-to-end checklist.

1. Enterprise applications → your SchoolRota app (or create one).

2. Open Provisioning → Get started.

3. Provisioning mode: Automatic.

4. Admin credentials:

   • Tenant URL: your SchoolRota SCIM base URL (ends with /api/scim/v2)
   • Secret Token: bearer token from Admin

5. Test connection → save.

6. Under Mappings, ensure Provision Azure Active Directory Users is enabled.

7. Attribute mapping (defaults usually work):

   Entra attribute	SCIM / SchoolRota
   userPrincipalName	userName
   mail	emails[type eq "work"].value
   givenName / surname	name.givenName / name.familyName
   accountEnabled	active
   objectId	externalId

8. Scope: Sync only assigned users and groups (recommended).

9. Turn provisioning On.

Okta

Full Okta pilot runbook

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

1. Applications → SchoolRota (SCIM 2.0 app or custom).

2. General → App Settings → Edit → enable SCIM provisioning.

3. SCIM connector:

   • SCIM base URL: SchoolRota SCIM base URL
   • Unique identifier: userName
   • Authentication: HTTP Header → Authorization: Bearer {token}

4. Supported provisioning actions: Create, Update, Deactivate (match SchoolRota capabilities).

5. To App attribute mappings: minimum:

   Okta	SCIM
   userName	userName
   firstName / lastName	name.givenName / name.familyName
   email	emails[primary eq true].value
   active	active
   externalId	externalId

6. Assign users/groups → Provision Now or wait for sync interval.

Google Workspace

Full Google pilot runbook

See Google Workspace pilot runbook for SSO-first setup and SCIM options.

Google uses SCIM for auto-provisioning when configured with a compatible IdP bridge or third-party provisioning tool. For direct Google → SchoolRota:

1. Use Google Cloud Identity / Workspace provisioning with a custom SCIM app (or partner connector).
2. Set Endpoint URL to the SchoolRota SCIM base URL.
3. Set Bearer token authentication with your Admin token.
4. Map:
   • Primary email → userName
   • Given / family name → name
   • Suspended → active (inverted: active = not suspended)

TIP

Many schools run Google as the directory but provision via Entra or Okta as the SCIM source. In that case, configure SCIM on the system that owns the roster of record.

Group naming for role mapping

Provision groups from your IdP using the SchoolRota-{Role} prefix for predictable role mapping:

IdP group name	SchoolRota role
SchoolRota-Admin	admin
SchoolRota-DutyLead	duty_lead
SchoolRota-Office	office
SchoolRota-Viewer	viewer

Local (built-in) groups in Admin work without SCIM. SCIM groups never appear in local group editors and vice versa.

Assigning staff to schools

SCIM can put someone on a school when it can resolve a short code (the code in the school URL, such as primary, not the display name). Codes come from either:

1. Attributes in Admin → Access → SCIM attribute mapping:
   • siteCode: a single code (the Entra preset maps enterprise costCenter)
   • siteCodes: an array or comma-separated list
2. Groups named SchoolRota-{siteCode}-Staff (for example SchoolRota-primary-Staff). These are separate from role groups such as SchoolRota-Admin.

If neither yields a matching active school, the person stays in the org directory with no school. Attach them in Staff like anyone else.

Leaving a group or clearing the mapped attribute takes them off only the schools SCIM assigned. Memberships added in the app (Staff editor, Add from another school, or import) stay. SCIM never converts an app-added membership into a SCIM one, so a later group match cannot steal it and then drop it when they leave the group.

A partial user update that does not include the mapped school attribute keeps the last codes SCIM stored. Sending the attribute as blank means the IdP cleared it.

Tenant attribute mapping

In Admin → Access → SCIM attribute mapping, map IdP attributes to staff directory fields (jobTitle, department, location, employeeNumber) and optional school codes (siteCode, siteCodes). Use Entra or Okta presets, then dry-run a sample SCIM user JSON before saving. Default mapping preserves title → job title and enterprise department → department. Dry-run also shows the school codes that payload would resolve.

Token hygiene

• Generate separate tokens per environment (pilot vs production) or per IdP if needed.
• Revoke tokens immediately when rotating or decommissioning an IdP connection.
• Token creation and revocation appear in the audit log.

Troubleshooting

Problem	What to try
401 Unauthorized	Token revoked, wrong token, or typo in Authorization: Bearer … header
403 SCIM not enabled	Generate a token in Admin (auto-enables SCIM) or contact platform operator
409 User already exists	Email already invited manually: deactivate duplicate or link in Admin
User created but cannot sign in	Enable SSO or send manual invite
Groups not syncing	Enable group provisioning in IdP; map to /Groups

Related

• IdP pilot runbooks. Entra, Okta, Google end-to-end checklists
• Admin users
• SSO setup
• Microsoft profile photos (after staff have portal access)
• Roles and permissions
• Troubleshooting