Flask-User API

Config Settings

# Features                     # Default   # Description
USER_ENABLE_CHANGE_PASSWORD    = True      # Allow users to change their password

USER_ENABLE_CHANGE_USERNAME    = True      # Allow users to change their username
                                           # Requires USER_ENABLE_USERNAME=True

USER_ENABLE_CONFIRM_EMAIL      = True      # Force users to confirm their email
                                           # Requires USER_ENABLE_EMAIL=True

USER_ENABLE_FORGOT_PASSWORD    = True      # Allow users to reset their passwords
                                           # Requires USER_ENABLE_EMAIL=True

USER_ENABLE_LOGIN_WITHOUT_CONFIRM_EMAIL = False
                                           # Allow users to login without a
                                           # confirmed email address
                                           # Protect views using @confirm_email_required

USER_ENABLE_EMAIL              = True      # Register with Email
                                           # Requires USER_ENABLE_REGISTRATION=True

USER_ENABLE_MULTIPLE_EMAILS    = False     # Users may register multiple emails
                                           # Requires USER_ENABLE_EMAIL=True

USER_ENABLE_REGISTRATION       = True      # Allow new users to register

USER_ENABLE_RETYPE_PASSWORD    = True      # Prompt for `retype password` in:
                                           #   - registration form,
                                           #   - change password form, and
                                           #   - reset password forms.

USER_ENABLE_USERNAME           = True      # Register and Login with username
# Settings                       # Default     # Description
USER_APP_NAME                    = 'AppName'   # Used by email templates

USER_AUTO_LOGIN                  = True

USER_AUTO_LOGIN_AFTER_CONFIRM    = USER_AUTO_LOGIN

USER_AUTO_LOGIN_AFTER_REGISTER   = USER_AUTO_LOGIN

USER_AUTO_LOGIN_AFTER_RESET_PASSWORD = USER_AUTO_LOGIN

USER_AUTO_LOGIN_AT_LOGIN         = USER_AUTO_LOGIN

USER_CONFIRM_EMAIL_EXPIRATION    = 2*24*3600   # Confirmation expiration in seconds
                                               # (2*24*3600 represents 2 days)

USER_INVITE_EXPIRATION           = 90*24*3600  # Invitation expiration in seconds
                                               # (90*24*3600 represents 90 days)
                                               # v0.6.2 and up

USER_PASSWORD_HASH               = 'bcrypt'    # Any passlib crypt algorithm

USER_PASSWORD_HASH_MODE          = 'passlib'   # Set to 'Flask-Security' for
                                               # Flask-Security compatible hashing

SECURITY_PASSWORD_SALT                         # Only needed for
                                               # Flask-Security compatible hashing

USER_REQUIRE_INVITATION          = False       # Registration requires invitation
                                               # Not yet implemented
                                               # Requires USER_ENABLE_EMAIL=True

USER_RESET_PASSWORD_EXPIRATION   = 2*24*3600   # Reset password expiration in seconds
                                               # (2*24*3600 represents 2 days)

USER_SEND_PASSWORD_CHANGED_EMAIL = True        # Send registered email
                                               # Requires USER_ENABLE_EMAIL=True

USER_SEND_REGISTERED_EMAIL       = True        # Send registered email
                                               # Requires USER_ENABLE_EMAIL=True

USER_SEND_USERNAME_CHANGED_EMAIL = True        # Send registered email
                                               # Requires USER_ENABLE_EMAIL=True

USER_SHOW_USERNAME_EMAIL_DOES_NOT_EXIST = USER_ENABLE_REGISTRATION
                                               # Show 'Username/Email does not exist' error message
                                               # instead of 'Incorrect Username/Email and/or password'
# URLs                        # Default
USER_CHANGE_PASSWORD_URL      = '/user/change-password'
USER_CHANGE_USERNAME_URL      = '/user/change-username'
USER_CONFIRM_EMAIL_URL        = '/user/confirm-email/<token>'
USER_EMAIL_ACTION_URL         = '/user/email/<id>/<action>'     # v0.5.1 and up
USER_FORGOT_PASSWORD_URL      = '/user/forgot-password'
USER_INVITE_URL               = '/user/invite'                  # v0.6.2 and up
USER_LOGIN_URL                = '/user/login'
USER_LOGOUT_URL               = '/user/logout'
USER_MANAGE_EMAILS_URL        = '/user/manage-emails'
USER_REGISTER_URL             = '/user/register'
USER_RESEND_CONFIRM_EMAIL_URL = '/user/resend-confirm-email'    # v0.5.0 and up
USER_RESET_PASSWORD_URL       = '/user/reset-password/<token>'
# Endpoints are converted to URLs using url_for()
# The empty endpoint ('') will be mapped to the root URL ('/')
USER_AFTER_CHANGE_PASSWORD_ENDPOINT      = ''              # v0.5.3 and up
USER_AFTER_CHANGE_USERNAME_ENDPOINT      = ''              # v0.5.3 and up
USER_AFTER_CONFIRM_ENDPOINT              = ''              # v0.5.3 and up
USER_AFTER_FORGOT_PASSWORD_ENDPOINT      = ''              # v0.5.3 and up
USER_AFTER_LOGIN_ENDPOINT                = ''              # v0.5.3 and up
USER_AFTER_LOGOUT_ENDPOINT               = 'user.login'    # v0.5.3 and up
USER_AFTER_REGISTER_ENDPOINT             = ''              # v0.5.3 and up
USER_AFTER_RESEND_CONFIRM_EMAIL_ENDPOINT = ''              # v0.5.3 and up
USER_AFTER_RESET_PASSWORD_ENDPOINT       = ''              # v0.6 and up
USER_INVITE_ENDPOINT                     = ''              # v0.6.2 and up

