ClickHelp User Manual

The Token Login Mechanism

ClickHelp User Manual/Portal Management and Administration/Authentication/The Token Login Mechanism

ClickHelp provides various methods to control who can access the content in your portal. However, in most cases, 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:

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
When using links with hashbangs, the token parameter must be inserted before the hashbang, like this:

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 already authenticated, 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 may not be enough for the end-user to open the first link to the documentation.

To learn more about token expiration, read the following topic: Session Control and Expiration.