Roles

Overview

The Roles product integration allows the customer to have RoleSync functionality.

For more information on using Roles in campusM app manager, see Managing App Roles.

For more information, watch:

Roles and RoleSync (8 min)
Roles Integration (7:52 min)

Vendors

Roles can be retrieved with a RESTful API service, with Microsoft Graph API services, and the adAS SSO and OKTA Groups, which are configured as part of the Roles product integration configuration.

User Experience

The following section describes information relating to the user experience for the Roles PI.

User Activities

Users view tiles according to the roles to which they are assigned.

Authentication

Users do not need to enter their authentication credentials at any stage. See the User Flow Diagram for a description of the authentication workflow.

Offline Support

campusM checks the user's roles when the user logs in. If the user works offline when logged in, the RoleSync functionality continues to operate. But, if the user begins working offline when not logged in, the RoleSync functionality does not operate. The user is given the privileges of the default role as configured in the App Builder.

Technical Overview

The following section describes technical information for the Roles PI.

Prerequisites

The list of roles per user can be provided by a RESTful API service or by Microsoft Graph API, which returns a list of roles in JSON format.
For Microsoft Graph API vendor, you need to configure Microsoft Azure. For more information, see Configuring Microsoft Azure (Graph) for the Roles Product Integration.

Required Format

Select one of the following links for the required format for that vendor:

Required Format for RESTful API Vendor
Required Format for Microsoft Graph API Vendor
Required Format for adAS SSO Vendor
Required Format for Okta Vendor

RESTful API Vendor

The following is the required JSON format for RESTful API service:

The API service must be configured using the HTTP GET request method.

{

"roles": [
"student",
"lecturer",
"other"
]
}

Microsoft Graph API Vendor

The following is the required JSON format for Microsoft Graph API:

The list of roles returned in the displayName field can be returned separated by a delimiter that can be configured in the Roles PI configuration.

For example, in the following response, the delimiter is a hyphen (-).

The list of roles provided by the Microsoft Graph API will be acquired by using the following Microsoft Graph API services:

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token (in order to generate the token that will be used in the second service)
https://graph.microsoft.com/v1.0/users/<username>/memberOf (in order to get the response which contains the roles list from above)

adAS SSO Vendor

The following is the required JSON format for adAS SSO:

[

{

"roles": [

"role1"

]

}

]

Okta Groups

The following is the required JSON format for Okta Groups vendor:

