jwt.rdoc

doc/jwt.rdoc
Last Update: 2023-09-29 16:19:05 -0700

Documentation for JWT Feature

The jwt feature adds support for JSON API access for all other features that ship with Rodauth, using JWT (JSON Web Tokens) to hold the session information. It depends on the json feature.

In order to use this feature, you have to set the jwt_secret configuration option with the secret used to cryptographically protect the token.

To use this JSON API, when processing responses for requests to a Rodauth endpoint, check for the Authorization header, and use the value of the response Authorization header as the request Authorization header in future requests, if the response Authorization header is set. If the response Authorization header is not set, then continue to use the previous Authorization header.

When using this feature, consider using the json: :only option when loading the rodauth plugin, if you want Rodauth to only handle JSON requests. If you don’t use the json: :only option, the jwt feature will probably result in an error if a request to a Rodauth endpoint comes in with a Content-Type that isn’t application/json, unless you also set only_json? false in your rodauth configuration.

If you would like to check if a valid JWT was submitted with the current request in your Roda app, you can call the rodauth.valid_jwt? method. If rodauth.valid_jwt? returns true, the contents of the jwt can be retrieved from rodauth.session.

Logging the session out does not invalidate the previous JWT token by default. If you would like this behavior, you can use the active_sessions feature, which stores session identifiers in the database and deletes them when the session expires. This provides a whitelist approach of revoking JWT tokens.

Auth Value Methods

invalid_jwt_format_error_message

The error message to use when a JWT with an invalid format is submitted in the Authorization header.

jwt_algorithm

The JWT algorithm to use, HS256 by default.

jwt_authorization_ignore

A regexp matched against the Authorization header, which skips JWT processing if it matches. By default, HTTP Basic and Digest authentication are ignored.

jwt_authorization_remove

A regexp to remove from the Authorization header before processing the JWT. By default, a Bearer prefix is removed.

jwt_decode_opts

An optional hash to pass to JWT.decode. Can be used to set JWT verifiers.

jwt_old_secret

The previous JWT secret used, to support JWT secret rotation (only supported when using jwt 2.4+). Access to this should be protected the same as a session secret.

jwt_secret

The JWT secret to use. Access to this should be protected the same as a session secret.

jwt_session_key

A key to nest the session hash under in the JWT payload. nil by default, for no nesting.

jwt_symbolize_deeply?

Whether to symbolize the session hash deeply. false by default.

use_jwt?

Whether to use the JWT in the Authorization header for authentication information. If false, falls back to using the rack session. By default, the Authorization header is used if it is present, if only_json? is true, or if the request uses a json content type.

Auth Methods

jwt_session_hash

The session hash used to create the session_jwt. Can be used to set JWT claims.

jwt_token

Retrieve the JWT token from the request, by default taking it from the Authorization header.

session_jwt

An encoded JWT for the current session.

set_jwt_token(token)

Set the JWT token in the response, by default storing it in the Authorization header.