Limiting access to documentation is a usual practice for companies who provide SaaS (software-as-a-service) products. This may sound illogical because public documentation like user guides, online manuals, and help docs enhance the product’s usability and popularity.
Still, certain documents are meant for internal use only. These are SOPs (standard operating procedures), employee handbooks, company policies, etc. Besides, there is product-specific technical documentation intended for developers (like SDK and API documentation), marketers (like MRDs and PRDs), technical/copywriters, and translators. Such documentation can be called “back-end” as compared to the “front-end” docs mentioned above (user guides, manuals, etc.).
It is clear that access should be limited for back-end documentation so that users or potential customers can see only the ‘façade’ or result of your work. This blog will explain how to configure the authentication process so that your trade secrets remain confidential.
Understanding the Requirements
There are different scenarios when restricted access to documentation becomes necessary. For example, when users encounter a restricted manual in your documentation portal, they will be redirected to the login page.
However, you have the flexibility to grant access to specific individual users or entire categories (such as reviewers, translators, or testers). You can decide which categories of users will be allowed to view or modify the information.
Another option is to provide access to documentation to all authenticated users of your product. In this case, they will automatically gain access to your documentation. In fact, there are numerous options and scenarios to consider. You can grant access to commercial version users or exclusively to beta-testers, depending on your specific needs.
Indirectly, authentication can provide you with more specific statistics. When users authenticate to read a document, you will be able to track who exactly has viewed the topic. Having this information enables you to better understand the interests of your target audience and improve documentation for users from different segments. It also allows you to restrict access to or archive the documentation that is not in demand.
Choosing ClickHelp as Your Documentation Platform
ClickHelp is an online documentation management platform that operates on single-sourcing and content reuse principles. It provides a comfortable and highly efficient environment for creating, reviewing, editing, localizing, and translating technical documentation.
One of its most outstanding features is its robust access control capabilities. ClickHelp offers various scenarios for managing access, and the most obvious options include:
- Configuring each user account individually. This approach is ideal when dealing with a relatively small target audience. An individual approach is effective when you have enough time to handle each account separately.
- Assigning user roles for groups of users. By grouping users together, you can streamline the process and grant access permissions to entire groups at once, thereby saving time.
- Single Sign-On (SSO). With SSO, users can access both your product and your portal using unified credentials, simplifying the login process and enhancing user experience.
- Tokens. Tokens are one-time passwords with limited validity periods (typically one login session). Implementing tokens can add an extra layer of security to the authentication process.
These authentication features will save you time and make administrating your portal easier.
Implementing User Authentication
User authentication is a powerful tool for access control. It enables you to ensure data privacy by defining permissions for users and authorizing specific groups, such as customers, technical writers, stakeholders, and others.
ClickHelp offers a range of features allowing to easily implement user authentication in your documentation portal. Let’s take a closer look at the features mentioned in the section above.
Customizing each user account separately. In ClickHelp, you can quickly and easily create password-protected documents. Each user with an account in your portal will have access permissions that can be set and modified by the portal administrator. Putting it simply, you can specify which documents a user can view and which ones are restricted.
Allocating user roles to user groups. ClickHelp enables you to centrally set access permissions, which is particularly convenient when dealing with a large number of users. Instead of managing each user account individually, you can assign roles to groups of users and set access permissions for those groups collectively. This ensures that all members of a group have identical access to your documentation.
Access with Single Sign-On (SSO). Another way to optimize the process is to integrate access to the ClickHelp documentation portal with access to your product using SSO. When a new user registers, your system automatically creates a new user account in the documentation portal. This grants new users access to documentation automatically once they start using your product. This solution makes the whole process user-friendly, as users will not have to create two separate credentials for the product and the documentation portal.
Security through tokens. If you are not yet prepared to use SSO, ClickHelp offers an alternative option with login tokens. Implementing this technology is straightforward. Your portal will include links with specific parameters – tokens. These tokens inform the portal that a particular user can access the document. A token is a one-time password that can be valid for a certain period, for example, one login session. A validity period makes tokens very secure.
Defining User Roles and Permissions
Controlling user roles and permissions is a crucial aspect of the documentation management process. ClickHelp provides role-based access control, allowing you to define roles and assign appropriate permissions.
Permissions refer to the actions users can perform in the ClickHelp portal. For example, there are Power Readers (PRs) who have only one permission (or ‘power’) — to view restricted publications. They can access password-protected documentation but are unable to enter the authoring environment. It means that they cannot see private publications, edit documents, or add comments.
On the other hand, Contributors have more diverse permissions. They can be Correctors, who simply edit topics, or Administrators with full system access.
Contributors are internal users who can interact with the content available in the portal and create new content. They can view unpublished projects, adjust settings, and more. To understand the specific capabilities of each Contributor Role, the portal's help documentation includes a comprehensive Roles and Permission Matrix detailing their respective permissions.
Configuring Access Restrictions in ClickHelp
Configuring access restrictions within ClickHelp is a straightforward process. To start with, ClickHelp user access is protected by login, forming the starting point of access management.
Next, you can manage user permissions by adjusting their privileges, ranging from minimal to maximum. For example, with contributor security roles, you can specify who can manage portal settings, publish or update content, and edit the content.
What’s more, you can use the SSO system, which integrates access to your ClickHelp portal with your product or company portal.
ClickHelp supports the OpenID Connect technology. You can easily configure SSO connections to Microsoft Azure AD, Salesforce, Google, or your custom authentication endpoint.
Besides the ‘macro’-level of control, there is also a ‘micro’-level. In ClickHelp, you can make specific sections of documentation invisible depending on the context. This is achieved through the use of conditional blocks, variables, and snippets.
To illustrate the process of creating access restrictions, consider the example of developing a restricted user manual:
- Begin by clicking the Publish button below the project name designated for publication.
- A publishing wizard will open. On step 1 of the wizard, set the visibility level to Restricted. This ensures that the document will be visible solely to Contributors and Power Readers.
- After that, follow the subsequent steps in the wizard.
As you can see, configuring permissions in ClickHelp is easy. To learn more about the procedure, read the Help documentation available in the ClickHelp portal.
Designing User Interface and Access Controls
As mentioned earlier, ClickHelp has two user types: Contributors and Power Readers. In your documentation portal in ClickHelp, you can have as many Contributor accounts as needed. However, the number of active users is limited by your license.
At the same time, it is unnecessary to permanently remove unused accounts. Instead, you can simply disable them and revisit them later if required. As compared to contributors, the number of active Power Readers is not limited.
The assigning of roles impacts the user interface, causing changes in the appearance of the workplace due to certain projects and documents being restricted.
Testing and Ensuring Security
To ensure security, the ClickHelp portal utilizes an authentication cookie that is set in the users’ web browsers. This cookie remains valid for 48 hours. It means that a session has an expiration time of 48 hours. After that, the user will be automatically logged out. Therefore, when attempting to access a document in the portal after the session has expired, the user will be redirected to the authentication page.
In the event of an expired session, the user will need to obtain an authentication token, and the system will use it to log the visitor back in. Upon successful authentication, the user's browser will receive a new cookie, providing an additional 48 hours of access to the platform.
Ongoing Management and Updates
It is important to regularly review and update user roles and permissions in ClickHelp. As your product gains popularity on the market, the number of users will increase, leading to a growing demand for your documentation. Consequently, more and more users will access your portal.
The system does not impose any limits on the number of accounts you can create for Power Readers (PRs). However, the number of contributors is subject to your license, and there may be a limitation on the number of active contributors in your portal.
Still, it doesn’t mean that you have to delete the inactive accounts. Just disable them and, if necessary, reactivate them again in the future.
Conclusion
Clearly, access control is a fundamental aspect of documentation management. Users must have varying permissions concerning the information stored in your portal. This is important because the value and purpose of the information can differ significantly. Some publications a meant for public use, others require strict confidentiality.
To ensure effective access control, choose a documentation management tool that allows you to execute access control procedures quickly and effectively. ClickHelp is a convenient online documentation management platform that offers a simple and transparent way of access control.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices