DEV Community

Cover image for Just-in-Time Provisioning & Role Mapping From IdP Groups
Muhammad Ali Mughal
Muhammad Ali Mughal

Posted on

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 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

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.

Mail sorting room with pigeonhole shelves sorted by color tags, AI-generated

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 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)
);
Enter fullscreen mode Exit fullscreen mode

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 ceo@yourcompany.com 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;
}
Enter fullscreen mode Exit fullscreen mode

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"]
}
Enter fullscreen mode Exit fullscreen mode

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 groups claim 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

Top comments (0)