Sovrain
  1. Documentation
  2. Identity provider
  3. For developers

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:

Agree with the admin on the role names. Sovrain does not check them; it passes on whatever text was entered.

With OpenID Connect

  1. Add groups to the scopes of the authorization request:

    &scope=openid%20profile%20groups
    

    If groups is not ticked for your app, Sovrain refuses the whole request with invalid_scope.

  2. Read the claims from the ID token, or from userinfo:

    {
      "groups": ["Engineering"],
      "role": ["editor"]
    }
    
    • groups lists group names, sorted. It is always present when the scope was granted, as [] if none applies.
    • role lists the distinct roles of those groups, sorted. It is left out when no group has a role, so treat a missing role as no role.
  3. 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.