How-to guide
Read groups and roles in your app
Get the person's access groups and roles from the ID token or the SAML assertion and use them for permissions.
This guide gets the groups and roles an admin assigned for your app into your app, so you can base permissions on them.
What your app receives is limited to its own access: the groups that give access to your app, and the roles set for those groups on your app. It never sees the organization’s other groups. About access, groups and roles explains the model.
Before you start
Ask an admin to:
- give the groups access to your app on Access & diagnostics, with a Role where you need one (see Send roles to apps);
- for an OpenID Connect app, tick groups under Scopes & options.
Agree with the admin on the role names. Sovrain does not check them; it passes on whatever text was entered.
With OpenID Connect
Add
groupsto the scopes of the authorization request:&scope=openid%20profile%20groupsIf groups is not ticked for your app, Sovrain refuses the whole request with
invalid_scope.Read the claims from the ID token, or from userinfo:
{ "groups": ["Engineering"], "role": ["editor"] }groupslists group names, sorted. It is always present when the scope was granted, as[]if none applies.rolelists the distinct roles of those groups, sorted. It is left out when no group has a role, so treat a missingroleas no role.
Map names to permissions in your app. Because the values are names, renaming a group in Sovrain changes what your app receives; update your mapping when that happens.
Claims are worked out when a token is issued. Changes reach your app at the next sign-in or token refresh. Userinfo always answers with the current values.
With SAML
Read the role attribute of the assertion. It has one value per distinct role of the person’s groups with access, and
it is sent without any attribute mapping. When no group has a role, the attribute is not sent.
SAML assertions carry no groups attribute. If your app needs to tell groups apart, ask the admin to give each group a
role.
What Sovrain does not send
- Groups that do not give access to your app, even if the person belongs to them.
- Nested groups: Sovrain has none.
- Group IDs: only names.
All claims and attributes: Claims and attributes and SAML.