PyJWT RSA Helper

jwt-rsa is a versatile command-line utility and Python library for managing JSON Web Tokens (JWT) using RSA cryptography. It enables you to generate RSA key pairs, issue and verify JWTs, convert keys between various formats, and perform comprehensive key management tasks with ease.

Installation

Ensure you have Python 3.10 or higher installed. You can install pyjwt-rsa using pip:

pip install pyjwt-rsa

Python Library

pyjwt-rsa can also be used as a Python library for integrating JWT and RSA key management into your Python applications.

JWT Factory Function

The JWT factory function creates a JWTSigner (when given a private key) or a JWTDecoder (when given a public key).

Importing and Basic Usage

from jwt_rsa import JWT, generate_rsa

# Generate RSA key pair
key_pair = generate_rsa(bits=2048)

# Create a JWTSigner from a private key (can encode and decode)
jwt = JWT(key=key_pair.private)

# Encode a JWT token
token = jwt.encode(foo='bar')

# Decode a JWT token
claims = jwt.decode(token)
print(claims)

# Create a JWTDecoder from a public key (can only decode)
decoder = JWT(key=key_pair.public)
claims = decoder.decode(token)

Handling Expiration and Not Before Claims

# Encode with custom expiration and nbf
token = jwt.encode(foo='bar', expired=3600, nbf=0)

# Decode without verification
claims = jwt.decode(token, verify=False)
print(claims)

JWTSigner and JWTDecoder

You can also use JWTSigner and JWTDecoder directly:

from jwt_rsa import JWTSigner, JWTDecoder, generate_rsa

key_pair = generate_rsa(bits=2048)

# JWTSigner can encode and decode tokens
signer = JWTSigner(key=key_pair.private, algorithm="RS256")
token = signer.encode(sub="user123", role="admin")

# JWTDecoder can only decode tokens
decoder = JWTDecoder(key=key_pair.public, algorithm="RS256")
claims = decoder.decode(token)

JWKs support

from jwt_rsa.jwks import HTTPSJWKFetcher

jwks = HTTPSJWKFetcher('https://example.com/.well-known/jwks.json')

# Fetch JWKs from a URL
jwks.refresh()

# Decode a token using the appropriate key (selected by kid header)
claims = jwks.decode(token)

RSA Key Management

pyjwt-rsa provides functions to generate, load, and convert RSA keys.

Generating RSA Keys:

from jwt_rsa import generate_rsa

# Generate a 2048-bit RSA key pair
key_pair = generate_rsa(bits=2048)
private_key = key_pair.private
public_key = key_pair.public

Loading RSA Keys:

load_private_key and load_public_key accept a Path, a PEM string, a JWK dict, or a Base64-encoded DER string. The format is detected automatically.

from jwt_rsa import load_private_key, load_public_key
from pathlib import Path

# Load from a file
private_key = load_private_key(Path('./private.pem'))
public_key = load_public_key(Path('./public.pem'))

# Load from a PEM string
private_key = load_private_key("-----BEGIN RSA PRIVATE KEY-----\n...")

# Load from a JWK dict
public_key = load_public_key({"kty": "RSA", "n": "...", "e": "AQAB", ...})

Converting RSA Keys to JWK:

from jwt_rsa import rsa_to_jwk, generate_rsa

private_key, public_key = generate_rsa(bits=2048)

# Convert private key to JWK
private_jwk = rsa_to_jwk(private_key, kid='my-key-id')

# Convert public key to JWK
public_jwk = rsa_to_jwk(public_key, kid='my-key-id')

Command line utility jwt-rsa

jwt-rsa is a versatile command-line utility for managing JSON Web Tokens (JWT) using RSA cryptography. It allows you to generate RSA key pairs, issue and verify JWTs, convert keys between formats, and perform various other key management tasks with ease.

Features

• Generate RSA Key Pairs: Create new RSA public and private keys with customizable parameters.
• Issue JWTs: Generate JWT tokens with configurable claims and expiration.
• Verify JWTs: Parse and verify the authenticity of JWT tokens.
• Key Conversion: Convert keys between PEM, JWK, and Base64 formats.
• Extract Public Keys: Derive the public key from a private key.
• Key Testing: Validate the integrity of RSA key pairs.

Installation

Ensure you have Python 3.10 or higher installed. You can install pyjwt-rsa using pip:

