Flask-JWT

Add basic JWT features to your Flask application.

Installation

Install with pip or easy_install:

pip install Flask-JWT

or download the latest version from version control:

git clone https://github.com/mattupstate/flask-jwt.git ./flask-jwt
pip install ./flask-jwt

Quickstart

Minimum viable application configuration:

from flask import Flask
from flask_jwt import JWT, jwt_required, current_identity
from werkzeug.security import safe_str_cmp

class User(object):
    def __init__(self, id, username, password):
        self.id = id
        self.username = username
        self.password = password

    def __str__(self):
        return "User(id='%s')" % self.id

users = [
    User(1, 'user1', 'abcxyz'),
    User(2, 'user2', 'abcxyz'),
]

username_table = {u.username: u for u in users}
userid_table = {u.id: u for u in users}

def authenticate(username, password):
    user = username_table.get(username, None)
    if user and safe_str_cmp(user.password.encode('utf-8'), password.encode('utf-8')):
        return user

def identity(payload):
    user_id = payload['identity']
    return userid_table.get(user_id, None)

app = Flask(__name__)
app.debug = True
app.config['SECRET_KEY'] = 'super-secret'

jwt = JWT(app, authenticate, identity)

@app.route('/protected')
@jwt_required()
def protected():
    return '%s' % current_identity

if __name__ == '__main__':
    app.run()

To get a token make a request to the auth resource:

POST /auth HTTP/1.1
Host: localhost:5000
Content-Type: application/json

{
    "username": "joe",
    "password": "pass"
}

The response should look similar to:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNDQ0OTE3NjQwLCJuYmYiOjE0NDQ5MTc2NDAsImV4cCI6MTQ0NDkxNzk0MH0.KPmI6WSjRjlpzecPvs3q_T3cJQvAgJvaQAPtk1abC_E"
}

This token can then be used to make requests against protected endpoints:

GET /protected HTTP/1.1
Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6MSwiaWF0IjoxNDQ0OTE3NjQwLCJuYmYiOjE0NDQ5MTc2NDAsImV4cCI6MTQ0NDkxNzk0MH0.KPmI6WSjRjlpzecPvs3q_T3cJQvAgJvaQAPtk1abC_E

Within a function decorated by jwt_required(), you can use the current_identity proxy to access the user whose token was passed into this request context.

Configuration Options

JWT_DEFAULT_REALM The default realm. Defaults to Login Required
JWT_AUTH_URL_RULE The authentication endpoint URL. Defaults to /auth.
JWT_AUTH_ENDPOINT The authentication endpoint name. Defaults to jwt.
JWT_AUTH_USERNAME_KEY The username key in the authentication request payload. Defaults to username.
JWT_AUTH_PASSWORD_KEY The password key in the authentication request payload. Defaults to password.
JWT_ALGORITHM The token algorithm. Defaults to HS256
JWT_LEEWAY The amount of leeway given when decoding access tokens specified as an integer of seconds or a datetime.timedelta instance. Defaults to timedelta(seconds=10).
JWT_VERIFY Flag indicating if all tokens should be verified. Defaults to True. It is not recommended to change this value.
JWT_AUTH_HEADER_PREFIX The Authorization header value prefix. Defaults to JWT as to not conflict with OAuth2 Bearer tokens. This is not a case sensitive value.
JWT_VERIFY_EXPIRATION Flag indicating if all tokens should verify their expiration time. Defaults to True. It is not recommended to change this value.
JWT_LEEWAY A token expiration leeway value. Defaults to 0.
JWT_EXPIRATION_DELTA A datetime.timedelta value indicating how long tokens are valid for. This value is added to the iat (issued at) claim. Defaults to timedelta(seconds=300)
JWT_NOT_BEFORE_DELTA A datetime.timedelta value indicating a relative time from the iat (issued at) claim that the token can begin to be used. This value is added to the iat (issued at) claim. Defaults to timedelta(seconds=0)
JWT_VERIFY_CLAIMS A list of claims to verify when decoding tokens. Defaults to ['signature', 'exp', 'nbf', 'iat'].
JWT_REQUIRED_CLAIMS A list of claims that are required in a token to be considered valid. Defaults to ['exp', 'iat', 'nbf']

API

flask_jwt.current_identity

A proxy for the current identity. It will only be set in the context of function decorated by jwt_required().

class flask_jwt.JWT(app=None, authentication_handler=None, identity_handler=None)[source]
auth_request_handler(callback)[source]

Specifies the authentication response handler function.

Parameters:callback (callable) – the auth request handler function
auth_response_handler(callback)[source]

Specifies the authentication response handler function.

Parameters:callback (callable) – the auth response handler function
authentication_handler(callback)[source]

Specifies the identity handler function. This function receives two positional arguments. The first being the username the second being the password. It should return an object representing an authenticated identity. Example:

@jwt.authentication_handler
def authenticate(username, password):
    user = User.query.filter(User.username == username).scalar()
    if bcrypt.check_password_hash(user.password, password):
        return user
Parameters:callback – the identity handler function
identity_handler(callback)[source]

Specifies the identity handler function. This function receives one positional argument being the JWT payload. For example:

@jwt.identity_handler
def identify(payload):
    return User.query.filter(User.id == payload['identity']).scalar()
Parameters:callback – the identity handler function
jwt_decode_handler(callback)[source]

Specifies the decoding handler function. This function receives a signed payload and decodes it.

Parameters:callback (callable) – the decoding handler function
jwt_encode_handler(callback)[source]

Specifies the encoding handler function. This function receives a payload and signs it.

Parameters:callback (callable) – the encoding handler function
jwt_error_handler(callback)[source]

Specifies the error handler function. Example:

@jwt.error_handler
def error_handler(e):
    return "Something bad happened", 400
Parameters:callback – the error handler function
jwt_headers_handler(callback)[source]

Specifies the JWT header handler function. This function receives the return value from the identity_handler function.

Example:

@jwt.payload_handler
def make_payload(identity):
    return {'user_id': identity.id}
Parameters:callback (callable) – the payload handler function
jwt_payload_handler(callback)[source]

Specifies the JWT payload handler function. This function receives the return value from the identity_handler function

Example:

@jwt.payload_handler
def make_payload(identity):
    return {'user_id': identity.id}
Parameters:callback (callable) – the payload handler function
request_handler(callback)[source]

Specifieds the request handler function. This function returns a JWT from the current request.

Parameters:callback (callable) – the request handler function
flask_jwt.jwt_required(realm=None)[source]

View decorator that requires a valid JWT token to be present in the request

Parameters:realm – an optional realm