JSON Web Token Authentication

LAST UPDATED: MARCH 28, 2025

JSON Web Token (JWT) enables authentication by encoding claims within a digitally signed token, ensuring secure validation of user identity and permissions. Follow the steps in this article to send a JWT-encoded request in Postman.

Prerequisites

• Postman

• A JWT encoding tool, such as jwt.io or an external script.

• JWT webhook authentication enabled

How to Enable JWT Webhook Authentication on D3 vSOC

1. Open the Web Config settings.

   

   1. Click on the Configuration navigational link.

   2. Click on the Application Settings icon.

   3. Click on the Web Config option.

2. Set the EnableEnhanceWebhookAuthentication radio option to True.

3. Click on the Save button.

• Ability to set up D3 webhook keys

Setting Up JWT Remote Command Keys for Data Ingestion

1. Establish a connection between D3 vSOC and the integration. This connection must be active and display a status, as shown in the image below.

   

   Ensure the connection is associated with a specific site. The connection in the screenshot is linked to the Security Operations site.

2. Select the event/incident intake command, such as Fetch Event.

   

3. Ensure that Webhook Authentication is toggled on.

• On:

• Off:

From this point, users can configure their JWT through either the Integrations module or the Data Ingestion module.

Setting Up JWT from the Integrations Module

1. Click on the JSON Web Token (JWT) button.

   

2. Set up the JWT within the Setup JWT popup.

   

   1. Click the + button in the INTERNAL SITES or CLIENT SITES section.

   2. Select the Site to be used for the data ingestion job.

   3. Enter a unique Key Name.

   4. Click the Generate button.

The user will see a display similar to the following:

READER NOTE

If users click the + button in the ALL SITES section, then select Shared to All Internal Sites or Shared to All Client Sites for the Site field, the JWT will be shared with all corresponding sites. However, users must still select a specific site for data ingestion.

Setting Up JWT from the Data Ingestion Module

1. Navigate to the Configuration module, then click the Data Ingestion sub-module.

   

2. Click the + button, then select the Webhook option.

   

3. Configure the webhook data source.

   

   1. Select the integration to use, such as Wiz.

   2. Choose the site into which the data will be ingested.

   3. Select the JWT checkbox in the Authentication Method section.

   4. Click the + button to add a new JWT.

4. Enter a unique Key Name, then click the Generate button.

   

The user will see a display similar to the following:

Setting Up JWT Remote Command Keys for Integration Commands

1. Establish a connection between D3 vSOC and the integration. This connection must be active and display a status, as shown in the image above.

   

   Ensure the connection is associated with a specific site. The connection in the screenshot is linked to the Security Operations site.

2. Select the desired integration command.

   

   For demonstration purposes, the Get Computers command will be used.

3. Ensure that Webhook Authentication is toggled on, then click on the JSON Web Token (JWT) button.

   

• On:

• Off:

4. Set up the JWT in the Generate Remote Command Key pop-up.

   

   1. Click on the + button within the Setup JWT popup.

   2. Select the connection created from step 1. The connection should have the name of the site it is linked to in parentheses.

   3. Enter a unique Key Name.

   4. Click on the Generate button.

The user will see a display similar to the following:

Setting Up JWT Remote Command Keys for Utility Commands

1. Ensure that Webhook Authentication is toggled on, then click on the JSON Web Token (JWT) button.

   

• On:

• Off:

2. Set up the JWT in the Generate Remote Command Key pop-up.

   

   1. Click on the + button within the Setup JWT popup.

   2. Enter a unique Key Name.

   3. Click on the Generate button

The user will see a display similar to the following:

READER NOTE

Each JWT Remote Command Key will have a unique Secret Key value used in generating the JWT encoding.

Setting Up and Sending a JWT-Encoded Request: Data Ingestion

Users can send an JWT-authenticated request to push data into D3 using the webhook data ingestion method to create D3 events.

READER NOTE

For clarity, the example below demonstrates how to send an JWT-authenticated request using Postman. However, this approach is intended only for testing purposes. In typical use cases, webhook ingestion is handled automatically through external software or scripts.

1. Copy the request URL in vSOC.

   

2. In Postman, set the HTTP request method to POST, then paste the request URL in the designated field.

   

3. In vSOC, copy the request header key.

   

4. In Postman, click on the Headers tab, then paste the request header key under the Key column.

   

5. In vSOC, copy the object from the Header section.

   

6. In jwt.io, click the JWT Encoder tab, then paste the object into the HEADER field.

   

7. Remove the placeholder content within the curly braces to make the payload an empty object.

   

