JWT authentication

Note: This feature is available in Enterprise, AWS, Team editions only.

Table of contents

• Overview
• Configuration steps
  • Step 1: Enabling JWT authentication
  • Step 2: Create JWT
  • Step 3: Adding an Identity Provider
  • Step 4: Insert JWT in browser cookies
  • Step 5: Logging in

Overview

In CloudBeaver, you can use JWT (JSON Web Tokens) authentication to securely exchange claims between the client and the server. This method allows you to authenticate using JWTs, which the server validates to grant access to its resources. This article outlines the basic settings necessary for JWT authentication in CloudBeaver.

For more information on JWT standards, see JWT official documentation

Configuration steps

Step 1: Enabling JWT authentication

1. As an administrator, navigate to the Settings -> Server configuration.

2. Locate the JWT option and activate this setting to allow JWT authentication.

   

3. Save changes.

Step 2: Create JWT

1. Create the payload of your JWT. Use the template below and modify its values according to your needs:

   {
     "email": "[email protected]",
     "firstName": "Name",
     "lastName": "Surname",
     "team": "user"
   }

   Tip: For more information on teams, see Teams article.

   Alongside the payload, create a sufficiently large and secure secret key. Here is an example of a robust secret key:

   8Sa8sdfkj980stCLyV6XICnI2TLoFcgzwtwgX94joMiaMnB8PTft6EDBXBqJpiIieeg7b26b9oiXKUx0Os9i1lmGDi1hpB2eOIiVuLQNxAZ9CMdSctnchzprIjgnKOeKaYHjUVZpNlnckxcOzzix4hLPsdfsdfsdffq2WyFNJ2Juw1OnEedA8MbgzSyfqbL0s02gXHLiRdakxbhsWg6NVvUMMTcsDLQZDxAzvLPD0MtKEIy6Vn8kSC0icog5Q187Uw0swlxNNAnt82cLcBaOwoHUFUOjZet3Rdu
   

2. Generate your JWT.

   Tip: You can use jwt.io. Enter the payload data in the PAYLOAD:DATA section and your secret key in the VERIFY SIGNATURE section. Jwt.io will automatically create the encoded JWT for you.

   

Step 3: Adding an Identity Provider

1. As an administrator, navigate to Settings -> Identity Providers.

2. Click on the + Add button.

3. Fill in the following fields:

   

   Field	Description
   Provider	Select JWT from the dropdown menu.
   ID	Enter a unique identifier for the configuration.
   Configuration name	Enter a descriptive name for this configuration.
   Description	Provide a brief description of this identity provider configuration.
   Icon URL	Enter the URL of an icon to represent this provider.
   Disabled	Leave unchecked to enable this identity provider.
   Cookie Name	Set the name of the cookie to store the JWT.
   Email Attribute	Specify the custom attribute that represents the user's email. Default value: "email".
   Team Attribute	Specify the custom attribute that represents the user's team. Default value: "team".
   First Name Attribute	Specify the custom attribute that represents the user's first name. Default value: "firstName".
   Last Name Attribute	Specify the custom attribute that represents the user's last name. Default value: "lastName".
   Name of an AWS role claim attribute	Use this attribute to identify the AWS IAM role claim within the JWT.
   Jwk token	Enable option for decrypting incoming tokens.
   Public Key	Enter the public key for validating the JWT signature.
   Secret Key	Enter the secret key used in Step 2.
   Use additional header	Enable if additional headers for the JWT authentication requests.
   Team Header	Set the custom header to be used for the team verification.
   Decrypt RSA256 Header	Enable if RSA256 decryption of the header is required.
   Public Key RSA	Enter the RSA public key for additional security checks.

   Tip: You can insert the Public key with the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- headers, or without them.

4. Click on the Create button.

Step 4: Insert JWT in browser cookies

You need to insert the JWT into your browser cookies at this step. Below is a straightforward method to achieve this:

1. Access the developer tools in your web browser. This is generally achieved by right-clicking on a web page and selecting Inspect or by using shortcuts like F12.

2. In the developer tools, go to the Application tab. Here, locate the Cookies section under the Storage header on the left. This section allows you to view and manipulate cookies related to the current website.

3. Add your cookie:

   • Click on the Add new button in the cookies panel.
   • In the Name field, enter the Cookie Name, used in Step 3.
   • In the Value field, paste your JWT token, generated in Step 2.

4. After inputting your cookie's name and value, save the changes.

Step 5: Logging in

By entering the JWT token into the cookie, users can automatically authenticate upon visiting the CloudBeaver login page. This method eliminates the need for refreshing the page or manually logging in each time, providing a seamless access experience to the application.