Auth Hardening

Open Astra uses JWT-based authentication. Two optional hardening features let you perform zero-downtime key rotation and bind tokens to the device they were issued on.

Zero-downtime JWT key rotation

Rotating JWT_SECRET normally invalidates all existing tokens, forcing users to re-authenticate. The JWT_SECRET_PREV env var solves this: the gateway accepts tokens signed with either the current or the previous secret, so you can rotate without a hard logout.

# Step 1: generate a new secret
NEW_SECRET=$(openssl rand -base64 48)

# Step 2: set both vars — existing tokens still verify with the old secret
JWT_SECRET=${NEW_SECRET}
JWT_SECRET_PREV=${OLD_SECRET}

# Step 3: deploy; all new tokens are signed with JWT_SECRET.
#         Existing tokens signed with JWT_SECRET_PREV remain valid.

# Step 4: after all old tokens expire (default 15 minutes for access tokens),
#         remove JWT_SECRET_PREV from your env.

How verification works

1. The gateway first tries to verify the token with JWT_SECRET.
2. If that fails and JWT_SECRET_PREV is set, it retries with the previous secret.
3. If both fail, the request is rejected with 401 Unauthorized.

Once all tokens signed with the old secret have expired (15 minutes by default for access tokens), remove JWT_SECRET_PREV from your deployment.

Device fingerprint binding

When BIND_JWT_TO_DEVICE=true, each access token embeds a dfp claim — a 16-character hex fingerprint derived from the client's User-Agent header and IP subnet (/24). On every subsequent request, the gateway recomputes the fingerprint and rejects the token if it does not match, preventing stolen-token replay attacks from a different device or network.

# Enable device fingerprint binding
BIND_JWT_TO_DEVICE=true

# Tokens are now bound to a fingerprint derived from:
#   sha256(User-Agent + IP subnet).slice(0, 16)
# Tokens used from a different User-Agent or /24 subnet are rejected with 401.

Environment variable summary