# Users with an unconfirmed email trying to access a view that has been
# decorated with @confirm_email_required will be redirected to this endpoint
USER_UNCONFIRMED_EMAIL_ENDPOINT          = 'user.login'    # v0.6 and up

# Unauthenticated users trying to access a view that has been decorated
# with @login_required or @roles_required will be redirected to this endpoint
USER_UNAUTHENTICATED_ENDPOINT            = 'user.login'    # v0.5.3 and up

# Unauthorized users trying to access a view that has been decorated
# with @roles_required will be redirected to this endpoint
USER_UNAUTHORIZED_ENDPOINT               = ''              # v0.5.3 and up
# Email template files                  # Defaults
USER_CONFIRM_EMAIL_EMAIL_TEMPLATE       = 'flask_user/emails/confirm_email'
USER_FORGOT_PASSWORD_EMAIL_TEMPLATE     = 'flask_user/emails/forgot_password'
USER_INVITE_EMAIL_TEMPLATE              = 'flask_user/emails/invite'
USER_PASSWORD_CHANGED_EMAIL_TEMPLATE    = 'flask_user/emails/password_changed'
USER_REGISTERED_EMAIL_TEMPLATE          = 'flask_user/emails/registered'
USER_USERNAME_CHANGED_EMAIL_TEMPLATE    = 'flask_user/emails/username_changed'

# These settings correspond to the start of three template files:
# SOMETHING_subject.txt   # Email subject
# SOMETHING_message.html  # Email message in HTML format
# SOMETHING_message.txt   # Email message in Text format
# Form template files                   # Defaults
USER_CHANGE_PASSWORD_TEMPLATE           = 'flask_user/change_password.html'
USER_CHANGE_USERNAME_TEMPLATE           = 'flask_user/change_username.html'
USER_FORGOT_PASSWORD_TEMPLATE           = 'flask_user/forgot_password.html'
USER_INVITE_TEMPLATE                    = 'flask_user/invite.html'                  # v0.6.2 and up
USER_INVITE_ACCEPT_TEMPLATE             = 'flask_user/register.html'                # v0.6.2 and up
USER_LOGIN_TEMPLATE                     = 'flask_user/login.html'
USER_MANAGE_EMAILS_TEMPLATE             = 'flask_user/manage_emails.html'           # v0.5.1 and up
USER_REGISTER_TEMPLATE                  = 'flask_user/register.html'
USER_RESEND_CONFIRM_EMAIL_TEMPLATE      = 'flask_user/resend_confirm_email.html'    # v0.5.0 and up
USER_RESET_PASSWORD_TEMPLATE            = 'flask_user/reset_password.html'

# Place the Login form and the Register form on one page:
# Only works for Flask-User v0.4.9 and up
USER_LOGIN_TEMPLATE                     = 'flask_user/login_or_register.html'
USER_REGISTER_TEMPLATE                  = 'flask_user/login_or_register.html'

SQLAlchemyAdapter()

Flask-User shields itself from database operations through a DBAdapter. It ships with a SQLAlchemyAdapter, but the API is very simple, so other adapters can be easily added.

class SQLAlchemyAdapter(DBAdapter):
    """ This object shields Flask-User from database specific functions. """

    def get_object(self, ObjectClass, pk):
        """ Retrieve one object specified by the primary key 'pk' """

    def find_all_objects(self, ObjectClass, **kwargs):
        """ Retrieve all objects matching the case sensitive filters in 'kwargs'. """

    def find_first_object(self, ObjectClass, **kwargs):
        """ Retrieve the first object matching the case sensitive filters in 'kwargs'. """

    def ifind_first_object(self, ObjectClass, **kwargs):
        """ Retrieve the first object matching the case insensitive filters in 'kwargs'. """

    def add_object(self, ObjectClass, **kwargs):
        """ Add an object with fields and values specified in kwargs. """

    def update_object(self, object, **kwargs):
        """ Update an object with fields and values specified in kwargs. """

    def delete_object(self, object):
        """ Delete an object. """

    def commit(self):
        """ Commit an Add, Update or Delete. """

