flask_praetorian package

Submodules

flask_praetorian.base module

class flask_praetorian.base.Praetorian(app=None, user_class=None, is_blacklisted=None, encode_jwt_token_hook=None, refresh_jwt_token_hook=None)

Bases: object

Comprises the implementation for the flask-praetorian flask extension. Provides a tool that allows password authentication and token provision for applications and designated endpoints

authenticate(username, password)

Verifies that a password matches the stored password for that username. If verification passes, the matching user instance is returned

encode_eternal_jwt_token(user, **custom_claims)

This utility function encodes a jwt token that never expires

Note

This should be used sparingly since the token could become a security concern if it is ever lost. If you use this method, you should be sure that your application also implements a blacklist so that a given token can be blocked should it be lost or become a security concern

encode_jwt_token(user, override_access_lifespan=None, override_refresh_lifespan=None, bypass_user_check=False, is_registration_token=False, is_reset_token=False, **custom_claims)

Encodes user data into a jwt token that can be used for authorization at protected endpoints

Param:override_access_lifespan: Override’s the instance’s access lifespan to set a custom duration after which the new token’s accessability will expire. May not exceed the refresh_lifespan Param:override_refresh_lifespan: Override’s the instance’s refresh lifespan to set a custom duration after which the new token’s refreshability will expire. Param:bypass_user_check: Override checking the user for being real/active. Used for registration token generation. Param:is_registration_token: Indicates that the token will be used only for email-based registration Param:custom_claims: Additional claims that should be packed in the payload. Note that any claims supplied here must be JSON compatible types

encrypt_password(raw_password)

NOTE This should be deprecated as its an incorrect definition for

what is actually being done – we are hashing, not encrypting

error_handler(error)

Provides a flask error handler that is used for PraetorianErrors (and derived exceptions).

extract_jwt_token(token, access_type=<AccessType.access: 'ACCESS'>)

Extracts a data dictionary from a jwt token

get_user_from_registration_token(token)

Gets a user based on the registration token that is supplied. Verifies that the token is a regisration token and that the user can be properly retrieved

hash_password(raw_password)

Hashes a plaintext password using the stored passlib password context

init_app(app=None, user_class=None, is_blacklisted=None, encode_jwt_token_hook=None, refresh_jwt_token_hook=None)

Initializes the Praetorian extension

Param:

app: The flask app to bind this extension to

Param:

user_class: The class used to interact with user data

Param:

is_blacklisted: A method that may optionally be used to check the token against a blacklist when access or refresh is requested should take the jti for the token to check as a single argument. Returns True if the jti is blacklisted, False otherwise. By default, always returns False.

Parameters:

• encode_jwt_token_hook – A method that may optionally be called right before an encoded jwt is generated. Should take payload_parts which contains the ingredients for the jwt.
• refresh_jwt_token_hook – A method that may optionally be called right before an encoded jwt is refreshed. Should take payload_parts which contains the ingredients for the jwt.

pack_header_for_user(user, override_access_lifespan=None, override_refresh_lifespan=None, **custom_claims)

Encodes a jwt token and packages it into a header dict for a given user

Param:user: The user to package the header for Param:override_access_lifespan: Override’s the instance’s access lifespan to set a custom duration after which the new token’s accessability will expire. May not exceed the refresh_lifespan Param:override_refresh_lifespan: Override’s the instance’s refresh lifespan to set a custom duration after which the new token’s refreshability will expire. Param:custom_claims: Additional claims that should be packed in the payload. Note that any claims supplied here must be JSON compatible types

read_token()

Tries to unpack the token from the current flask request in the locations configured by JWT_PLACES. Check-Order is defined by the value order in JWT_PLACES.

read_token_from_cookie()

Unpacks a jwt token from the current flask request

read_token_from_header()

Unpacks a jwt token from the current flask request

refresh_jwt_token(token, override_access_lifespan=None)

