Notice: As of January 2017, we recommend using our SAML 2.0 Service Provider Configuration instead of Incoming SSO. Support for Incoming SSO will be removed at some point in the future.
The Incoming Single Sign-On (SSO) API allows you to seamlessly pass user sessions from an external application into Channeltivity's PRM software without requiring users to enter a username or password. This article explains how Incoming SSO works and outlines implementation steps.
How Incoming SSO works
Incoming SSO is fairly straightforward but will require a developer to implement. Here is how a user would log into Channeltivity from an external web application:
- The user logs into your external application (the "Originating System").
- Within the Originating System, the user then clicks on a link to Channeltivity's partner portal software. The Originating System will need to include the user's session information and email address in the query string of the link to Channeltivity, similar to http://PartnerPortal.YourDomain.com/SomePage?email=sample.user%40company.com&session=5ampIe5essi0nId. The session key should be a unique identifier within the Originating System. (This is what you'll have to develop.)
- Once the user arrives on the page, Channeltivity will take the email address and session key and use them to call a special Authentication Web Service on the Originating System (you'll need to implement this too). This Web Service checks the passed information and returns whether it's valid, in which case Channeltivity will log the user in and show him the requested page.
Incoming SSO FAQ:
What happens if the user trying to log in using Incoming SSO doesn't exist in Channeltivity?
Only users that have active or pending accounts in Channeltivity can log in using Incoming SSO. You will need to create users within Channeltivity and set their group permissions. This can be done with Channeltivity's Data API.
Will creating a new user within Channeltivity send out an email invitation if I have Incoming SSO active?
Activating Incoming SSO disables invitation emails from getting sent out.
- What happens when a newly created user logs into Channeltivity using Incoming SSO for the first time?
Once the user is successfully authenticated using the Originating System's Authentication Web Service, the user will need to fill out their profile. You can pre-fill the user's profile using our Data API.
What happens to the user in Channeltivity once the session times out?
If the user requests a Channeltivity page and is not logged in, they will be redirected to a page on the Originating System that you specify. You can configure Channeltivity to include the URL of the page the user was trying to access along with the reason they were redirected. You should ideally follow the best practices outlined in the Seamless Invalid Session Handling article.
- I've enabled Incoming SSO but there's something wrong with my implementation and now I can't log into Channeltivity. What do I do?
To prevent the automatic redirect to the Originating System, simply add "NoSSO=true" to the login page URL, like so: http://YourChanneltivityURL/?NoSSO=true
How to implement Incoming SSO
Follow these steps to implement Incoming SSO with Channeltivity:
- Send us a support ticket asking us to enable Incoming SSO.
- Once Incoming SSO is enabled, navigate to the Portal Settings page:
- Find the link to the SSO Settings page:
- Review the Incoming SSO settings page and download the WSDL for the authentication Web Service your Originating System will need to implement. You can implement your Web Service using SOAP or REST (JSON or XML):
- Implement the Authentication Web Service and update the settings with the details. Make sure to review the inline help for the individual settings. If you use JSON, make sure to set the Content-Type to "application/json; charset=utf-8" and return just true or false in the body (no quotes).
- Test the Authentication Web Service using the tool provided on the SSO Settings page:
- Once you complete your testing, activate Incoming SSO by checking the box at the top of the settings page. That's it, you have successfully implemented Incoming SSO.