[

{

"id": "{id}",

"created": "{date time}",

"lastUpdated": "{date time}",

"lastMembershipUpdated": "{date time}",

"objectClass": [

"okta:user_group"

],

"type": "{type}",

"profile": {

"name": "Everyone", // 'name' attribute in this specific hierarchy is the only attribute we expect

"description": "All users in your organization"

},

"_links": {

"logo": [

{

"name": "{name}",

"href": {url},

"type": "i{mage/png}"

},

],

"users": {

"href": {url}

},

"apps": {

"href": {url}

}

]

For more info about Okta Groups API, refer to https://developer.okta.com/docs/reference/api/groups/#list-groups.

Technical Flow Diagram

The following is the technical flow diagram for the Roles product integration:

Roles Technical Flow Diagram

Configuration

To use the Roles product integration, you must configure the following components:

Customer roles and App roles according to Managing App Roles.
A Roles product integration instance as described below.
To be done by Ex Libris – Application Server, Authentication Access, and Profile Registration Authentication.

To configure the Roles product integration, select Add Product Integration Instance from the Product Integrations main menu option, and select ROLES.

The Roles configuration page appears.

Roles Configuration

Select one of the following links to see the configuration options for that vendor:

Configurations for RESTful API Vendor
Configurations for Microsoft Graph API Vendor

Configurations for RESTful API, adAS SSO, or Okta Vendors

The following table describes the configuration options available for the RESTful API vendor:

Configuration Option	Description	Mandatory	Data Type	Default	Example
Enable Product Integration	Select to enable the product integration on the user's campusM app.	No
Product Integration Description	A description of the PI for internal use	Yes	String
Vendor Name	Select 'REST API' or 'adAS SSO'	Yes	Drop down list
API Configuration
URL to retrieve the information	URL to retrieve the roles list	Yes	URL address	none	https://yrv80x694e.execute-api.eu-we.../Prod/rolesync
Response Content Type	The content type of the response; JSON, XML etc. For Roles PI should be JSON.	No	Drop down list	JSON
URL Query Parameters	Parameters on the URL	No	An array of query parameter object information	No query parameters
URL Path Parameters	Parameters on the URL	No	An array of path parameter object information	No path parameters
API Authentication
Authentication Type	Select one of the following options: No Auth Basic Auth API Key Bearer token OAuth Using User App Authentication – select an OAuth integration profile (from the Integration Profiles configured in App Settings) and choose where the access token should be added, Header or URL. OAUTH Using Client Credentials – select this if you are using a preliminary token call to get the access token.	Yes	Drop-down list

Configurations for Microsoft Graph API Vendor

The following table describes the configuration options available for the Microsoft Graph API vendor:

Configuration Option	Description	Mandatory	Data Type	Default	Example
Enable Product Integration	Select to enable the product integration on the user's campusM app.	No
Product Integration Description	A description of the product integration for internal use	Yes
Vendor Name	Select MS Graph APIs	Yes
Microsoft Graph APIs Configuration
Delimiter	The separator between the different roles returned in the displayName field. For example, in the following response, the delimiter is a hyphen (-): displayName: US-DC-FAC	No	One of the following: - / ; , No delimiter	No delimiter
Tenant	The tenant value in the path of the request can be used to control who can sign into the application. The allowed values are common for both Microsoft accounts and work or school accounts, organizations for work or school accounts only, consumers for Microsoft accounts only, and tenant identifiers such as the tenant ID	Yes	String
Client ID	The Application ID that the registration portal assigned your app	Yes	String		6731..-..6914391e
Client Secret	The application secret that you created in the app registration portal for your app. It should not be used in a native app, because client secrets cannot be reliably stored on devices. It is required for Web apps and Web APIs that have the ability to store the client secret securely on the server side	Yes	String
Grant Type	Must be client_credentials for the authorization code flow	Yes	String		client_credentials
Scope	The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the first (authorization) leg. If the scopes specified in this request span multiple resource servers, then the v2.0 endpoint returns a token for the resource specified in the first scope	Yes	String		https://graph.microsoft.com/.default
User Input Identifier
Parameter Input Option	User input identifier for MemberOf API	Yes	Input options		username
Constant Value	Enter the constant value

Updating User Roles

When a user logs into campusM, the RoleSync web service retrieves the user’s roles from the enterprise system and assigns them to the user. Because users can remain logged into campusM for many days at a time, when roles have changed, it may be necessary to refresh them even when users are logged in. This can be done in one of two ways:

A scheduled role-refresh process (see Scheduling Automatic Role Refreshes from the App Settings, below)
Using the campusM setRolesUpdated API (see Updating Roles Via the campusM API, below)

When one of these processes is employed, users whose roles have changed are tagged, and the following occurs when the user next launches the app:

The app calls the startup service on campusM, which informs the app that the roles of this user require an update.
The app calls the configured Roles service to retrieve the user’s new roles. (For information about the Roles product-integration options and how to configure them, see Configuration, above.)
The app presents the content and tiles according to the new user roles.

Scheduling Automatic Role Refreshes from the App Settings

The Refresh RoleSync process checks which users had role changes since they last logged into campusM and flags them for RoleSync the next time they open the app. This RoleSync takes place even if they were already logged into the app when they opened it.

Refreshing the RoleSync is an automated process that must be scheduled to take place on a weekly basis. It can be scheduled to run as much as once a day. We recommend only running it once a week, because it refreshes all users.

To schedule the Role Refresh process:

Navigate to App Settings > Enterprise Roles > Refresh Roles. The Refresh Role Sync Config page opens.
Select Activate Refresh Role Sync.
Select the days of the week on which to run the process, the time of day, and the time zone.
Select Save.

Updating Roles via the campusM API

When user roles have changed – for example, a new role was added, or an existing role removed – the institution can call the campusM setRolesUpdated API service to update specific users' roles accordingly. The API call must include the emails of the users whose roles need to be updated. The users' roles are updated even if they are currently logged into campusM. For information about this API, see Refresh User Roles in the Developer Network.