Creates a new token for a user if and only if the old token’s access permission is expired but its refresh permission is not yet expired. The new token’s refresh expiration moment is the same as the old token’s, but the new token’s access expiration is refreshed

Param:token: The existing jwt token that needs to be replaced with a new, refreshed token Param:override_access_lifespan: Override’s the instance’s access lifespan to set a custom duration after which the new token’s accessability will expire. May not exceed the refresh lifespan

send_registration_email(email, user=None, template=None, confirmation_sender=None, confirmation_uri=None, subject=None, override_access_lifespan=None)

Sends a registration email to a new user, containing a time expiring

token usable for validation. This requires your application is initialized with a mail extension, which supports Flask-Mail’s Message() object and a send() method.

Returns a dict containing the information sent, along with the

result from mail send.

Param:user: The user object to tie claim to (username, id, email, etc) Param:template: HTML Template for confirmation email. If not provided, a stock entry is used Param:confirmation_sender: The sender that shoudl be attached to the confirmation email. Overrides the PRAETORIAN_CONFIRMATION_SENDER config setting Param:confirmation_uri: The uri that should be visited to complete email registration. Should usually be a uri to a frontend or external service that calls a ‘finalize’ method in the api to complete registration. Will override the PRAETORIAN_CONFIRMATION_URI config setting Param:subject: The registration email subject. Will override the PRAETORIAN_CONFIRMATION_SUBJECT config setting. Param:override_access_lifespan: Overrides the JWT_ACCESS_LIFESPAN to set an access lifespan for the registration token.

send_reset_email(email, template=None, reset_sender=None, reset_uri=None, subject=None, override_access_lifespan=None)

Sends a password reset email to a user, containing a time expiring

token usable for validation. This requires your application is initialized with a mail extension, which supports Flask-Mail’s Message() object and a send() method.

Returns a dict containing the information sent, along with the

result from mail send.

Param:email: The email address to attempt to send to Param:template: HTML Template for reset email. If not provided, a stock entry is used Param:confirmation_sender: The sender that shoudl be attached to the reset email. Overrides the PRAETORIAN_RESET_SENDER config setting Param:confirmation_uri: The uri that should be visited to complete password reset. Should usually be a uri to a frontend or external service that calls the ‘validate_reset_token()’ method in the api to complete reset. Will override the PRAETORIAN_RESET_URI config setting Param:subject: The reset email subject. Will override the PRAETORIAN_RESET_SUBJECT config setting. Param:override_access_lifespan: Overrides the JWT_ACCESS_LIFESPAN to set an access lifespan for the registration token.

send_token_email(email, user=None, template=None, action_sender=None, action_uri=None, subject=None, override_access_lifespan=None, custom_token=None)

Sends an email to a user, containing a time expiring

token usable for several actions. This requires your application is initialized with a mail extension, which supports Flask-Mail’s Message() object and a send() method.

Returns a dict containing the information sent, along with the

result from mail send.

Param:email: The email address to use (username, id, email, etc) Param:user: The user object to tie claim to (username, id, email, etc) Param:template: HTML Template for confirmation email. If not provided, a stock entry is used Param:action_sender: The sender that should be attached to the confirmation email. Param:action_uri: The uri that should be visited to complete the token action. Param:subject: The email subject. Param:override_access_lifespan: Overrides the JWT_ACCESS_LIFESPAN to set an access lifespan for the registration token. Param:custom_token: The token to be carried as the email’s payload

validate_reset_token(token)

Validates a password reset request based on the reset token that is supplied. Verifies that the token is a reset token and that the user can be properly retrieved

verify_and_update(user=None, password=None)

Validate a password hash contained in the user object is

hashed with the defined hash scheme (PRAETORIAN_HASH_SCHEME).

If not, raise an Exception of LegacySchema, unless the

password arguement is provided, in which case an attempt to call user.save() will be made, updating the hashed password to the currently desired hash scheme (PRAETORIAN_HASH_SCHEME).

