Convert your tenant into a CIAM (Customer Identity Access Management)

Convert your tenant into a CIAM (Customer Identity Access Management)

Organizations & OIDC Token Mapping



Notes
Objective :
Configure your Multi-Pass tenant to support Customer Identity and Access Management (CIAM), enabling secure registration, login, and profile management for external users (customers or partners).


Step 1 - Create a dedicated Tenant

  1. Login to your dashboard.
  2. Click on "New tenant"
  3. Complete the fields
    1. Company Name
    2. Tenant ID
  4. Click on advanced console
  5. on the left side, click on "realm settings" 
  6. Enable "Organizations"

  1. Click Save
  2. A new section called "Organization" will appear on the left side. 

Enable Self-Registration (Optional)

  1. In Realm Settings, change tab to "Login"
  2. Enable the following parameters :
    • User registration
    • Email as username (recommended)
    • Verify email (SMTP setup required)



Step 2 - Manage Organizations

  1. Go to Organizations, click on Create Organization

  1. and set : 
    • Name 
    • Alias (unique URL-friendly identifier)
    • Domains (match users via email)
    • Redirect URL and optional attributes
    • Description
  2. Customize onboarding, domain restrictions, IDPs, invitations per organization.
  3. You can disable or delete organizations to prevent login within their context.

Step 3 - Assign Roles to Users or Groups

Assign to Users

  1. Go to Users, on the left side

  1. Select the users
  2. open the tab "Role Mappings"

  1. Click Assign Role,

  1. select realm or client roles, and click Assign.

Assign to Groups

  1. Move to the groupe section on the left side
  2. select the appropriate group.

  1. Under Role Mappings, assign roles. Members inherit them.


Restrict Roles in Tokens

  • Go to clients
  • Select the application you need 

  • Go to Client scope tab and select the line of your client,

  • Go to the tab "Scope" and make sure Full scope allowed is enabled


Step 4 - Include Organization Info in OIDC Token

  1. Create a Client Scope (e.g. organization:*).
  2. Add a mapper of type Organization Membership.
  3. Configure it to include organization alias and/or ID.
  4. Set the scope as Default or assign as Optional for your client.
{
  "organization": [
    {"alias": "org1", "name": "Org One"}
  ],
  "organizationId": "a56bea03-5904-470a-b21c-92b7f1069d44"
}

Step 5 - Include Roles and Groups in Tokens

"realm_access": {
  "roles": ["admin", "user"]
},
"resource_access": {
  "my-client-id": {
    "roles": ["app-role"]
  }
},
"groups": ["/group1/subgroup", "admins"]

Summary Table

StepsDescription
Enable OrganizationsRealm Settings → General → Toggle ON
Manage OrgsCreate orgs with alias, domain, redirect
Assign RolesVia user or group Role Mappings
Org Claim in TokenCreate organization:* scope and mapper
Limit Roles in TokenSet Full Scope Allowed = OFF; define explicitly
Include GroupsGroup Membership mapper

Step 6 - Sample OIDC Authentication Flow

  1. User initiates login to your app
  2. OIDC request includes: scope=openid profile organization:*
  3. Token includes:
    • organization & organizationId claims
    • realm_access, resource_access roles
    • groups (if mapped)
  4. Your app enforces authorization using these claims
  5. Important endpoints, you need to take care : 

Notes
  1. Use organization:* scope to fetch all orgs if user has more than one.
  2. Composite roles automatically include their children roles in tokens.
  3. Disable Full Scope and map scopes explicitly to limit exposure.
If you need JSON config samples, client scope exports, or tailored examples for your stack (Node.js, Spring, etc.), just ask!