Okta — 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: Okta syncs staff into SchoolRota (SCIM), staff sign in with Okta (OIDC), and groups drive roles

Single end-to-end checklist

This page covers the full Okta pilot. Generic API details are in SCIM provisioning and SSO setup.

Prerequisites

Requirement	Notes
SchoolRota tenant owner account	Break-glass admin
Okta role	Super Admin or app admin for your org
Pilot cohort	3–10 users in dedicated Okta groups
Production URL	Live portal host

Okta can use one application with both OIDC sign-in and SCIM provisioning, or two apps if you prefer separation. This runbook uses one app (SchoolRota) for simplicity.

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	https://{host}/t/{subdomain}/login

---

Part 1 — Create the Okta application

1.1 OIDC app integration

1. Applications → Create App Integration
2. Sign-in method: OIDC — OpenID Connect
3. Application type: Web Application
4. Name: SchoolRota
5. Sign-in redirect URIs: https://{host}/api/auth/oidc/callback
6. Sign-out redirect URIs: optional (portal login URL is fine)
7. Controlled access: allow access to pilot groups only (recommended for pilot)
8. Save and note Client ID and Client secret

1.2 Issuer URL

Use your Okta authorization server:

Setup	Issuer URL
Default custom authorization server	https://{yourOktaDomain}/oauth2/default
Org authorization server	https://{yourOktaDomain}

Paste this into SchoolRota Admin later.

---

Part 2 — SCIM provisioning

2.1 Enable SCIM

1. Open the SchoolRota app → General tab
2. App Settings → Edit → enable SCIM provisioning
3. Save

2.2 SCIM connection

1. Provisioning tab → Integration
2. SCIM connector settings:
   • SCIM base URL: SchoolRota SCIM base URL
   • Unique identifier field for users: userName
   • Supported provisioning actions: Create Users, Update User Attributes, Deactivate Users
   • Authentication mode: HTTP Header
   • Authorization: Bearer {your SCIM token}
3. Test Connector → save

2.3 Attribute mappings (To App)

Under Provisioning → To App, configure at minimum:

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

2.4 Group push (roles)

1. Provisioning → enable Push Groups (if available on your Okta edition)
2. Create Okta groups with role-friendly names (see Part 4):
   • SchoolRota Admin
   • SchoolRota Duty Lead
   • SchoolRota Office
   • SchoolRota Staff
3. Push each group to SchoolRota and assign pilot users

If group push is unavailable, assign roles via the SSO group map only (Part 3).

2.5 Assign users and run sync

1. Assignments → assign pilot users or groups
2. Provisioning → Run provisioning (or wait for the next cycle)
3. Confirm users appear in SchoolRota Admin

---

Part 3 — SSO (OIDC) in SchoolRota

Admin → Single sign-on (OIDC):

Field	Value
Issuer URL	Your Okta issuer (see §1.2)
Client ID	From the SchoolRota Okta app
Client secret	From the SchoolRota Okta app
Group → role map	JSON (see Part 4)
Active	Check when ready

Save. Login page shows Sign in with Okta.

Groups in the ID token

Ensure Okta sends group membership to SchoolRota:

1. Security → API → your authorization server → Claims
2. Add or verify a groups claim included in the ID token
3. Filter to groups assigned to the SchoolRota app if needed

SchoolRota reads groups, roles, or Microsoft-style group claims from the token/userinfo.

---

Part 4 — Groups and roles

SCIM group names (auto-mapping)

When groups are pushed via SCIM, SchoolRota infers roles from display name:

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

SSO group → role map

Admin JSON (keys must match Okta group names):

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

The higher role from SCIM groups and SSO claims wins. tenant_owner is never downgraded.

---

Part 5 — Pilot test checklist

Provisioning

• [ ] SCIM connector test succeeds
• [ ] Pilot users appear in SchoolRota Admin
• [ ] Audit log: SCIM user provisioned
• [ ] Group push updates membership and roles

Sign-in

• [ ] Sign in with Okta on login page
• [ ] Pilot user completes Okta login
• [ ] Correct role in portal
• [ ] Audit log: auth.login_sso

Lifecycle

• [ ] Deactivate in Okta → user inactive in SchoolRota
• [ ] Remove from admin group → role downgrades
• [ ] Tenant owner email/password still works (break-glass)

---

Okta-specific troubleshooting

Symptom	Likely cause	Fix
Connector test failed	Bad URL or bearer token	Verify SCIM base URL and Authorization: Bearer … header
Users not provisioning	App assignment	Assign users/groups to SchoolRota app
SSO button missing	Inactive OIDC config	Activate in Admin
Wrong role after login	No groups claim	Add groups to ID token claims
Issuer mismatch	Wrong auth server	Issuer must match token issuer exactly
409 duplicate user	Prior manual invite	Deactivate duplicate in Admin

---

Go-live notes

• Use separate SCIM tokens for pilot vs production
• Restrict app assignment before widening to all staff
• Document group → role mapping for handover to school IT

Related

• SCIM provisioning
• SSO setup
• Microsoft Entra pilot runbook
• Google Workspace pilot runbook
• Troubleshooting