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.



This article explains an advanced technique of session handling used with Incoming SSO and assumes familiarity with Channeltivity's Incoming Single Sign-On process.



Problem: 


When you have incoming SSO enabled and request a page in the Channeltivity partner portal without being logged in (clicking on a link in an email notification, for example), Channeltivity will redirect you to the Originating System. Once the Originating System validates your session, you will need to go through the single sign-on process to access Channeltivity, but won't end up on the page you originally requested, creating a negative user experience.



Solution: 


When both the Originating System and Channeltivity are configured for seamless invalid session handling, the user experience is greatly improved to the following:

  1. Click on link in email
  2. Enter login and password
  3. View Lead


Here's an example that illustrates how this is implemented:

  1. The User clicks on a link within an email that links to a Lead within Channeltivity:
    https://company.channeltivity.com/Leads/123
  2. Since the User is not logged into Channeltivity, he is redirected to the SSO Jump Page of the Originating System along with the URLEncoded link he was originally trying to access and a code for the reason he was redirected ("NotLoggedIn" in this case, full list below):
    https://originatingsys.com/SSO?reason=1&target=https%3A%2F%2Fcompany.channeltivity.com%2FLeads%2F123
  3. Since the User is not logged into the Originating System either, he is redirected to the login page of the Originating System. The SSO Jump Page URL he was originally trying to access is again included as a URLEncoded querystring variable:
    https://originatingsys.com/Login?redirect=%2FSSO%3Freason%3D1%26target%3Dhttps%253A%252F%252Fcompany.channeltivity.com%252FLeads%252F123
  4. The User enters his credentials into the Originating System, logs in successfully and is automatically redirected to the SSO Jump Page URL that was passed in the "redirect" querystring variable:
    https://originatingsys.com/SSO?reason=1&target=https%3A%2F%2Fcompany.channeltivity.com%2FLeads%2F123
  5. The SSO Jump Page creates the SSO session and redirects the User to the originally requested Lead page within Channeltivity (along with the User's email and SSO session details):
    https://company.channeltivity.com/Leads/123?email=sample.user%40company.com&session=5ampIe5essi0nId 
  6. Channeltivity validates the passed SSO session credentials by calling the Authentication Web Service on the Originating System and then displays the originally requested Lead page:
    https://company.channeltivity.com/Leads/123


Configuring Channeltivity

The Incoming SSO configuration page allows you to specify the URL to redirect users with invalid sessions (Invalid Session URL) along with the querystring variables for redirect reason code and target link.




Originating System Recommended Architecture

In order to implement seamless invalid session handling with Channeltivity, we recommend the following architecture in the Originating System:
  • The Originating System login page should allow specifying a redirect location in the querystring to send the User once the login is successful.
  • The Originating System should have a SSO Jump Page that creates the single point of entry into Channeltivity using the Single Sign-On process. Recommended Jump Page functionality is below.



Recommended Jump Page Functionality

Here's the recommended workflow for the SSO Jump Page on the Originating System:

  1. If the user's Originating System session isn't valid, redirect to the login page with the current Jump Page full URL passed URLEncoded in the querystring. Otherwise continue.
  2. If there's a reason code in the querystring, handle as follows:
    1. NotLoggedIn (1): redirect the user to the requested Channeltivity page using the Incoming SSO process (step 4)
    2. SessionTimeout (2): redirect the user to the requested Channeltivity page using the Incoming SSO process (step 4)
    3. AccessDenied (3): display an "access denied" message or hand some other way
    4. AuthenticationFailed (4): display an error message
    5. UserNotFound (5): go to the user creation process below (step 3)
    6. Logout (6): log the user out of the Originating System and redirect them to the Originating System login page
    7. InactiveUser (7): display an error message
    8. ExpiredUser (8): display an error message
    9. CookiesNotEnabled (9): display an error message
    10. InvalidSession (10): display an error message
  3. Check if the User exists and create it using the process outlined in this article. 
  4. If there's a target Channeltivity URL in the querystring, redirect the user to the page, following the regular Incoming SSO process of adding the user's email and Originating System session in the querystring. Otherwise use the same process to redirect the user to the Channeltivity home page.



Redirect Reason Codes:
  • 1 = NotLoggedIn - The User is not logged into Channeltivity. 
  • 2 = SessionTimeout - The User's Channeltivity session expired.
  • 3 = AccessDenied - The User is logged into Channeltivity, but doesn't have permissions to access the requested page.
  • 4 = AuthenticationFailed - The response Channeltivity got from the Originating System's Authentication Web Service was that the provided email and SSO session key was invalid.
  • 5 = UserNotFound - The User doesn't exist in Channeltivity (or is not active).
  • 6 = Logout - The User pressed the "Logout" link within Channeltivity (Single Sign-Out)
  • 7 = InactiveUser - The User is inactive.
  • 8 = ExpiredUser - The User has expired.
  • 9 = CookiesNotEnabled - Cookies are not enabled.
  • 10 = InvalidSession - Invalid session string/hash.