How do I map SSO users to tenants and roles?

To map SSO users to tenants and roles, you typically need to do two things:

1. Identify the user uniquely from the SSO assertion/token
2. Translate claims/groups/attributes into your app’s tenant and role model

Common approach

1) Use a stable user identifier

From your IdP (Okta, Azure AD, Auth0, etc.), use a unique claim such as:

• sub
• oid (Azure AD)
• email only if you trust it to be immutable
• nameid / SAML NameID

Store that as the SSO identity link to your internal user record.

---

2) Map SSO attributes to tenant membership

You usually get tenant info from one of these:

• Group membership
  Example: groups = ["tenant-a-admins", "tenant-b-viewers"]
• Custom claims Example: tenant_id = "tenant-a"
• Email domain rules Example: @acme.com → tenant acme
• IdP app assignment Different SSO app per tenant

Best practice is to avoid relying on email domain alone if you can.

---

3) Map claims/groups to roles

Create a mapping table in your app, for example:

SSO Group/Claim	Tenant	App Role
tenant-a-admins	tenant-a	admin
tenant-a-readers	tenant-a	viewer
tenant-b-editors	tenant-b	editor

Then on login:

• Read the SSO claims
• Find matching tenant(s)
• Assign the corresponding role(s)
• If no match, deny access or create a default limited role

---

Recommended data model

A simple model:

• users
  • id
  • sso_subject
  • email
• tenants
  • id
  • name
• roles
  • id
  • name
• user_tenant_roles
  • user_id
  • tenant_id
  • role_id

This lets one user belong to multiple tenants with different roles.

---

Example logic

If using group claims

1. User logs in via SSO
2. App receives token with:

   {
     "sub": "abc123",
     "email": "jane@company.com",
     "groups": ["tenant-a-admins", "tenant-b-viewers"]
   }
   

3. App checks group-to-tenant-role mapping:
   • tenant-a-admins → tenant A / admin
   • tenant-b-viewers → tenant B / viewer
4. App creates/updates user access records

---

Important best practices

• Do mapping server-side, not in the client
• Don’t trust raw claims blindly unless they come from your verified IdP
• Normalize roles to your internal role names
• Support multiple tenant memberships
• Have a fallback policy for unmapped users
• Audit changes to mappings and assignments

---

If you want a more secure/scalable setup

Use one of these patterns:

• Centralized mapping table in your app
• SCIM provisioning to sync users/groups from IdP
• Just-in-time provisioning on first login
• Role-based access via IdP groups with your app translating groups → internal permissions

---

If you want, I can also show:

1. a SAML example,
2. an OIDC/JWT example, or
3. a database schema + login flow for tenant/role mapping.