Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Map IdP groups to roles in your app

Have your customer's identity provider send groups or a custom attribute, read them from the ID token in your SSO callback and set each user's role in your app.

Enterprise customers want access in your app to follow their directory: people in their “App Admins” group are admins in your app, and someone removed from the group loses that access. With Modular SSO, your app keeps its own roles. Scalekit passes along what the customer’s identity provider (IdP) says about the user, and your app turns that into a role at each login.

This page shows how to:

  1. Turn on the attribute in Scalekit: the built-in Groups attribute, or a custom one.
  2. Have your customer’s IT admin send it from their IdP.
  3. Read it from the ID token in your callback and set the user’s role.

It builds on the callback from Handle the callback and find the user.

AttributeWhat the IdP sendsUse it when
Groups (groups)A list of the user’s group names, which your app maps to rolesThe customer already manages access with groups. Most IdPs, including Okta and Microsoft Entra ID, can send groups
A custom attribute, such as app_roleOne value that names the role in your app, such as adminThe customer would rather set a role per user, or their IdP can’t send groups

Your app can read both, as the code below does.

Open User Attributes in the dashboard.

  • Groups: edit Groups and turn on its SSO mapping. It’s a built-in attribute that is off until you turn it on.
  • A custom attribute: select Add Attribute, enter an attribute name such as app_role and a display name, and save. Scalekit then reads an attribute or claim with the same name from the IdP.

Attributes you don’t add here aren’t passed on, even if the IdP sends them. Don’t name a custom attribute after a reserved name such as roles.

Ask your customer’s IT admin to add the attribute to the app they created for your SSO connection:

  • SAML: an attribute named groups, or your custom attribute’s name, such as app_role. In Okta, that’s a group attribute statement; in Microsoft Entra ID, a group claim.
  • OIDC: a groups claim, or your custom attribute’s name, in the ID token or userinfo response.

The IT admin can check what their IdP sends with Test Connection in the admin portal. The result lists the attributes Scalekit received.

The ID token from the code exchange carries groups as a list, and each custom attribute as a claim of its own. In your callback, after you validate the ID token, pass its claims to a function like this one and save the result on the user:

roles.js
// Your app's role for each of a customer's IdP groups. Each customer names
// its groups differently, so keep this map per organization.
const GROUP_ROLES = {
'<organization-id>': { 'App Admins': 'admin', 'App Editors': 'editor' },
};
const ROLES_BY_RANK = ['admin', 'editor', 'viewer'];
function roleFor(claims) {
const groupRoles = GROUP_ROLES[claims.oid] ?? {};
const groups = Array.isArray(claims.groups) ? claims.groups : [];
const roles = groups.map((group) => groupRoles[group]);
// A custom attribute that names the role directly, if you use one
if (ROLES_BY_RANK.includes(claims.app_role)) roles.push(claims.app_role);
// The highest role wins; a user in no mapped group gets the lowest
return ROLES_BY_RANK.find((role) => roles.includes(role)) ?? 'viewer';
}
// In your callback, after: claims = await scalekit.validateToken(result.idToken);
// user.role = roleFor(claims);

Keep these rules in the function:

  • Set the role at every login, not only the first. When the IT admin removes someone from a group, the change reaches your app at the user’s next login.
  • Map groups per organization. One customer’s “Admins” group says nothing about another’s. The ID token’s oid claim tells you whose groups they are.
  • Accept only roles your app defines. Ignore groups and values you haven’t mapped, and give users with none the lowest role.
  1. Add a custom attribute named app_role, as in Turn on the attribute.
  2. Start a login for your test organization. In the SSO simulator, select + Add Attribute, enter app_role as the key and admin as the value, and select Simulate Login.
  3. Your callback’s ID token claims include "app_role": "admin", and the user’s role is admin.

The simulator sends each value as text, so test Groups with a real IdP, such as a free Okta developer account.

These names are used by Scalekit. A custom attribute with one of them is dropped or overwritten:

NameUse
roles, permissionsRoles and permissions in Scalekit’s full-stack auth. In Modular SSO, send groups or a custom attribute such as app_role instead
email, email_verifiedStandard email claims
name, given_name, family_nameStandard profile claims
sub, oid, sidScalekit identifiers