Microsoft Entra ID — pilot runbook

Who this is for: School IT admin or SchoolRota tenant owner
Time: about 2–3 hours for a small pilot group
What you'll achieve: Entra syncs staff into SchoolRota (SCIM), staff sign in with Microsoft (OIDC), and security groups drive roles

Start here for school pilots

This is the single end-to-end checklist for Entra. Generic SCIM/SSO reference material lives in SCIM provisioning and SSO setup.

Prerequisites

Requirement	Notes
SchoolRota tenant owner account	Keeps working as break-glass admin
Entra role	Global Administrator or Application Administrator
Pilot cohort	3–10 users in dedicated Entra security groups
Production URL	Your live portal host, e.g. https://demo.yourschool.schoolrota.com

You will create two Entra apps:

1. SchoolRota SCIM — provisions users and groups into SchoolRota
2. SchoolRota SSO — OIDC sign-in on the login page

Using separate apps keeps provisioning credentials isolated from the public OIDC client.

Step 0 — Collect SchoolRota values

Sign in as tenant owner → Admin.

Setting	Where to copy	Example
SCIM base URL	Admin → SCIM provisioning	https://{host}/api/scim/v2
SCIM bearer token	Generate in Admin (shown once)	dlscim_…
OIDC redirect URI	Admin → Single sign-on card	https://{host}/api/auth/oidc/callback
Portal login URL	Browser address bar	https://{host}/t/{subdomain}/login

Generate the SCIM token before configuring Entra provisioning. Label it e.g. Entra pilot.

---

Part 1 — SCIM provisioning (users + groups)

1.1 Create the enterprise application

1. Microsoft Entra admin center → Identity → Applications → Enterprise applications
2. New application → Create your own application
3. Name: SchoolRota SCIM
4. Select Integrate any other application you don't find in the gallery (Non-gallery)
5. Create the app

1.2 Configure automatic provisioning

1. Open SchoolRota SCIM → Provisioning → Get started
2. Provisioning mode: Automatic
3. Admin credentials:
   • Tenant URL: your SchoolRota SCIM base URL (must end with /api/scim/v2)
   • Secret Token: the bearer token from Admin
4. Test connection → expect success → Save

1.3 User attribute mapping

Under Mappings, open Provision Azure Active Directory Users and confirm:

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

Save if you changed anything.

1.4 Group attribute mapping

1. Mappings → Provision Azure Active Directory Groups → ensure it is Enabled
2. Default mappings are usually sufficient (displayName, objectId → externalId)
3. Group display names drive SchoolRota roles when they contain keywords (see Part 3)

1.5 Assignment and scope

1. Users and groups → assign pilot security groups (and/or individual pilot users)
2. Provisioning → Provisioning Status → set Provisioning to On
3. Settings → Scope: Sync only assigned users and groups (recommended)

1.6 Verify SCIM sync

1. Wait for the first cycle (or Provision on demand for one user)
2. In SchoolRota Admin, confirm pilot users appear in the user list
3. Check Audit log for SCIM user provisioned events

---

Part 2 — SSO (OIDC)

2.1 Register the OIDC application

1. App registrations → New registration
2. Name: SchoolRota SSO
3. Supported account types: single tenant (typical for one school)
4. Redirect URI: Web → https://{host}/api/auth/oidc/callback
5. Register and note:
   • Application (client) ID
   • Directory (tenant) ID

2.2 Client secret

1. Certificates & secrets → New client secret
2. Copy the Value immediately (not the Secret ID)

2.3 Token configuration (groups claim)

For role mapping at sign-in, Entra must emit group membership:

1. Token configuration → Add groups claim
2. Choose Security groups (or groups assigned to the app)
3. For large directories, use Groups assigned to the application and assign role groups to this app

Group overage

If a user belongs to more than ~200 groups, Entra may omit the groups claim. Assign only the SchoolRota role groups to the SSO app, or configure Entra group overage handling for production.

2.4 Save OIDC config in SchoolRota

Admin → Single sign-on (OIDC):

Field	Value
Issuer URL	https://login.microsoftonline.com/{directory-tenant-id}/v2.0
Client ID	Application (client) ID from step 2.1
Client secret	Secret value from step 2.2
Group → role map	JSON (see Part 3)
Active	Check when ready

Select Save OIDC config.

The login page shows Sign in with Microsoft when the config is active.

---

Part 3 — Security groups and roles

SchoolRota applies roles from two mechanisms (whichever yields the higher role wins):

A. SCIM group sync

When Entra syncs a group, SchoolRota maps roles from the group display name:

Group name contains	SchoolRota role
Admin	admin
Duty + Lead	duty_lead
Office	office
Viewer	viewer

Recommended pilot group names:

• SchoolRota Admin
• SchoolRota Duty Lead
• SchoolRota Office
• SchoolRota Staff

Assign users to these groups in Entra. Enable group provisioning on the SCIM app.

B. SSO group → role map

In Admin, set JSON matching your Entra group display names:

{
  "SchoolRota Admin": "admin",
  "SchoolRota Duty Lead": "duty_lead",
  "SchoolRota Office": "office",
  "SchoolRota Staff": "staff"
}

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

Linking SCIM and SSO

A user provisioned via SCIM can sign in with SSO when email matches. SchoolRota links the OIDC sub claim to the existing account on first login.

---

Part 4 — Pilot test checklist

Run through this with one user from each role group.

Provisioning

• [ ] SCIM Test connection succeeds in Entra
• [ ] Pilot user appears in SchoolRota Admin user list
• [ ] Staff profile created (name matches Entra)
• [ ] Audit log shows SCIM user provisioned
• [ ] Group membership syncs (user role updates after group change)

Sign-in

• [ ] Sign in with Microsoft visible on login page
• [ ] Pilot user completes Microsoft login without error
• [ ] User lands in the portal (not login loop)
• [ ] Role matches expected group (Admin user sees admin features)
• [ ] Audit log shows auth.login_sso

Lifecycle

• [ ] Disable user in Entra → user deactivated in SchoolRota after sync
• [ ] Re-enable user → can sign in again
• [ ] Remove user from admin group → role downgrades on next sync/login

Break-glass

• [ ] Tenant owner can still sign in with email/password if SSO fails

---

Entra-specific troubleshooting

Symptom	Likely cause	Fix
Test connection failed	Wrong URL or token	URL must be exact SCIM base; regenerate token if lost
401 on provisioning	Revoked or mistyped token	New token in Admin; update Entra secret
User synced but no SSO button	OIDC config inactive	Check Active in Admin; tenant needs sso feature
SSO works but wrong role	Groups claim missing	Add groups claim; assign role groups to SSO app
sso_state_mismatch	Cookie blocked	Allow cookies for portal; retry in private window
Token exchange failed	Secret or redirect mismatch	Re-check client secret and redirect URI (exact match)
409 User already exists	Manual invite same email	Remove duplicate or deactivate manual account
Groups not syncing	Group provisioning off	Enable Provision Azure Active Directory Groups

See also Troubleshooting.

---

Go-live notes

• Rotate SCIM tokens on a schedule; revoke old tokens in Admin
• Keep tenant owner as break-glass (not solely dependent on Entra)
• Document which Entra groups map to which SchoolRota roles for the school
• Expand assignment from pilot groups to full staff when satisfied

Related

• SCIM provisioning
• SSO setup
• Outlook calendar sync — separate Entra app with Calendars.ReadWrite (application) for calendar write-back
• Signing in
• Roles and permissions
• Okta pilot runbook
• Google Workspace pilot runbook