SSO / OIDC: Differentiated JIT Provisioning (Staff vs. Portal), Profile Attribute Sync & Role Fallbacks

[srinivasansanthosh]

Hi Ed,

Following up on our SSO/OIDC setup, we ran into a few common enterprise onboarding requirements when using a single corporate Identity Provider (e.g. Microsoft Entra ID / Okta) across an organization:

1. Role Separation on JIT Provisioning: Auto-creating regular employees as portal customers upon their first login without unintentionally turning everyone into an IT analyst (or conversely, enabling automated analyst provisioning with defined default module permissions).
2. Profile Attribute Sync & Field Locking: Synchronizing name, job title, department, office/location, phone, and mobile from IdP claims/UserInfo on login, while locking those fields from manual editing in FreeITSM when the IdP is configured as the authoritative directory of record.
3. Non-Analyst Fallback Routing: Gracefully handling staff login attempts by users who only possess a self-service portal account (offering a branded redirect/prompt rather than a generic authentication error).
4. Seamless Dual-Role Navigation: Allowing team members who use the Self-Service Portal to quickly jump back to the Analyst Console from their user account menu.

I have implemented and tested this on my fork, keeping strictly to FreeITSM's database schema rules, translation keys, and house style. The branch is organized into four atomic, independent commits so you can review, cherry-pick individual parts, or ignore anything that doesn't align with your roadmap.

---

What's in the branch

1. Differentiated JIT Provisioning & Role Separation (feat(auth))

• Independent Provisioning Toggles: Split auto-creation into Auto-create self-service users and Auto-create IT analysts per provider.
• Default Analyst Permissions: Choose default module capabilities assigned to newly created analysts.
• Non-Analyst Fallback Handling: Configurable per provider when a portal user logs in on the analyst screen:
  • Warn & confirm: Displays a clean branded screen offering to continue to the Self-Service Portal or sign out.
  • Automatically switch: Seamlessly forwards them to the portal.
  • Block: Denies access.

2. Profile Attribute Sync & Directory Authority (feat(auth))

• Three Sync Modes: Configurable per provider (Always (Every sign-in), Initial only (First sign-in), Never).
• UserInfo Claims Merge: Falls back to fetching claims from the OIDC userinfo_endpoint when claims like department, job_title/title, or phone_number are not embedded directly in the ID token.
• Managed Field Locking: When set to Always, fields (preferred_name, job_title, office, phone, mobile) are locked with a tooltip and notice in both Self-Service (My Account) and Analyst Preferences (System → Preferences → My details), preventing local drift.

3. Analyst Console Launcher in Portal Menu (feat(portal))

• When an authenticated portal user has an active analyst record, the portal avatar menu displays an Analyst Console shortcut that opens the console in a new tab.

4. Help Documentation & IdP Claim Guidance (docs(sso))

• Added Section 4l to system/help/sso.php and updated portal-profile.php with step-by-step guidance for configuring optional claims in Microsoft Entra ID (Azure AD), Okta, and Keycloak, as well as clarifying Scopes vs. Claims.

---

Compatibility & Baseline

• Base Version: Rebased cleanly on top of Release 2.7.1 (801019c9).

---

Screenshots

Provider modal showing Differentiated JIT toggles, Default Modules, and Fallback options

SSO Provider table with "Profile sync" column pill and sync mode selector

Analyst Preferences / Portal My Account with locked fields & notice

Self-service avatar menu showing the Analyst Console shortcut with pop-out icon

---

Branch & Commits

I have tested this thoroughly in our environment across the key identity provider scenarios, but please do review it from your broader architectural perspective. If there are any edge cases, design adjustments, or house style tweaks you would like addressed, I would be very happy to iterate on them. Alternatively, feel free to pull the branch directly and adapt anything as you see fit.

If this looks good to you in principle, let me know and I will be glad to open a formal PR!

🔗 Branch: feat/differentiated-jit-sso

Commit breakdown:

1. 4dc92600 feat(auth): add differentiated JIT provisioning, role separation, and profile attribute sync
2. b302112d feat(portal): add analyst console launcher in user account menu
3. 90cafb1b style(auth): standardize login footer links across analyst and portal
4. 5cab6417 docs(sso): document differentiated JIT rules, profile sync modes, and claim mappings

