Login Through Third-party Software
ClickHelp allows creating password-protected documentation. To access this type of content, a reader must have a special Power Reader account.
When integrating ClickHelp with your web or desktop application, you may want to simplify the process for your readers and avoid creating a Power Reader account for every user. You would normally expect all users of your application to have access to the documentation automatically, and all other visitors not to have this access at all. This approach is possible to implement with Single Sign-On (SSO) or with Login Tokens. Let's consider the latter option - disposable login tokens.
So, the goal is to somehow authenticate a user of your application in your documentation portal without asking for login and password. The fact that the user has access to your application UI is considered enough for documentation access authorization. This means that your application will need to "tell" your documentation portal that a visitor is authorized to access the user guides. Technically, this means that your application needs to get a Login Token from your documentation site and make sure the users have this token in every documentation link they click in your UI.
Let's consider this authentication approach step by step to understand what happens when a visitor tries to access a password-protected user guide.
Authentication Process
- The reader clicks a documentation link.
- Since the topic is inside a restricted manual, the system redirects the user to the ClickHelp Login page.
- If the link has a Token (which is not the case if the link was simply shared by a colleague), the normal Token Authentication process happens, and the user is redirected to the topic.
- If the link has no Token (which is the case when a user shares a link to ClickHelp topic), a custom script checks if the link has a special parameter that indicates that this user is an contributor. If the user is an contributor, nothing happens, and the user stays on the Login Page to proceed with the login process normally.
- If the link has no special "user type" parameter, the Login page automatically redirects the reader to a special page in your SaaS application, passing the target topic URL as a URL parameter to the third-party software.
- This page then checks the user authorization in the third-party software.
-
If the user is authorized in the third-party software, the page makes an API
call to retrieve a login token for the current user.
-
The third-party software creates a URL to the target topic with the login
token included as a parameter and redirects the user to that URL.
-
ClickHelp verifies the provided token.
- If the token is valid, the system logs the user in as a Power Reader, and the topic is displayed.
- If the token is not valid (expired, incorrect), or if the user does not have access to the requested topic based on the permission configuration, ClickHelp shows the "Access Denied" page.
Changes Required
This workflow will require two changes: in your ClickHelp portal login page and in your application.
ClickHelp Login page
In the ClickHelp portal branding script, you need to implement a function that will do the following:
- Handle the window onload event;
- Check if the current page is the Login page;
- Check if the URL contains a special parameter that avoids auto-redirect (so your contributors are not logged in through the third-party application) - you can name the parameter the way you want;
- If the parameter is not there, then extract the "ReturnUrl" parameter value from the URL (this will be the URL-encoded topic URL the reader tried to access);
- Perform a script-based redirect to the third-party software and pass the value of the ReturnUrl parameter to the page.
Your App Authentication Page
Implement a URL parameter that will accept the target topic URL that the Login page passes in its redirect. Implement the logic that will perform two operations:
- Make an API call to get a login token from ClickHelp;
- Perform a redirect to the topic whose URL was passed to the third-party software page as a parameter, and include the login token to the URL.