Param:

user: The user object to tie claim to (username, id, email, etc). MUST include the hashed password field, defined as user.password

Param:

password: The user’s provide password from login. If present, this is used to validate

and then attempt to update with the new PRAETORIAN_HASH_SCHEME scheme.

flask_praetorian.decorators module

flask_praetorian.decorators.auth_accepted(method)

This decorator is used to allow an authenticated user to be identified while being able to access a flask route, and adds the current user to the current flask context.

flask_praetorian.decorators.auth_required(method)

This decorator is used to ensure that a user is authenticated before being able to access a flask route. It also adds the current user to the current flask context.

flask_praetorian.decorators.roles_accepted(*accepted_rolenames)

This decorator ensures that any uses accessing the decorated route have one of the needed roles to access it. If an @auth_required decorator is not supplied already, this decorator will implicitly check @auth_required first

flask_praetorian.decorators.roles_required(*required_rolenames)

This decorator ensures that any uses accessing the decorated route have all the needed roles to access it. If an @auth_required decorator is not supplied already, this decorator will implicitly check @auth_required first

flask_praetorian.exceptions module

exception flask_praetorian.exceptions.AuthenticationError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The entered user’s password did not match the stored password

exception flask_praetorian.exceptions.BlacklistedError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The jwt token has been blacklisted and may not be used any more

status_code = 403

exception flask_praetorian.exceptions.ClaimCollisionError(message)

Bases: flask_praetorian.exceptions.PraetorianError

” Custom claims to pack into the JWT payload collide with reserved claims

exception flask_praetorian.exceptions.ConfigurationError(message)

Bases: flask_praetorian.exceptions.PraetorianError

There was a problem with the configuration

exception flask_praetorian.exceptions.EarlyRefreshError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The jwt token has not yet expired for access and may not be refreshed

status_code = 425

exception flask_praetorian.exceptions.ExpiredAccessError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The jwt token has expired for access and must be refreshed

exception flask_praetorian.exceptions.ExpiredRefreshError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The jwt token has expired for refresh. An entirely new token must be issued

exception flask_praetorian.exceptions.InvalidRegistrationToken(message)

Bases: flask_praetorian.exceptions.PraetorianError

The supplied registration token is invalid

exception flask_praetorian.exceptions.InvalidResetToken(message)

Bases: flask_praetorian.exceptions.PraetorianError

The supplied registration token is invalid

exception flask_praetorian.exceptions.InvalidTokenHeader(message)

Bases: flask_praetorian.exceptions.PraetorianError

The token contained in the header is invalid

exception flask_praetorian.exceptions.InvalidUserError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The user is no longer valid and is now not authorized

status_code = 403

exception flask_praetorian.exceptions.LegacyScheme(message)

Bases: flask_praetorian.exceptions.PraetorianError

The processed hash is using an outdated scheme

exception flask_praetorian.exceptions.MissingClaimError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The jwt token is missing a required claim

exception flask_praetorian.exceptions.MissingRoleError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The token is missing a required role

status_code = 403

exception flask_praetorian.exceptions.MissingToken(message)

Bases: flask_praetorian.exceptions.PraetorianError

The header is missing the required jwt token

exception flask_praetorian.exceptions.MissingUserError(message)

Bases: flask_praetorian.exceptions.PraetorianError

The user could not be identified

exception flask_praetorian.exceptions.MisusedRegistrationToken(message)

Bases: flask_praetorian.exceptions.PraetorianError

Attempted to use a registration token for normal access

exception flask_praetorian.exceptions.MisusedResetToken(message)

Bases: flask_praetorian.exceptions.PraetorianError

Attempted to use a password reset token for normal access

exception flask_praetorian.exceptions.PraetorianError(message)

Bases: flask_buzz.FlaskBuzz

Provides a custom exception class for flask-praetorian based on flask-buzz. flask-buzz on gitub

status_code = 401