8. In vSOC, copy the Secret Key.

   

9. In jwt.io, paste the Secret Key, then copy the JSON web token.

   

10. In Postman, paste in the token under the Value column for the d3jwt key.

    

11. Select the Body tab, choose the raw option, then paste sample request body data.

    

READER NOTE*

The request body data is derived from the raw sample available under the Outputs > Raw Data tab of Wiz’s Fetch Event command. Any D3 events created using this data are not real security events.

Users can treat this as a template for structuring data pushed into D3 to create D3 events, specifically for Wiz’s Fetch Event command. For example, this demonstrates that the main event JSON path is data.nodes, which means that event data from Wiz should be within that path.

12. Click the Send button to send the request.

    

RESULT

If the request is successful and the conditions for event creation are met, the ingested event can be viewed in D3 by navigating to Configuration > Data Ingestion and selecting the relevant webhook data ingestion job card (i.e., Webhook | Site: Security Operations within the Wiz accordion).

Users can view the ingestion details by clicking the corresponding timestamp.

Setting Up and Sending a JWT-Encoded Request: Remote Command

1. Copy the request URL in vSOC.

   

2. In Postman, set the HTTP request method to POST, then paste the request URL in the designated field.

   

3. In vSOC, copy the request header key.

   

4. In Postman, click on the Headers tab, then paste the request header key under the Key column.

   

5. In vSOC, copy the object from the Header section.

   

6. In jwt.io, click the JWT Encoder tab, then paste the object into the HEADER field.

   

7. In vSOC, copy the payload.

   

8. In jwt.io, paste the payload into the PAYLOAD field.

   

9. Populate the PAYLOAD fields. For this demonstration, the completed payload is as follows:

   

READER NOTE*

• Ensure the value of the payload’s Username field matches the username of the user being granted access to the remote command key (user10 in this case).

  

  • By default, the creator is the only individual with access.

• All payload data are case-sensitive.

10. In vSOC, copy the Secret Key.

    

11. In jwt.io, paste the Secret Key.

    

12. In vSOC, copy the request body sample data.

    

13. In Postman, select the Body tab, choose the raw option, then paste the sample request body data.

    

14. Modify the highlighted request body values to match the payload precisely.

    

15. In jwt.io, copy the encoded token.

    

16. In Postman, click on the Headers tab, paste in the token, then send the request.

    

RESULT

A successful request will have the 200 OK status and valid return data with no errors.

Encoding Using an External Script

Users who prefer to perform JWT encoding outside a browser may do so using a script, provided they have access to the following:

• A code editor, such as VS Code

• Python installed on their device

• Pip for installing Python packages

Use the following instructions to perform JWT encoding in a script.

1. Create a new file in VS Code to contain the script.

2. Copy and paste the code below in the file.

   PY

   import jwt  # Import the PyJWT library for encoding JSON Web Tokens
   
   # Define the payload – this is the data that must be included in the token
   payload = {
       "Timestamp": "",
       "Site": "",
       "Username": ""
   }
   
   # Define the JWT header – this specifies the algorithm and token type
   jwt_header = {
       "alg": "HS256",
       "kid": "",
       "typ": "JWT"
   }
   
   # Secret key used to sign the token – must be known to both sender and receiver
   secret_key = "a-string-secret-at-least-256-bits-long"
   
   # Generate the JWT using the payload, secret key, and algorithm
   jwt_token = jwt.encode(payload, secret_key, algorithm="HS256", headers=jwt_header)
   
   # Convert to string if the result is in bytes (needed for older versions of PyJWT)
   if isinstance(jwt_token, bytes):
       jwt_token = jwt_token.decode('utf-8')
   
   # Output the signed JWT string
   print(jwt_token)

3. Open a new terminal and paste the command below to use pip to install the pyjwt package required for JWT encoding:

   CODE

   pip install pyjwt

   Refer to PyJWT 2.10.1 documentation for more information.

4. Copy the JWT header in vSOC and replace the jwt_header object in the script.

   

5. Copy the payload from vSOC and replace the payload object in the script.

   

6. Update the payload with the correct site and username to match the request body in Postman.

   

   The username in both the request body and payload must match the user being granted access to the remote command key.

   

7. (Optional) Adjust the value of the Timestamp field in the script.

   

8. Copy the secret key from vSOC and replace the secret_key value in the script.

   

9. Click the down arrow beside the button in VS Code and select the Run Python File in Dedicated Terminal option.

   

10. Once executed, copy the encoded JWT value printed in the terminal and paste it into Postman as the value for the d3jwt header key.