Session Linking Authentication

Overview

Integrate JWT authentication with DocsHound to secure your published documentation.

Example

A demo guide and application showcasing the authentication flow:

https://test-auth.docshound.ai/

To log in use the following credentials:

username: user@example.com

password: password

Set Up JWT Authentication

Guide configuration

Reach out to DocsHound team to set up authentication configuration for your guide.

You will to provide an authentication URL, where DocsHound will redirect unauthenticated users to verify their credentials.

DocsHound will provide an authentication secret (DOCSHOUND_AUTH_SECRET) that will be used to sign tokens and confirm user authenticated status.

Create Authentication Sub page

To integrate JWT authentication with DocsHound, you need to create a sub page in your application, ie: https://yourapplication.com/auth/docshound.

This sub page will accept an authentication challenge parameter, and upon verifying user authenticated status, redirect the user back to published guide, with an additional URL search parameter with signed token.

Sign JWT Token

Using the provided DOCSHOUND_AUTH_SECRETcreate and sign a JWT token to confirm the user identity.

For Single Page applications, this step needs to run on backend to ensure thatDOCSHOUND_AUTH_SECRETis exposed in the frontend code.

Redirect the user back to published guide

Once the authentication is successful, and the JWT token is available, the user should be redirected back to the published guide URL with a signed JWT token attached in the URL search parameters.

Example redirect URL:

https://test-auth.docshound.ai?dh-auth-token=<GENERATED JWT TOKEN>&challenge=<CHALLENGE PARAM>

Replace <GENERATED JWT TOKEN> with the JWT token, and <CHALLENGE PARAM> with the initial challenge search param received when DocsHound redirects to the Authentication Sub page.

Authentication Flow

User Access Attempt

When a user tries to access the published documentation, they are redirected to the configured Guide authentication page URL on your application.

Verify user session

The verification_url can be any URL within your application that is capable of verifying a user session and redirecting them back to the DocsHound published guide.

On the verification URL page, the system ascertains whether the user is logged in. If the user is logged in, the verification page will run a process to sign DocsHound JWT token. This token is signed using a DOCSHOUND_AUTH_SECRET provided by DocsHound for your guide. In case the user is not logged in, they are redirected to the login page.

Once the JWT token is signed, the verification page will redirect the user back to the published guide URL. The signed token and the original challenge query parameter are appended to this URL. This redirection ensures that the user can now access the secure documentation.

URL params:

dh-auth-token - the signed JWT token

challenge - the inital challenge recevied

Security Considerations

Protect Secrets

It is important to protect your DOCSHOUND_AUTH_SECRET and ensure it is never exposed in client-side code. Storing this secret in your backend prevents unauthorized access and protects your users' data. If the DOCSHOUND_AUTH_SECRET were to be compromised, it could lead to unauthorized access to your secured documentation.

To safeguard your DOCSHOUND_AUTH_SECRET, never hard-code the secret directly in your source files.

Ensure Parameter Matching

The challenge parameter must match during token validation to ensure the user session is correctly established. When DocsHound receives the signed token and the challenge parameter, it verifies the parameter to confirm the user intent comes from the correct session.