Skip to content

Group based permissions

Warning

This document should never be followed as the default way of defining application permissions. For most cases we recommend using the default role based permissions, which doesn't have any privacy implications and doesn't need an official approval for setting it up.

Most applications can be defined with a well defined set of roles (e.g. user, administrator, help-desk), but this approach could be very limited for other applications with more fine-grained permissions. For example, an application containing wiki pages could need to define read, edit and administrate permissions for each page. With the role-based approach, each page would have to be a separate application with roles such as reader, editor and administrator for them. If this wiki contains just a few pages it is possible to set this up, but if we expect thousands of pages that can be dynamically created we can see that it wouldn't scale easily.

We accept that, only in those cases, the application needs to get the group memberships of its users to manage their access rights according to the application's own permissions scheme. We will configure your application registration so that your application will be able to get these groups easily by reading them from the authentication response or OpenID Connect token.

In order to set up group based permissions, these are the steps that you will have to follow:

  1. Create a Service Now request using the following form: Request Form.
  2. Once the request is approved, configure your application to read the groups claim or field.

The groups field

  • OpenID Connect: It will be included in the ID Token (not the Access Token) and the UserInfo endpoint in the groups claim. Remember that the application has to use OpenID Connect (not just OAuth2) in order to include the ID Token in the response, i.e. it has to include the openid scope.

  • SAML: It will be included in your authentication response as a multivalued attribute.

 <saml:Attribute FriendlyName="Group"
                      Name="http://schemas.xmlsoap.org/claims/Group"
                      NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
    <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:type="xs:string">my-group
    </saml:AttributeValue>
</saml:Attribute>

Recommendations

Some users are members of a very large number of groups, making the token or authentication response size much larger than the usual size. Your application should handle tokens in a different way accordingly.

1. Prefer using OpenID Connect over SAML

SAML responses are limited to the HTTP header size limit, which is about 8KB. This limit can be easily reached with users that contain over 1000 groups. In OpenID Connect the token is always sent in the HTTP body, which has no size limit.

When using OpenID Connect, a common solution for keeping the user session is saving the ID Token or Access Token as a cookie. The ID Token will very likely be too large for the maximum size of a cookie, which could be as low as 4096 bytes depending on the web browser. Instead of that, you can save the Access Token or generate your own application session cookies.