API: Single Sign On (SSO)

If you have an existing ecosystem of sites available to your subscribers, you can setup Content Catalyst to participate in existing user login sessions so your users can instantly access Content Catalyst without logging in.

To set it up, please contact support. We will need the following information from you (explained in more detail below):

The URL of a hosted website or login hub to direct traffic to.
If you have an open site, we can optionally direct users attempting to register to a different URL where they can be presented with a Register form instead of Login.
We optionally provide a “Return URL” to indicate the page the user was attempting to access before they were forwarded to the authentication hub. To use it, we need the name of the query parameter to provide it (we recommend returnUrl).

We will provide you with a shared, secret key which can be used to generate a temporary session key.

🚨Note: It is important to keep this key secure because it can be used to login as anyone on the system, including administrators.

How a user would Sign in

When SSO is enabled, any unauthenticated users (or bots) accessing the site will be redirected to your authentication hub.

The authentication hub is responsible for confirming who the user is. This could be by detecting an established login session (e.g. a cookie) or asking the user to login/register.

You could also present a security screen at this stage to ensure the user is trying to access Content Catalyst.

If the user was recognised, or after they have logged in, the authentication hub should use the following call GET ~/api/v1/authenticate/singlesignon to generate a temporary session key.

(An example of using the API is below, or follow the link to get more information on this endpoint).

The user should then be redirected back to Content Catalyst (using the URL defined below), by automatically redirecting the user's browser or asking the user to click a link.

Generating the redirect URL

Once you’ve obtained a session key, you need to generate a URL in the style of https://{Host}/ir/irLogin.aspx?un={UserName}&SessionKey={SessionKey}.

If the user was redirected from iReports, we will include which page the user was trying to access. For the best user experience, you should include this value in the optional ReturnUrl query parameter.

This will allow the user to continue from where they were trying to access seamlessly. .

Parameter	Value
Host	The base URL of this site
UserName	The name of the user to be logged in
SessionKey	The session key obtained from the API
ReturnUrl	Optional: A relative URL to a page in iReports

🚨Note : You should URL encode the username, session key and return URL parameters.

See examples below.

Bash
C#

Bash

#!/bin/bash 
baseUrl=$1 
username=$2 
secretKey=$3 
returnUrl=$4  

# Get the sessionKey and pipe through jq to deserialize the JSON (and select the current node which is a string) 
sessionKey=$(curl -s -d username=$username -d authkey=$secretKey -H "accept: application/json" -G "${baseUrl}api/v1/authenticate/singlesignon" | jq -r '.')  

echo "https://example.com/ir/irLogin.aspx?un=$username&SessionKey=$sessionKey&returnUrl=$returnUrl"

C#

using System; 
using IO.Swagger.v1.Api; 
using IO.Swagger.v1.Client; 
using Newtonsoft.Json;  

public string GetRedirectUrl(string username, string secretKey, string returnUrl) 
{     
var authClient = new AuthenticationApi(_v1Configuration);      

// Normally responses are automatically deserialzed, but this client doesn't deserialize plain strings correctly, so pass through JSON.NET for correct handling.     
var sessionKey = JsonConvert.DeserializeObject<string>(authClient.AuthenticateSinglesignonGet(username, secretKey));     
if (string.IsNullOrEmpty(sessionKey))     
{         
throw new InvalidOperationException("Invalid secret key or username");     
}      

return string.Format(         
"http://example.com/ir/irlogin.aspx?un={0}&SessionKey={1}&returnUrl={2}",
Uri.EscapeDataString(username), Uri.EscapeDataString(sessionKey), Uri.EscapeDataString(returnUrl)); }

User impersonation

If you have support staff who need to temporarily impersonate a user, you can use SSO from your CRM to begin an impersonated session.

When requesting a session key, you can specify the optional ‘impersonateUsername’ parameter. You can then generate a session key as normal (The Username in the URL should be your support staff username).

To use this feature, your staff member must either have the ‘Client’ admin right, or their preference ‘Can impersonate other users’ must be true.