[edmozley]

Hi Sandy @srinivasansanthosh,

Thank you - this is a really thoughtful piece of work, and it solves a problem a lot of people will have when one company sign-in is used for both staff and customers. I've read through the whole branch and I'd love to get it into FreeITSM.

Before it can go in, there are a few things to change. Most of them are about people who are upgrading - their existing settings need to keep working exactly as before until they choose to use the new options.

1. Existing "auto-create" settings need carrying over
At the moment, anyone who has "Auto-create users" switched on is getting new analysts created. With the new setup, "Auto-create IT analysts" starts switched off, so after upgrading those people would quietly stop getting new analysts (this affects LDAP too). When the new setting is added, it should copy across whatever the old one was set to.

2. Profile sync should start as "Never"
Right now it starts as "Always", which means the moment someone upgrades, every sign-in starts overwriting names, job titles and phone numbers, and people can no longer edit their own details. Starting it as "Never" means nothing changes until an admin switches it on.

3. Check who the person is before updating their details
When someone is matched by email, their details are updated before FreeITSM checks whether the account is active and whether it belongs to that sign-in provider. So a provider that gets refused a moment later has already changed the details. The update just needs moving to after those checks. While you're there, the same block of code appears four times - one shared function would be tidier.

4. Please leave out the login page restyle and the reworded text
I'd like to keep the login footer as it is. Also, changing the wording of existing text (like "Forgot password?" and the portal link) makes the translations in the other languages out of date. New text with new keys is absolutely fine - it's just changing existing wording that causes the problem. The same goes for hiding the password / MFA options for SSO users - it's a reasonable idea, but I'd rather look at it separately.

There are also a few smaller bits. I've written everything up in full on a wiki page, file by file, with the code changes and the reasons, plus a list of checks to run at the end. It's written so you can point your coding tool straight at it:

👉 SSO - JIT roles and profile sync: review notes

Don't worry about catching up with 2.8.0 - a few things have changed since 2.7.1 and there are a couple of small overlaps, but I'm happy to handle all of that myself. Just make the changes on your existing branch, and once you're done, open the PR against it as it is and I'll take care of the merge.

The "Analyst console" link in the portal menu is a lovely touch and fills a gap I'd missed.

Thanks again - really appreciate the time you've put into this, and just shout if anything above doesn't make sense.

Ed

[srinivasansanthosh]

Hi Ed,

Thank you for the thorough review notes on the wiki. Every single point made total sense, especially regarding upgrade safety and data preservation.

Regarding hiding Password Change / MFA (Fix 8): I had initially added this thinking specifically of my own single-tenant SSO deployment where end-users don't have local passwords and was wondering why you wanted it removed. However, your points about forced password resets (must_change_password), and dual-credential accounts make sense. I agree this belongs in a dedicated discussion to design a holistic solution. Please do take this idea forward.

I have addressed all 10 review items in a clean commit on top of the branch:
f8d57cf0 - fix(sso): apply review adjustments for JIT split, profile sync defaults, and i18n parity

Summary of adjustments made:

1. Upgrade Migration (db_verify.php): Added the one-time $providerAutoAnalystsColWasMissing probe to copy the existing auto_create_users setting to auto_create_analysts and default existing providers' fallback mode to block.
2. Profile Sync Defaults: Changed default profile_sync_mode to never across schemas (freeitsm.sql, db_verify_schema.php), API endpoints, and UI modal selectors.
3. Single Sync Helper (oidc_callback.php): Consolidated the inline updates into oidcSyncProfile(), invoked strictly after all access checks (active status, provider assignment, tenant boundary) pass. Requesters' preferred_name is preserved from being overwritten.
4. Protocol Scoping & Field Locking: Scoped profile locking strictly to OIDC with profile_sync_mode === 'always' (locking only the 5 synced fields) so CardDAV write-back and LDAP directory sync remain untouched.
5. UserInfo Hardening: Skipped userinfo calls when sync is never, enforced sub verification with hash_equals(), and removed CURLOPT_FOLLOWLOCATION. Added an explicit note in system/help/sso.php regarding Entra ID's UserInfo claims.
6. i18n & Login Footer: Reverted the footer restyling in auth/login.php (retaining only the cancel_sso clearing) and restored the original English keys, introducing new keys (cb_autocreate_users, cb_autocreate_users_desc) for portal requester JIT.
7. SSO UI Scoping: Profile sync dropdowns and table pills now show only for OIDC (showing Not applicable for LDAP/CardDAV).
8. Password/MFA Menu Visibility: Reverted the hunks hiding password/MFA for SSO sessions.
9. Analyst Console Shortcut: Updated the launcher link to use BASE_URL.
10. Theme Tokens: Replaced --accent-subtle in system/preferences/index.php with valid surface tokens.

