Skip to main content
ExLibris
  • Subscribe by RSS
  • Ex Libris Knowledge Center

    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 and Roles and RoleSync.
    For more information, watch 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

    Required Format

    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 (-).

    json_microsoft_graph_API.png

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

    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:

    technical_flow_diagram_roles.png

    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.png

    Roles Configuration
    Select one of the following links to see the configuration options for that 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 via campusM API

    When a user role has changed, the institution needs to call the campusM setRolesUpdated API service. The following steps describe the update process:

    1. The user is currently logged in to the app.
    2. User roles have changed—for example, a new role was added, or an existing role removed.
    3. Institution: Calls the campusM setRolesUpdated API, including the user email address.
    4. The user launches the app.https://developers.exlibrisgroup.com/campusm/apis/refresh-user-roles/
    5. The app calls the startup service on campusM, which informs the app that the roles of this user require an update.
    6. The app calls the login service on the campusM Connect Layer, triggering the institution Roles API to retrieve the user’s new roles.
    7. The app presents the content and tiles according to the new user roles.
    • Was this article helpful?