Template variables

The following template variables are available for use in email and form templates:

user_manager       # points to the UserManager object

Template functions

The following template functions are available for use in email and form templates:

# Function                           Setting                   # Default
url_for('user.change_password')      USER_CHANGE_PASSWORD_URL      = '/user/change-password'
url_for('user.change_username')      USER_CHANGE_USERNAME_URL      = '/user/change-username'
url_for('user.confirm_email')        USER_CONFIRM_EMAIL_URL        = '/user/confirm-email/<token>'
url_for('user.email_action')         USER_EMAIL_ACTION_URL         = '/user/email/<id>/<action>'    # v0.5.1 and up
url_for('user.forgot_password')      USER_FORGOT_PASSWORD_URL      = '/user/forgot-password'
url_for('user.login')                USER_LOGIN_URL                = '/user/sign-in'
url_for('user.logout')               USER_LOGOUT_URL               = '/user/sign-out'
url_for('user.register')             USER_REGISTER_URL             = '/user/register'
url_for('user.resend_confirm_email') USER_RESEND_CONFIRM_EMAIL_URL = '/user/resend-confirm-email'   # v0.5.0 and up
url_for('user.reset_password')       USER_RESET_PASSWORD_URL       = '/user/reset-password/<token>'
url_for('user.profile')              USER_PROFILE_URL              = '/user/profile'                # v0.5.5 and up

UserManager

UserManager()

user_manager = UserManager(
        db_adapter,                     # typically from SQLAlchemyAdapter()
        app = None,                     # typically from Flask() or None

        # Forms
        add_email_form                  = forms.AddEmailForm,
        change_username_form            = forms.ChangeUsernameForm,
        forgot_password_form            = forms.ForgotPasswordForm,
        login_form                      = forms.LoginForm,
        register_form                   = forms.RegisterForm,
        resend_confirm_email_form       = forms.ResendConfirmEmailForm,
        reset_password_form             = forms.ResetPasswordForm,

        # Validators
        username_validator              = forms.username_validator,
        password_validator              = forms.password_validator,

        # View functions
        change_password_view_function   = views.change_password,
        change_username_view_function   = views.change_username,
        confirm_email_view_function     = views.confirm_email,
        email_action_view_function      = views.email_action,
        forgot_password_view_function   = views.forgot_password,
        login_view_function             = views.login,
        logout_view_function            = views.logout,
        manage_emails_view_function     = views.manage_emails,
        register_view_function          = views.register,
        resend_confirm_email_view_function = views.resend_confirm_email_view_function,
        reset_password_view_function    = views.reset_password,
        user_profile_view_function      = views.user_profile,
        unauthenticated_view_function   = views.unauthenticated,
        unauthorized_view_function      = views.unauthorized,

        # Miscellaneous
        login_manager                   = LoginManager(),
        password_crypt_context          = None,
        send_email_function             = emails.send_email,
        make_safe_url_function          = views.make_safe_url,
        token_manager                   = tokens.TokenManager(),
        )

Typical use:

app = Flask(__name__)
db = SQLAlchemy(app)
db_adapter = SQLAlchemyAdapter(db, User)
user_manager = UserManager(db_adapter, app,
        register_form=my_register_form,
        register_view_function=my_register_view_function)

Work in progress. See Basic App for now.

init_app()

init_app() is used by Application Factories to bind the UserManager to a specific app.

typical use:

db = SQLAlchemy()
db_adapter = SQLAlchemyAdapter(db, User)
user_manager = UserManager(db_adapter)

def create_app():
    app = Flask(__name__)
    db.init_app(app)
    user_manager.init_app(app)

Work in progress. See Basic App for now.

hash_password()

user_manager.hash_password(password)
# Returns hashed 'password' using the configured password hash
# Config settings: USER_PASSWORD_HASH_MODE = 'passlib'
#                  USER_PASSWORD_HASH      = 'bcrypt'
#                  USER_PASSWORD_SALT      = SECRET_KEY

verify_password()

user_manager.verify_password(password, user)
# Returns True if 'password' matches the user's 'hashed password'
# Returns False otherwise.

Signals

# Signal                    # Sent when ...
user_changed_password       # a user changed their password
user_changed_username       # a user changed their username
user_confirmed_email        # a user confirmed their email
user_forgot_password        # a user submitted a reset password request
user_logged_in              # a user logged in
user_logged_out             # a user logged out
user_registered             # a user registered for a new account
user_reset_password         # a user reset their password (forgot password)