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

    Configuring Integration Profiles

    This section discusses how to configure integration profiles – a set of defined configurations that allow campusM to integrate with third-party applications.

    Permissions

    The following permissions are required to configure integration profiles:
    • System administrators with the All Permissions option selected
    • Users with the Can change integration profile permission
    You configure integration profiles from App Manager > App Settings > Integration Profiles. Select Add integration profile:
    configure_integration_profiles_part_1.png
    Configure Integration Profiles - Part 1
    Fill in a name and description for the integration profile. Select a Type and a Subtype.
    Additional fields appear, depending in the type and subtype.
    For all campusM token based authentications, the following attributes appear in the second part of the authentication configuration page:
    • Username Mapping (required): The name of the attribute in the response to be used as the campusM app username.
    • Mail Mapping (required): The name of the attribute in the response that contains the user’s email.
    • First Name Mapping (required): The name of the attribute in the response that contains the user’s first name.
    • Last Name Mapping (required): The name of the attribute in the response that contains the user’s last name.
    • Additional Mappings (optional): This field takes multiple comma delimited name and value pairs that are added in a designated part of the token, where additional information can be kept and then used in the different parts of the application. A single value can be supplied if the same attribute name in the response should be used (so instead of department=department, you can type just department). For example: job=title,tel=mobile,office,department.
    • Additional Encrypted Mappings (optional): Same as Additional Mapings, but is encrypted on the token.
    • Token Lifetime: The expiration date for the generated token used by campusM. If left empty, the default is 30 days for both Web and Native mobile. Example values are: 30d, 120m, 72h.
      It is recommended to have the token lifetime (expiration) configured at the 30d level to avoid the need for the user to frequently need to re-login/authenticate to campusM.
      The token lifetime definition represents the campusM authentication token lifetime (the one used within campusM to ensure the user is authorized to use the system functions), NOT the IdP session/token lifetime (when relevant) which is typically much shorter than 30d, and may be passed by the browser to seamlessly login to other systems covered by the same IdP.
    These attributes are expected to be returned as part of the response from the IdP, regardless of which authentication method is used. They can be mapped to any available attribute returned during the login process.
    With SAML, these are expected to be part of the returned assertions. With OAuth2/OIDC, part of the response is returned from the user information endpoint, or attributes present on the id_token if a user information endpoint is not provided.

    Configurations Per Authentication Type

    The following sections describe the configurations necessary for the different authentication types.

    SAML2

    This section describes the configurations necessary for the SAML2 authentication type.

    Customer Configuration for SAML2

    Perform the following configurations on the customer's environments for SAML2:
    Download the campusM SAML metadata file from the following URL:
    <org_web_hostname>/cmauth/saml/metadata
    You can also download the metadata by clicking the Get SAML Metadata button when selecting SAML as the authentication subtype.
    Do this for each campusM environment that you work with: Production, Sandbox, and Preview. Add each of the metadata files to the IdP’s configuration.

    campusM Configuration for SAML2

    Perform the following configurations in campusM for SAML2:
    configure_integration_profiles_saml_part_2.png
    campusM Configuration for SAML2
    Fill out the fields of the integration profile configuration according to the following:
    • CampusM Certificate (required) – The certificate used for communication. Select the one with the latest expiration date.
    • Entity ID – an attribute on the root EntityDescriptor element in the IdP’s metadata.
    • SSO (Single Sign On) URL (required) – at the end of the IDPSSODescriptor element (the first one, if there are multiple) is one or more SingleSignOnService elements. Take the one that has its Binding element set to: urn:oasis:names:tc:SAML:2.0:bindings:HTTPRedirect and fill the Location attribute here.
    • Certificate –  In the IDPSSODescriptor element of the metadata, there are one or more KeyDescriptor elements that may have an optional use attribute. Copy the attribute that is set to signing, and put it in the X509Certificate element.
    • Additional Certificate – You can add an additional certificate. 
    • IDP Logout URL (optional) – a general logout URL that allows the IdP to terminate the user’s session. For Shibboleth, an example syntax is: https:///idp/profile/Logout
    The following diagram illustrates the SAML2 Workflow:
    saml2_workflow.png
    SAML2 Workflow

    OAuth2

    This section describes the configurations necessary for the OAuth2 authentication type.
    campusM implementation of OAuth2 uses the authorization code flow: https://tools.ietf.org/html/rfc6749#page-24

    Customer Configuration for OAuth2

    Perform the following configurations on the customer's environments for OAuth2:
    Register the app as a client on the customer’s side from which a client ID and optionally a client secret (recommended) is produced. Use the following redirect URI:
    <org_web_hostname>/cmauth/oauth/callback
    Do this for each campusM environment that you work with: Production, Sandbox, and Preview. Add each of the metadata files to the IdP’s configuration.

    campusM Configuration for OAuth2

    Perform the following configurations in campusM for OAuth2:
    configure_integration_profiles_oauth_part_2.png
    campusM Configuration for OAuth
    Fill out the fields of the integration profile configuration, according to the following:
    • OAuth Client ID (required) – the client ID that the customer’s system produces when registering the campusm app.
    • OAuth Client secret (optional) – this is provided when registering the app. Optional, but recommended.
    • Authorization endpoint (required) – the endpoint to where the user is redirected for login.
    • Access token endpoint (required) – the endpoint from where the OAuth tokens are fetched.
    • Token Endpoint Auth – the authentication method used for the token endpoint. Options are Post or Basic.
    • User info endpoint (optional) – the endpoint from which user information is retrieved by using the access token. If this is not provided, it is expected that the user information is contained in an id_token (JWT) returned from the access token endpoint response. If that is not found, the access token is expected to be a jwt token containing the information.
    • OAuth Scope (optional) – used to define the amount of information sent back in the responses.
    • Logout URL (optional) – a general logout URL that allows the IdP to terminate the user’s session. For Shibboleth, an example syntax is: https:///idp/profile/Logout. If this is not provided, the user’s session with the IdP are not terminated when logging out of campusM.
    • Token verification certificate (optional) – The certificate with which the token (either id_token or access_token where a user info endpoint is not provided) can be verified. Only one certificate is supported currently, so if there is a rotating set of keys that is being used to sign the tokens, leave this empty.
    • Extract OAuth tokens (optional) – not selected by default. Selecting this option saves encrypted during the login process the tokens returned from the access token endpoint on the resulting campusM token for later use.
      The following is required for this to function properly:
      • Access token and expiry (expires_in)
      • Refresh token (refresh_token)

    OIDC

    OIDC configuration is essentially the same as OAuth2. Use the same integration profile type and follow the same steps.
    The customer may provide you with a discovery URL (similar to the SAML metadata file) from which you can get the required information to complete the configuration.
    The following is an example of the OIDC metadata:
    oidc_metadata.png
    OIDC Metadata
    The OAuth2 implementation is compatible with OpenID, but not fully compliant. OAuth2 works with OpenID, but it does not support all OpenID features, for example, there is no dynamic registration, and the configuration is not updated automatically with the discovery document.

    LDAP (Login Web Service)

    It is possible to use the connect layer’s login endpoint as the authentication mechanism.

    Customer Configuration for LDAP

    Configure the connect layer with a login endpoint that returns the expected attributes.

    campusM Configuration for LDAP

    Perform the following configurations in campusM for LDAP:
    configure_integration_profiles_ldap_part_2.png
    campusM Configuration for LDAP
    Fill out the fields of the integration profile configuration, according to the following:
    • Login screen prompt (required) – the message to be displayed on the login screen
    • Authentication server (required) – the connect layer against which to authenticate
    • Login service path (required) – the path to the login service

    Testing Integration Profiles

    If the Integration profile link does not appear, you are using the legacy authentication method. For more information, contact campusM support.
    You can test the campusM authentication profiles to confirm that that parameter data is valid and identify the causes of an authentication failure.
    To test integration profiles:
    1. From the Main Menu, select App Settings > App Settings > Integration Profiles. A list of your integration profiles appears.
    2. Select an integration profile. The following page, for example, appears displaying the integration profile information:
      change_integration_profile.png
      Change Integration Profile
    3. To test the profile, select Test Profile. The following page appears, displaying the authentication request and the request redirect URL.
      Any changes you make must be saved before you can test the profile.
      build_authentication_request.png
      Build Authentication Request
    4. Select Continue. A new IdP login page appears.
    5. Enter your username and password and log in.
      A test report appears indicating if the test passed successfully or if there were any failures. Click on an element to see more information.
      profile_test_report.png
      Profile Test Report
    • Was this article helpful?