pip install jwt-rsa

Usage

jwt-rsa is operated via the command line with various subcommands to perform different tasks. Below is an overview of the available commands and their options.

Global Options

• -a, --algorithm: Algorithm for JWT keys (RS256, RS384, RS512). Default: RS512.
• --log-level: Logging level (debug, info, warning, error, critical). Default: info.

Time Interval Format

Several commands accept time interval values (e.g., --expired, --nbf). The following formats are supported:

• A plain integer is interpreted as seconds (e.g., 600 = 10 minutes).
• A value with a suffix and optional +/- sign (e.g., +10m, -1h, +30d).
• Supported suffixes: s (seconds), m (minutes), h (hours), d (days), w (weeks), M (months), y (years).
• + means future, - means past relative to the current time.

Commands

keygen

Generate a new RSA key pair.

Usage:

jwt-rsa keygen [options]

Options:

• -b, --bits: Number of bits for the RSA key (default: 2048). Choices: 1024, 2048, 4096, 8192.
• --kid: Key ID. If not provided, one will be generated.
• -a, --algorithm: Algorithm to use (RS256, RS384, RS512). Default: RS512.
• -u, --use: Key usage (sig for signature, enc for encryption). Default: sig.
• -o, --format: Output format (pem, jwk, base64). Default: jwk.
• -r, --raw: Output raw JSON without indentation.
• -k, --save-public: Path to save the public key.
• -K, --save-private: Path to save the private key.
• -f, --force: Overwrite existing keys if they exist.

Examples:

By default jwt-rsa keygen generates keys to the standard output.

$ jwt-rsa keygen -b 1024 -o jwk
Public key in jwk format:
{
 "alg": "RS256",
 "e": "AQAB",
 "kid": "N-ls95OIH-FhdrfM",
 "kty": "RSA",
 "n": "3QHB3jCki6iFYEsYyQ9L9Jmn05bytXYzeaPckyMEdmhti4VPCVI8inec",
 "use": "sig"
}
Private key in jwk format:
{
 "alg": "RS256",
 "d": "...",
 "dp": "...",
 "dq": "...",
 "e": "AQAB",
 "kid": "N-ls95OIH-FhdrfM",
 "kty": "RSA",
 "n": "3QHB3jCki6iFYEsYyQ9L9Jmn05bytXYzeaPckyMEdmhti4VPCVI8inec",
 "p": "...",
 "q": "...",
 "qi": "...",
 "use": "sig"
}

If you want to save the keys to files, you can use the -K/--save-private and -k/--save-public options.

Generate a 4096-bit RSA key pair and save them in PEM format:

$ jwt-rsa keygen -b 4096 -o pem -K /tmp/private.pem -k /tmp/public.pem
Saving public key to /tmp/public.pem in PEM format
Saving private key to /tmp/private.pem in PEM format

Generate shorter version. The public key will be saved in a file with the same name as the private key but with the .pub extension:

$ jwt-rsa keygen -b 4096 -o pem -K /tmp/key
Public key file not specified, saving public key to /tmp/key.pub
Saving public key to /tmp/key.pub in PEM format
Saving private key to /tmp/key in PEM format

testkey

Test the validity of a JWT key pair. Make a round-trip test signing and verifying a random message.

Usage:

jwt-rsa testkey -K PRIVATE_KEY_PATH -k PUBLIC_KEY_PATH

Options:

• -K, --private-key: Path to the private key (required).
• -k, --public-key: Path to the public key (required).

Examples:

Ensure that your RSA key pair is valid:

$ jwt-rsa testkey -K /tmp/key -k /tmp/key.pub
Signing OK
Verifying OK

pubkey

Extract the public key from a private key.

Usage:

jwt-rsa pubkey -K PRIVATE_KEY_PATH [options]

Options:

• -K, --private-key: Path to the private key (required).
• -o, --format: Output format (pem, jwk, base64). Default: jwk.
• -r, --raw: Output raw JSON without indentation.

Examples:

Extract the public key from a private key and save it in Base64 format:

$ jwt-rsa pubkey -K /tmp/key -o base64
MIICCg...EAAQ==

issue

Issue a new JWT token.

Usage:

jwt-rsa issue -K PRIVATE_KEY_PATH [options]

Options:

• -K, --private-key: Path to the private JWT key (required).
• --expired: Token expiration time interval (default: +1M, i.e., 1 month). See Time Interval Format.
• --nbf: "Not Before" claim time interval (default: -1m, i.e., 1 minute in the past). See Time Interval Format.
• -I, --no-interactive: Disable interactive mode. By default, interactive mode is enabled.
• -e, --editor: Editor to use in interactive mode. Defaults to the EDITOR environment variable or vim.

Examples:

Issue a JWT token with default expiration and interactive mode:

jwt-rsa issue -K ./private.pem

By default will be opened the default editor to edit the claims, the format is python dictionary, with comments and pre-filled values:

# This modules functions and constants are available:

#  * DAY = 86400
#  * HOSTNAME = 'localhost'
#  * HOUR = 3600
#  * YEAR = 31536000
#  * datetime = <class 'datetime.datetime'>
#  * format = <built-in function format>
#  * int = <class 'int'>
#  * now = datetime.datetime(2025, 1, 4, 1, 42, 25, 890287)
#  * sum = <built-in function sum>
#  * time = <module 'time' (built-in)>
#  * timestamp = 1735951345
#  * whoami = pwd.struct_passwd(pw_name='example', pw_passwd='********', pw_uid=1000, pw_gid=1000, pw_gecos='Example User')

{
    # === Standard JWT Claims (As per RFC 7519) ===

    # Issuer of the token
    "iss": "{} <{}@{}>".format(whoami.pw_name, whoami.pw_gecos, HOSTNAME),

    # Subject of the token (usually the user ID)
    "sub": "JohnDoe <johndoe@localhost>",

    # Audience for the token
    "aud": "your-audience",

    # Expiration time (Unix timestamp)
    "exp": timestamp + 2678400,

    ...
}

After saving and closing the editor, the token will be issued and printed to the stdout.

If you want to disable interactive mode, you can use the -I/--no-interactive option:

$ echo '{"foo": "bar"}' | jwt-rsa issue -K /tmp/key -I --expired 3600
eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIiLCJleHAiOjE3Mzg2MzAwNDcsIm5iZiI6MTczNTk1MTYyN30.HRCQ

In non interactive mode, the input must be a JSON object with the claims to issue the token.

verify

Parse and verify a JWT token.

Usage:

jwt-rsa verify [options] TOKEN

Options:

• -K, --private-key: Path to the private key.
• -k, --public-key: Path to the public key. If ommited, the public key will be extracted from the private key.
• -V, --no-verify: Do not verify the token's signature.
• -I, --no-interactive: Disable interactive mode. By default, interactive mode is enabled.

Examples:

Verify a JWT token using the public key:

$ echo '{"foo": "bar"}' | jwt-rsa issue -K /tmp/key -I --expired 3600 | jwt-rsa verify -k /tmp/key.pub
Enter JWT token:
Decoded token:

{
 "exp": 1738630217,
 "foo": "bar",
 "nbf": 1735951797
}

convert

Convert a JWT token's key format.

Usage:

jwt-rsa convert PRIVATE_KEY_PATH [options]

Options:

• private_key: Path to the source private key (positional argument).
• -k, --save-public: Path to save the converted public key. If omitted, the public key will be saved to the same directory as the private key with a .pub extension.
• -K, --save-private: Path to save the converted private key.
• -o, --format: Output format (pem, jwk, base64). Default: jwk.
• -f, --force: Overwrite existing keys if they exist.
• -r, --raw: Output raw JSON without indentation.

Examples:

Convert a private key from PEM to JWK format:

jwt-rsa convert /tmp/key -o jwk -K /tmp/jwk
Public key file not specified, saving public key to /tmp/jwk.pub
Saving public key to /tmp/jwk.pub in PEM format
Saving private key to /tmp/jwk in PEM format

Convert a private key from PEM to base64 format and print the output:

$ jwt-rsa convert /tmp/key -o base64
Public key in base64 format:
MIICCg...EAAQ==
Private key in base64 format:
MIIJQgIBA....DANBgkqhkiG==

jwks

Fetch and inspect a JSON Web Key Set (JWKs) from a remote URL.

Usage:

jwt-rsa jwks URL

Options:

• url: URL for the JWKs endpoint (positional argument, required).

Examples:

Fetch JWKs from a well-known endpoint:

$ jwt-rsa jwks https://example.com/.well-known/jwks.json

License

This project is licensed under the MIT License.