How to Use the Command 'jwt' (with Examples)

The jwt command-line tool is designed to work with JSON Web Tokens (JWTs), a compact and URL-safe means of representing claims transferred between two parties. It provides functionality to decode, encode, and manipulate JWTs with various encryption algorithms such as HS256, HS384, HS512, RS256, RS384, RS512, ES256, and ES384. The tool is especially useful for developers and system administrators who need to implement or debug authentication systems that rely on JWTs. More information can be found on the project’s GitHub page .

Use Case 1: Decode a JWT

Code:

jwt decode jwt_string

Motivation:

You may want to decode a JWT to inspect its contents without needing to verify or validate the cryptographic integrity. This is particularly useful for debugging purposes or when you need to understand the claims and data encapsulated in the token.

Explanation:

• jwt: This is the command-line tool used to interact with JSON Web Tokens.
• decode: This sub-command tells the tool that you want to decode a JWT.
• jwt_string: This is the input string representing the JWT that you want to decode. Typically, a JWT consists of three base64url-encoded components separated by dots: the header, payload, and signature.

Example Output:

{
  "header": {
    "alg": "HS256",
    "typ": "JWT"
  },
  "payload": {
    "sub": "1234567890",
    "name": "John Doe",
    "iat": 1516239022
  },
  "signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Use Case 2: Decode a JWT as a JSON String

Code:

jwt decode -j jwt_string

Motivation:

Sometimes, it is preferable to receive the decoded JWT in a standardized JSON format, particularly if you need to programmatically process the output or integrate it into another tool or script.

Explanation:

• jwt: The command-line tool for JWT manipulation.
• decode: The sub-command for decoding the JWT.
• -j: This flag specifies that the output should be formatted as a JSON string. It provides structured data, which is more machine-readable.
• jwt_string: This is the JWT that you wish to decode.

Example Output:

{
  "header": "{\"alg\":\"HS256\",\"typ\":\"JWT\"}",
  "payload": "{\"sub\":\"1234567890\",\"name\":\"John Doe\",\"iat\":1516239022}",
  "signature": "SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
}

Use Case 3: Encode a JSON String to a JWT

Code:

jwt encode --alg HS256 --secret 1234567890 'json_string'

Motivation:

Encoding a JSON string into a JWT is useful when you need to create a token for authentication or authorization purposes. You can encapsulate claims or user data within a token, which can then be securely transmitted and used to verify identity or permissions.

Explanation:

• jwt: The tool used for encoding/decoding JWTs.
• encode: The sub-command to encode data into a JWT.
• --alg HS256: This option specifies the algorithm used for the signing process, in this case, HMAC using the SHA-256 hash function.
• --secret 1234567890: This specifies the secret used to sign the JWT. It is crucial for verifying the integrity of the token.
• 'json_string': This is the JSON payload to encode. It contains the claims or data intended for inclusion in the JWT.

Example Output:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJuYW1lIjoiSm9obiBEb2UiLCJzdWIiOiIxMjM0NTY3ODkwIiwiaWF0IjoxNTE2MjM5MDIyfQ.DR5YfWInXg_pNwM-EhKz1l_E6Vw0FhxNFuAnkq5EUIw

Use Case 4: Encode Key Pair Payload to JWT

Code:

jwt encode --alg HS256 --secret 1234567890 -P key=value

Motivation:

This use case is valuable when you need to directly encode key-value pairs into a JWT without the need to construct a JSON string manually. It simplifies the encoding process and is especially useful for quick, one-off token generation.

Explanation:

• jwt: The command-line utility for working with JWTs.
• encode: Indicates that the data will be encoded into a JWT.
• --alg HS256: Chooses HMAC-SHA256 as the algorithm for creating the token signature.
• --secret 1234567890: Specifies the secret used in the HMAC process for creating a signature.
• -P key=value: This option allows you to input key-value pairs directly, which are then assembled into the payload of the JWT.

Example Output:

eyJhbGciOiAiSFMyNTYiLCAidHlwIjogIkpXVCJ9.eyJrZXkiOiAidmFsdWUifQ.xHGkRCcJMyvmHVHSdxds12pBBjF0Z5YTJ7pDr-IYaEo

Conclusion

The jwt command-line tool is a versatile utility that simplifies the process of encoding and decoding JSON Web Tokens. Whether you need to inspect the contents of a JWT, generate new tokens securely, or integrate token handling into scripts, the tool provides robust functionality to meet a wide range of use cases. With support for various signing algorithms and output formats, it is an essential component for developers dealing with modern authentication and authorization systems.