Role based permissions (recommended)

What is a role?

A role is an identifier for a set of permissions in your application, that can be assigned to a group of users.

The authentication token provided to users when they login to your application will contain all the roles that the users have in your application only, in a special claim named cern_roles for OIDC or CernRolesfor SAML.

The concept of roles was introduced to let applications enforce their own authorization scheme without querying for groups membership.

Since a user can potentially be a member of many groups, if we were putting all groups memberships in a user's token, we would reach a point where the token becomes so big that browsers cannot handle it.

This forced applications to query an external groups data source (generally LDAP) to determine if a user is a member of a group granting certain privileges.

If you define roles for your application, the authentication tokens of the users accessing your application will always contain all the relevant information for your authorization decisions, without being bloated with irrelevant groups memberships.

For example, a users's token could tell your application that that user has the application_administrator role, without containing the irrelevant information that the user is a member of vogons-at-cern group.

How do roles work

As we said, roles can be assigned to groups of users: when a user logs in to your application, their Single Sign-on token will contain all the roles that are mapped to any of the groups they are member of. Alternatively, roles may apply to all authenticated users rather than identifying specific groups; this is useful if, for example, you would like to know whether all users have authenticated with Multi-Factor or not.

Please note that group membership is evaluated recursively.
Example:

• You assign the role application_users to the group building-XYZ.
• The group building-XYZ-1st-floor is member of building-XYZ.
• A user who is member of the group building-XYZ-1st-floor logs in to your application.
• The user's token contains the role application_users.

Role requirements

Roles can define additional authentication requirements for Multi-Factor Authentication (MFA) and Level Of Assurance (LOA).

Multi-Factor Authentication (MFA) is an identity verification process requiring more than one method of authentication from the user (for example, a password and a one-time code).

Multi-factor authentication provides a higher degree of security than regular (single-factor) authentication.
If you enforce the MFA requirement on a certain role, a user logging in to your application will get a token containing that role only if they are member of a group mapped to the role and they logged in using multi-factor authentication.

The Level of Assurance (LOA) is the degree of confidence in the identity verification process established by the authentication provider issuing the user's credentials.

You can select specific LOA values, as follows:

• CERN: the user must have shown in person, with a valid ID document, at a secretariat or other registration office.
• EduGain with Sirtfi: the user is authenticated by an institution that is part of the EduGain identity federation (and that follows security practices called Sirtfi). These users are typically members of universities or other research institutes.
• Social accounts: anybody can register such an account, with little control or identity verification.

If you enforce the LOA requirement on a certain role, a user logging in to your application will get a token containing that role only if they logged in using an account from an identity provider with a sufficiently high LOA.

If you wish to restrict access to any known CERN person, regardless of the LOA, please see the example further down this documentation.

Restricting access with required roles

You can choose to block access to some users at the SSO level by setting up a required role.

If a role is required, users who do not belong to that role will not be able to access your application: after authenticating, they will receive an access denied error from the Single Sign On service.

For example, if you want to limit access to your application only to users above a certain level of assurance, you could setup a required role, tick the option to apply the role to all users, then set a LoA requirement on the role.

Default role

When you register your application for SSO, a default role is added to only allow users with a CERN or eduGAIN account to authenticate. You can modify this role if you would also like to allow social accounts (e.g. Google or Facebook) or guest accounts (self-registration, formerly known as Lightweight Accounts).

Defining a role

You can define roles from the application page:

The Role Name is a readable name for your role.

The Unique Identifier is a unique identifier for your role:

• it must be unique for your application
• it must start with a lowercase letter
• it can contain only lowercase letters, numbers, dashes and underscores
• must be between 3 and 64 characters long

The unique identifier of the role is the value that will be passed in the resource_access.{aplication_name}.roles claim of the user token, i.e. the value that your application will need to check to perform authorization decisions.

If you want to restrict access to your application only to users belonging to a certain role, tick the "this role is required" checkbox.

If you want to require that users authenticate with multi-factor authentication to your application to obtain a certain role, tick the "users with this role require multifactor authentication" checkbox.

Note: If this box is ticked the application will redirect the user to login with Two-factor authentication by appending only2fa=true to the URL query parameters.

If you want a role to apply to all authenticated users, regardless of groups, select "This role applies to all authenticated users".

Mapping roles to groups

Now that we have defined the roles for our application, we need to map each of them to one or more groups, so that users that are members of those group will obtain the corresponding roles in the SSO token (provided that MFA and LOA requirements for the role are met).

Clicking on the green "Assign role to groups" button in the roles list will let you define the groups that are mapped to that role.

Examples

The roles system is very flexible. A couple of examples are included here to help you get started.

CERN accounts and admins

I run a site for the library; only CERN accounts should be able to access and, in addition, I need to identify librarians (in group librarians) so that they can be access the management area.

1. Create a role called allowed-users, select Required, select This role applies to all users and set the minimum Level of Assurance to CERN (Highest)
2. Configure a second role called librarian, do not select Required, once it's created link it to the group librarians

Specific teams with 2FA

I run a site for the finance department; people from the finance team (in group finance-team) should be able to access and they must use second factor authentication. In addition, some IT support staff (in group finance-it-support) must be able to log in and be identified as IT support.

In this case we need to think a bit harder since users must have ALL required roles in order to authenticate. Consequently the IT staff must also use 2FA if we want to enforce 2FA at the SSO level. You could also choose to make all roles optional and process them within your application.

1. Create a role called allowed-users, select Required, select Multifactor Required, once it's created link it to two groups, finance-team and finance-it-support
2. Create a role called it-support, do not select Required, once it's created link it to the group e.g. finance-it-support

Anyone with 2FA

Anybody should be able to access my site, but they must use second factor authentication

In this case we need to create a required role, that requires Multifactor and applies to all users (i.e. we don't link it to specific groups).

Only known CERN people

I only want known CERN people to be able to log in, this should include ex-employees as well as currently active CERN members.

Create a role with LoA = Social (lowest) and select Required. The link it to 2 groups: cern-active-users and cern-non-active-users. These two groups together contain all the people known by CERN.