Introduction
ClientAuth is useful for "custom" SSO setups where you can integrate a specific SSO flow into your own custom application.
It is an API endpoint for enabling SSO between Skillcast and a client system, without the constraints of other frameworks. It is partly based on the oAuth2 specification, though it is client-initiated, and the handshake is server-side rather than client-side.
With SSO enabled, the link then leads the user directly to the designated activity (category, learning path, module or policy).
Prerequisites on Skillcast
Following roles enabled
Domains - Single sign-on
An agreed Shared Secret/Token
An endpoint URL
An agreed user identifier (userID, username, or email)
Setup on Skillcast
The Skillcast side of the setup is commonly completed by Skillcast and therefore may not be relevant for all implementations. In this case, skip to "Setup" below.
External Connection
Go to Management Console > Configuration > External connections
Connection: Add new connection
Type: Client Auth
Name: (Any)
Domain: (Select the Relevant domain)
Click Add Connection
Update the following:
Check single sign-on
Endpoint: (Client provided URL)
Secret: (Agreed upon secret/token)
Click Update connection
Domain setup on Skillcast
Go to Management Console > Configuration > Domains
Find the relevant domain
Check the Default Domain and click Update domain (Only if this is the first ClientAuth install)
Select Single sign-on in the right-hand nav
Choose the previously created connection
Set User identifier to the identifier agreed upon, i.e. UserID/Username/Email
Setup
Provide the following information to Skillcast:
Endpoint - The URL of your custom authentication endpoint that Skillcast will call to request details of the currently logged-in user of the calling system
Secret - A passphrase that will be used as a seed to hash data that is passed back and forth
Process
The end user is forwarded to the following URL from the client system to initiate the process:
https://[clientID].e-learningportal.com/?intentToken=[a-zA-Z0-9-]
intentToken: is an alpha-numeric string, ideally a unique identifier, generated by the client itself and associated with the currently logged-in user.
Once received, Skillcast will make a GET http request to the given endpoint with the following URL parameters:
intentToken - Returning the intentToken that the client sent
intentCheck - A Skillcast-generated unique 35-character hexadecimal string consisting of the following pattern: 8-4-4-16
intent - A SHA-256 hashed data consisting of the concatenated string in order: secret intentToken - This would be validated by the endpoint
If Skillcast receives an intentToken of abc123 and the agreed secret was ThisIsASecretString, then the following string would be hashed: ThisIsASecretStringabc123
Skillcast will expect the following response:
{
"userId": "...",
"intentcheck": "...", "redirectId": "...",
"redirectType": "..."
}userId - The id of the user in the calling system that is related to the initial intentToken from the client, matching the unique attribute in Skillcast. This could be an internal ID, employee ID, or email address
intentcheck - A SHA-256 hashed data consisting of the concatenated string in order: secretintentCheck
If the client receives an intentcheck of xyz789 and the agreed secret was ThisIsASecretString, then the following string would be hashed: ThisIsASecretStringxyz789
redirectId - The ID of the Skillcast entity that the user is to be redirected to
redirectType - The type of entity that the user is being redirected to, all Skillcast IDs:
* lp - Learning Path
* lpgId – Category
* scoId - Module/policy
Skillcast will then validate the response by checking the intentcheck variable, checking if the user exists, and then either redirect to the given entity or show the Skillcast user homepage.
If the response does not validate, then the end user is redirected to the Skillcast login page. This scenario could be any of the following:
Connection error to the client endpoint
Client validation of intent fails
Skillcast validation of intentcheck fails
Incorrect JSON structure of client response to Skillcast
If you experience any issues, select "Contact Support" by clicking the Info icon on your portal.