---

What I tested & Environment Limitations:

Tested on my environment:

• Verified automated checks from the review notes (profile_sync_mode defaults, oidcSyncProfile references, and lang/en/ key integrity).
• Tested the core OIDC flows: JIT analyst creation vs. JIT portal creation, the non-analyst fallback modal (confirm vs block vs redirect), and attribute sync (never, initial, always) against a live OIDC provider.
• Simulation suite: Ran test harness scripts confirming authorization checks, preferred name preservation, and the one-time db_verify upgrade migration.

Limitations & Areas to verify before merging:

• My test environment is a single-company setup with a single OIDC provider.
• I do not have a live CardDAV write-back server or a multi-tenant LDAP directory sync farm set up, so I was unable to test CardDAV write-back hands-on (though the code has been strictly isolated to protocol === 'oidc').
• It would be great if you could verify the one-time db_verify.php migration backfill on an upgraded 2.7.1 database with pre-existing providers, as well as CardDAV write-back behavior.
• Please give it an end-to-end holistic product sanity check from your end

The branch is ready on my fork:
🔗 feat/differentiated-jit-sso

Thanks again!
Keep up the good work !

[edmozley]

Hi Sandy @srinivasansanthosh,

It's merged! 🎉 Your branch is in main with your commits and authorship intact, and it will ship in 2.10.0. Thank you - this is the first sizeable feature FreeITSM has had from outside, and it's a really good one.

I've written it up properly on the wiki, with the code and a plain-English explanation of each part, and you're credited at the top:

👉 SSO auto-create and profile sync - Developer Guide

How I tested it. Since you didn't have multi-tenant or CardDAV setups, I built a clean room: a copy of the merged code on a throwaway database loaded from the 2.9.0 schema (so, an upgraded install), plus a small mock OpenID Connect provider that signs real ID tokens. That meant your callback ran all of its real checks. About 70 checks passed, covering the upgrade before and after Database Verification, all three fallback modes, all three sync modes, the userinfo top-up, locking, and - the one I cared about most - that a refused sign-in writes nothing at all, including across providers.

A few things I adjusted while merging (all listed in the "What changed at merge time" section of the guide):

• userinfo (review 5a/5b): the call still ran when sync was never, and the sub check wasn't there yet. I think it just got lost in a big commit, so I added both.
• Before Database Verification: this one is FreeITSM-specific and wasn't in my review, so there was no way you could have known. An upgraded install runs the new code on the old schema until someone runs Verification, so any query that names a new column fails - and the Authentication page shows "No providers yet". Every reader of the three columns now checks first.
• Small bits: the confirm screen now expires after 10 minutes and only keeps the ID token, the dialog shows fallback and sync for OIDC only, and the help sections were tidied (one mentioned IdP-group restrictions that don't exist yet).

None of that takes anything away from the work - the design is yours: the two switches, the three fallback modes, the three sync modes, the claim mapping across Entra, Okta and Keycloak, and the confirm screen.

On hiding password / MFA for SSO users - thanks for being open to that. I'll pick it up separately, so the must_change_password and dual-credential cases get thought through properly.

No need to open a PR now - it's all in. Thanks again, and if you spot anything once 2.10.0 is out, just shout.

Ed

[srinivasansanthosh]

Hi Ed,

Thank you so much for merging the branch and for the follow-up refinements! Looking forward to continuing to contribute to FreeITSM!