Flask-JWT-Extended Documentation

Flask-JWT-Extended provides JSON Web Token (JWT) support for Flask applications to protect routes. It includes several optional features to simplify JWT management:

• Custom Claims: Add and validate custom data within tokens.
• Automatic User Loading: Access the authenticated user via current_user.
• Refresh Tokens: Support for issuing and using refresh tokens.
• Fresh Tokens: First-class support for identifying 'fresh' tokens, useful for authorizing sensitive operations.
• Token Revocation: Mechanisms for blocklisting/revoking tokens.
• Cookie Support: Ability to store tokens in cookies and provides built-in CSRF protection.

You can control which methods your Flask application uses to accept JWTs using the JWT_TOKEN_LOCATION configuration option. Additionally, you can override this global setting for specific routes by passing the locations argument to the @jwt_required decorator.

Common locations include:

• Headers: Sending the token in the Authorization header.
• Cookies: Using browser cookies (recommended for web browsers).
• Query String: Sending the token as a URL parameter (not recommended due to security risks).
• JSON Body: Including the token in the request body (only works for methods like POST, PUT, PATCH, or DELETE).

The token freshness pattern allows you to distinguish between tokens created via recent credentials (e.g., username/password) and tokens obtained via refreshing.

• Fresh tokens: Can access all routes.
• Non-fresh tokens: Can access standard routes but are blocked from critical or dangerous routes (e.g., changing an email address) that require a fresh token.

This pattern works seamlessly with both implicit cookie refreshing and explicit refresh token strategies.

Refer to the token_freshness.py example for implementation details.

To access a route protected by @jwt_required(), you must include the JWT in the request headers. By default, the extension expects an Authorization header using the Bearer scheme:

Authorization: Bearer <access_token>

Flask-JWT-Extended provides a mechanism to automatically convert user objects to identities for JWTs and then reload those objects from the identity when a request is made. This is achieved using two callback functions registered with the JWTManager:

1. user_identity_loader: A callback that takes a user object and returns a unique identifier (usually a string) to be stored in the JWT.
2. user_lookup_loader: A callback that takes the identity from the JWT and performs a lookup (e.g., a database query) to return the original user object.

Once configured, the loaded user object is accessible in protected routes via the current_user attribute.

The core workflow of Flask-JWT-Extended involves three main steps:

1. Create a token: Use create_access_token to generate a JSON Web Token.
2. Protect routes: Use the @jwt_required() decorator to ensure only requests with a valid JWT can access a specific view.
3. Retrieve identity: Use get_jwt_identity() inside a protected route to access the identity (e.g., user ID or username) stored within the token.

Security Warning: Always change the JWT secret key in your application to a secure value. The tokens are signed with this key; if it is compromised, attackers can forge arbitrary tokens.

You can configure the extension's behavior using standard Flask configuration handling. Set the desired option on your Flask app.config object.

app.config["OPTION_NAME"] = option_value

If you want an endpoint to be accessible whether or not a JWT is present in the request, use the jwt_required decorator with the optional=True argument.

Behavior when no JWT is provided:

• get_jwt() and get_jwt_header() return an empty dictionary {}.
• get_jwt_identity(), current_user, and get_current_user() return None.

Behavior when an invalid JWT is provided:

• If a JWT is present but is expired or not verifiable, the extension will still return an error as it would for a standard protected route. optional=True only bypasses the requirement for the presence of a token, not the validity of a token if one is sent.

In version 4.0.0, the JWT_USER_CLAIMS configuration option has been removed. Additional claims are now placed at the top level of the JWT instead of inside a nested user_claims dictionary. This allows for overriding reserved claims like nbf.

Warning: Existing JWTs using the old format will not work correctly.

Migration Strategies:

1. Change your secret key: This forces all users to receive new JWTs in the new format.
2. Build a shim: If changing the secret key is not feasible, implement a shim to handle both the old format (claims inside user_claims) and the new format (claims at the top level) until existing tokens expire.

Use a database if you need to maintain metadata about revoked tokens, such as when they were revoked, who revoked them, or if they can be un-revoked. This approach is useful for auditing and long-term tracking.

class TokenBlocklist(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    jti = db.Column(db.String(36), nullable=False, index=True)
    type = db.Column(db.String(16), nullable=False)
    user_id = db.Column(
        db.ForeignKey('person.id'),
        default=lambda: get_current_user().id,
        nullable=False,
    )
    created_at = db.Column(
        db.DateTime,
        server_default=func.now(),
        nullable=False,
    )

You can include custom data in an access or refresh token by passing a dictionary to the additional_claims argument in create_access_token() or create_refresh_token(). These claims can then be retrieved in protected routes using get_jwt().

Security Warning: JWTs are not encrypted and can be easily decoded. Never include sensitive information in these claims.