Just-in-Time Provisioning & Role Mapping From IdP Groups
Not every enterprise customer turns on SCIM on day one. Many connect SAML or OIDC first and expect that a new employee can simply click the app tile in Okta or Entra ID and land inside the right workspace with the right
Not every enterprise customer turns on SCIM on day one. Many connect SAML or OIDC first and expect that a new employee can simply click the app tile in Okta or Entra ID and land inside the right workspace with the right permissions. That is just-in-time (JIT) provisioning: the account is created, or updated, at the moment of login, using the claims in the assertion or ID token.
JIT is convenient and easy to get wrong. The two classic failures are account takeover, where an IdP assertion gets linked to someone else's existing account, and privilege creep, where a group name in a token quietly makes someone an admin. This post covers how I build JIT and group-to-role mapping so neither happens.
I wrote this with help from AI tools and checked the claim behaviour against the Okta, Microsoft Entra ID and OpenID Connect Core documentation. I am a Principal Software Engineer in Karachi with 9+ years building Laravel, Node and .NET SaaS backends, and everything here is defensive design for your own application.
๐ Series Navigation โ Enterprise SSO & Identity for B2B SaaS
- Part 1: Enterprise SSO Readiness: SAML vs OIDC for B2B SaaS
- Part 2: Validating SAML Responses: Signatures, Audience & Clock Skew
- Part 3: SCIM Provisioning & Deprovisioning That Actually Removes Access
- Part 4: Multi-Tenant Login Routing: Domain Discovery & Enforced SSO
- Part 5 (This Post): Just-in-Time Provisioning & Role Mapping From IdP Groups
- Part 6: Break-Glass Accounts & SSO Audit Logs
Related earlier posts: OAuth 2.1 & OIDC ID Tokens: PKCE Forensics ยท Session Lifecycle Hardening: Rotation, Timeouts & Server-Side Revocation
What is JIT provisioning and how do I do it safely?
Direct answer: JIT provisioning creates or updates a user from the claims of a validated SAML assertion or OIDC ID token at login. Do it safely by keying identities on the connection plus the IdP's stable subject ID (not email), only linking to existing accounts inside the same verified domain, and mapping IdP groups to roles through an explicit per-tenant table that never grants admin automatically.
JIT vs SCIM vs manual invites
| Approach | When accounts appear | Deprovisioning | Role updates | Best for |
|---|---|---|---|---|
| Manual invites | When an admin invites | Manual | Manual | Small teams, guests |
| JIT on login | First SSO login | Only at next login, or never | At each login | Customers without SCIM yet |
| SCIM (Part 3) | When IdP assigns the app | Immediate push | Pushed on change | Mature enterprise customers |
| JIT + SCIM | SCIM creates, JIT refreshes | SCIM | Both | The setup I recommend |
The key weakness of JIT alone is in the third column: if someone leaves the company, JIT never hears about it. Short sessions and a "not seen in N days" cleanup job help, but SCIM is the real fix.
Step 1: decide which claims you trust
Only use claims from a response you have fully validated (signature, issuer, audience, time, as in Part 2). Then pick a stable identifier. Email changes when people marry, rebrand or switch domains, so it is a poor primary key.
| Claim | SAML source | OIDC source | Use it for |
|---|---|---|---|
| Stable user ID |
NameID (persistent format) or an immutable attribute like Entra objectidentifier
|
sub (with iss) |
Primary identity key |
email attribute |
email + email_verified
|
Display, routing, linking (with checks) | |
| Name |
givenName / surname
|
given_name / family_name
|
Display only |
| Groups |
groups or custom attribute |
groups claim (may be IDs, not names) |
Role mapping |
When debugging a tenant's setup, I decode a test ID token with a JWT decoder to see exactly which claims arrive. Never paste a live production token from someone else's account into any online tool; use a test user.
Step 2: key identities on connection + subject
CREATE TABLE sso_identities (
id BIGSERIAL PRIMARY KEY,
connection_id BIGINT NOT NULL REFERENCES sso_connections(id),
subject TEXT NOT NULL, -- NameID or iss+sub
user_id BIGINT NOT NULL REFERENCES users(id),
last_login_at TIMESTAMPTZ,
UNIQUE (connection_id, subject)
);
Scoping by connection_id matters. Two different tenants' IdPs can both issue a subject called 12345. If you key on subject alone, one tenant can log in as another tenant's user.
Step 3: link existing accounts without takeover
The dangerous moment is the first SSO login for a user who already has a password account with the same email. Auto-linking by email is how takeovers happen: a malicious or misconfigured IdP asserts [email protected] and gets that account.
public function resolveUser(SsoConnection $conn, array $claims): User
{
$identity = SsoIdentity::where('connection_id', $conn->id)
->where('subject', $claims['subject'])->first();
if ($identity) {
return $identity->user; // known identity: normal path
}
$email = strtolower($claims['email'] ?? '');
$domain = emailDomain($email);
if (! $domain || ! $conn->tenant->ownsVerifiedDomain($domain)) {
throw new SsoLinkRefused('Email domain is not verified for this connection');
}
$existing = User::where('email', $email)->first();
if ($existing && ! $existing->belongsToTenant($conn->tenant_id)) {
throw new SsoLinkRefused('Account exists outside this tenant; needs explicit link');
}
$user = $existing ?? User::create(['email' => $email, 'name' => $claims['name'] ?? $email]);
$conn->tenant->addMember($user);
SsoIdentity::create(['connection_id' => $conn->id, 'subject' => $claims['subject'], 'user_id' => $user->id]);
return $user;
}
The rules: link by email only when the domain is verified for that tenant (Part 4), and only for accounts already inside that tenant. Anything else needs an explicit, logged-in linking step by the user.
Step 4: map groups to roles with an explicit table
Do not do if (in_array('Admins', $groups)) $role = 'admin';. Group names are free text in the customer's IdP and anyone with IdP admin rights can create a group called "Admins". Store a mapping that the tenant's app admin configures:
{
"tenant_id": 482,
"connection_id": 77,
"default_role": "member",
"mappings": [
{ "idp_group": "8f2c1a7e-3b0d-4c55-9e1a-2d6f0b9c4a11", "role": "editor" },
{ "idp_group": "eng-viewers", "role": "viewer" }
],
"never_auto_assign": ["owner", "billing_admin"]
}
I keep these configs readable and validated, and check them in a JSON formatter before saving when a customer sends one by email. A few details that save support tickets:
- Entra ID sends group object IDs, not names, by default. Map IDs, and show the friendly name next to each in your admin UI.
-
Group overage: when a user is in too many groups, Entra omits the
groupsclaim and sends a pointer to Microsoft Graph instead. Treat "no groups claim" as "unknown", not "no groups", and keep the current role rather than downgrading. - Pick a precedence rule when a user matches several mappings. I use the highest role in a fixed order.
- Owner and billing roles are never auto-assigned. A human in the app grants them.
Step 5: update on every login, carefully
JIT runs again on every login, which is useful for keeping names and roles fresh. Decide which fields the IdP owns:
| Field | IdP-owned? | On each login |
|---|---|---|
| Name, email | Yes | Overwrite |
| Role from mapped groups | Yes | Recompute; log changes |
| Manually granted owner role | No | Never touch |
| App-specific preferences | No | Never touch |
Every role change from JIT goes into the audit log with the old role, new role, groups seen and connection ID. Part 6 covers that log.
Diagnostic checklist
- [ ] Identities are keyed on connection ID plus a stable subject, never email alone
- [ ] Claims are read only after full signature, issuer, audience and time validation
- [ ] Auto-linking by email is limited to verified domains and accounts already in the tenant
- [ ] Group-to-role mapping is an explicit per-tenant table, not hardcoded names
- [ ] Owner and billing roles are never granted automatically
- [ ] Missing groups claims keep the current role instead of downgrading
- [ ] Role changes from JIT are audit-logged
- [ ] A cleanup job or SCIM handles users who stop logging in
FAQ
Is JIT provisioning secure enough without SCIM?
For creating accounts, yes, if you follow the rules above. For removing access it is weak, because a departed user is never reported. Pair it with short sessions and SCIM when the customer can.
Should I use email as the user ID?
No. Use the IdP's persistent subject scoped to the connection. Keep email as an attribute you update.
What if the customer's IdP sends group names instead of IDs?
That works, but names can be renamed or duplicated. Store whatever is stable for that IdP, and let the tenant admin confirm the mapping.
Can a user be in several tenants with JIT?
Yes. Each tenant's connection creates its own identity row pointing to the same user, and membership is added per tenant.
Should JIT downgrade roles?
Yes, when the groups claim is present and no longer matches. Not when the claim is missing.
How do I test role mapping safely?
Create test users in a staging IdP tenant, assign them to each group, log in, and compare the resulting role against the mapping table.
Next in this series, Part 6 covers break-glass accounts and the SSO audit logs that make incidents investigable.
Follow & Connect
- Website: PixelValut Tools
- Watch on YouTube: Resume Boost AI ยท PixelValut ยท Daily AI News By Ali
- TikTok: PixelValut (@pixelvalut007)
- GitHub: Muhammad Ali Mughal (@ali111887)
- LinkedIn: Muhammad Ali Mughal
Originally published by Dev.to Security. Aggregated on AIWithGhost for educational purposes โ full credit and traffic to the original publisher.