Share:
ClickHelp Documentation

The Token Login Mechanism

 

ClickHelp provides various methods to control who can access the content in your portal. However, often, you don't want to bother your users with an additional set of credentials just to let them access documentation. And you don't want the documentation to be accessible by everyone either.

So you need to have a way to authenticate users of your application or service in your ClickHelp portal without making them deal with the portal's login process. The most secure way to do this is to use the SSO technology, and specifically, the OpenID Connect mechanism to authenticate users by your service native accounts.

It may be impossible in some situations, or you may not have the SSO implementation on your end. For example, if you are working with a desktop application that does not require users to log in, and you don't have an authentication endpoint on the Internet, the SSO approach cannot be used. In such cases, it is possible to use another approach - login tokens.

Login Tokens

Your application can generate a login token for a generic Power Reader user by calling the corresponding API method and then provide links to the documentation with this token included in the URL. Here is what a link with a token looks like:
https://myportal.clickhelp.co/articles/my-publication/my-topic?t=eyJ0eXAiOiJKV1QiLC

As you can see, there is just one additional element in this link - the "t" parameter, having a login token as a value. When such a link is used, your ClickHelp portal will validate the token and authenticate the reader automatically. This way, you can give a link to a password-protected user guide - including a login token will allow the reader to access this topic without entering a password.

Login tokens are disposable and, by default, every token can be used only once. Optionally, it is possible to create multi-use tokens that can be used multiple times. Also, for security reasons, every token has an expiry date that is set through a special parameter of the token creation API method. This means that your application will need to generate new login tokens for documentation links from time to time.

Supported Link Types

These are the types of links that support tokens in ClickHelp:

  • Direct links to topics
  • Smart links
  • Links to publications
  • Links with a hashbang
Note
When using links with hashbangs, the token parameter must be inserted before the hashbang, like this:
/articles/?t=12345#!my-project/my-topic. 

Token Expiration

When someone opens a link with a token in it, ClickHelp identifies the related Power Reader user (for which the token was generated) and silently authenticates the user in the current browser session. If the token is created as a one-time token, it is getting consumed and becomes invalid for future use - the tokens are disposable. Login tokens become invalid in two cases:

  • When its expiration date is due.
  • Right after a one-time token is used for authentication.

Note that a multi-use login token can be used more than once. If a user is already authenticated in a web browser session, adding an expired or used one-time token to a topic link won't produce any errors - the token will be ignored.

If a valid unexpired one-time token is used and a user is authenticated already, the token is ignored and not disposed of. The recommended approach is to generate a new token every time you need to provide a user with a link. You can also get a token when your application is launched, and use this token in all links. In this case, it could be a good idea to specify a more extended expiration period for the token, because the default 30 minutes can be not enough for the end-user to open the first link to the documentation.

Session Expiration

When a user is authenticated in ClickHelp with a token, with SSO, or by using the ClickHelp Login page, they get an authentication cookie set in their web browser. This cookie is valid for 48 hours and will be automatically renewed for another 48 hours if the user keeps working with the documentation portal. If a user does not access the portal for 48 hours or more, the cookie expires - next time the user tries to open a protected guide, the authentication process will be triggered. This may be the SSO authentication sequence or the ClickHelp Login page - this is based on the portal SSO configuration.

In the situation of an expired session, If the link used by the visitor contains a valid login token, the system will use this token to authenticate the visitor. The visitor's browser gets a new authentication cookie that will be valid for 48 hours.