Channeltivity includes full support for SAML 2.0 (Security Assertion Markup Language, an open standard for single sign-on) and can be configured both as a SAML Identity Provider (IdP) and Service Provider (SP). This article explains how to set Channeltivity up as a SAML Identity Provider, which allows Users to log into external applications (SAML Service Providers) from Channeltivity. If you're instead looking to allow Users to log into Channeltivity through an external application, check out the article How to configure Channeltivity as a SAML 2.0 Service Provider.
This article walks you through the process of setting up a sample SAML integration using Litmos LMS as an example.
Step 1: Enable SSO
Logged into Channeltivity as an administrator, go to Settings > Single Sign-On (SSO) > SAML Service Provider. If you don't see "SAML Service Provider" in the navigation (see screenshot), your Channeltivity instance doesn't have single sign-on enabled and you'll need to contact Channeltivity support to get SSO turned on.
Step 2: Get the metadata and/or certificate
If SSO is enabled, you'll see the following page (or similar) with Channeltivity's Identity Provider (IdP) information and a list of all available Service Providers (SPs), which are turned off by default. There are a number of predefined SPs, but you can also define your own. Many SPs can be configured simply by uploading your metadata, in which case you'll need to download Channeltivity's IdP metadata, which contains the certificate and all other information necessary for the SP to allow SSO. In some cases you'll just need the certificate, depending on your SP's requirements.
Step 3: Configure the SP
Depending on the Service Provider, you'll need to do a number of things to properly configure SAML. In the best case, you'll simply upload the metadata you downloaded from Channeltivity, but in other cases you might need to do a bit more. In the case of Litmos LMS (pictured below), the configuration screen asks for the Origin URL (which is your Channeltivity URL) and the SAML Certificate, which you can download from Channeltivity, open in a text editor, and paste into the Litmos configuration screen (below). Make sure that autoprovisioning of users is enabled.
Step 4: Configure the SP in Channeltivity
Once your SP is configured, you'll need to add the SP details in Channeltivity. Either click the New Service Provider button or the existing SP in the list and press the Edit button to go to the edit screen.
Enter the Entity ID (which really can be anything, but often is a URL and definitely shouldn't be changed once it's set) and Assertion Consumer Service URL (which is the same as the SAML endpoint for Litmos from the previous screenshot). Check the "Sign SAML Response" box to ensure the security of the SSO process. If you want to restrict access to SSO to certain Channeltivity Groups, use the "Service Provider Access" dropdown to define a new permissions resource that then becomes available in the Group Edit page.
Step 5: Set any custom SAML Attributes
Once you've saved the SP details, you can set Custom SAML Attributes on the SP details page. Custom attributes allow you to pass additional information from Channeltivity to the Service Provider in the SAML Response. This is critical for auto-provisioning of Users because it allows you to pass the User's name, email and other information to the SP. Each attribute consists of a name and value. Use placeholders to dynamically replace values with data from Channeltivity during single sign-on. The predefined Litmos SP already has custom attributes defined, so there's nothing left to do, but depending on the SP you might require additional ones.
Step 6: Activate the Service Provider
Once you're done configuring, activate your SP using the Actions menu:
Step 7: Test SSO by clicking on the Jump Page Link
Once the Service Provider settings are completed, you'll need to test the Jump Page Link to ensure everything is working. If you run into any errors, you can try updating the "Advanced options" SP settings or check the Integration Log for details. We're happy to help if you get stuck. The jump page can be found on the SP details page and also on the list of SPs from the main SAML settings page.
Step 7: Add the Jump Page to your Channeltivity portal
Now that SSO is properly configured it's time to embed the Jump Page Link anywhere in Channeltivity so that authorized Users who click on the link will be seamlessly logged into the Service Provider.
- To add the Jump Page to the top navigation, go to Settings > Portal Customization > Menu & Page Manager and hit the "Add" button to create a new External Link or iFrame Link, pointing to the Jump Page Link.
- To add it as a content item on the home page (or other content page), create a new Article and link the Title to a "Link", pointing to the Jump Page Link.
Tip: Deep linking to specific content
There are two ways to set up deep linking:
Deep Linking Option 1: Make Channeltivity the only way to log into the Service Provider (Recommended)
The most user-friendly way to deep link to content is to configure your Service Provider to use Channeltivity as the only way to log in. Any unauthenticated users accessing any page of the Service Provider will be redirected to Channeltivity for authentication. The initially requested page is passed to Channeltivity in the SAML Request and included as a RelayState when the user is passed back to the Service Provider. This is known as Service Provider-initiated SSO. The benefit of this method is that the user doesn't go through the full SSO process every time they access a deep-linked page. The drawback is that the only way to log into the Service Provider is through Channeltivity.
Deep Linking Option 2: Pass the target link with the Jump Page Link (Easier)
The easier way to deep link is to use Channeltivity's support for SAML RelayState, which allows you to specify which page to go to after the SSO process completes. Simply append the content destination to the Jump Page Link using the target querystring variable. For example, if your jump page link is /Connector/ServiceProvider/1 and you want to deep link to the Service Provider page /MyDirectory/MyPage.html, you would structure the Jump Page like this:
Two things to note:
- Channeltivity only supports local links, which means your target cannot start with http:// or the like. This is done for security reasons.
- You must URL encode the target
While this is the easier way to deep link to content on the Service Provider, it's not as fast, because the Jump Page will initiate a full SSO process every time the link is clicked.