SCIM provisioning

Who this is for: Tenant owner
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

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 → SCIM provisioning — it reflects your environment.

Before you begin

1. Sign in as tenant owner.
2. Open Admin → 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.

Tenant attribute mapping

In Admin → Access → SCIM attribute mapping, schools can map custom IdP attributes to staff directory fields (jobTitle, department, location, employeeNumber). 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.

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
• Roles and permissions
• Troubleshooting