python,flask,web,login
Flask-Login
Flask-Login provides user session management for Flask. It handles the common tasks of logging in, logging out, and remembering your users’ sessions over extended periods of time.
It will:
- Store the active user’s ID in the session, and let you log them in and out easily.
- Let you restrict views to logged-in (or logged-out) users.
- Handle the normally-tricky “remember me” functionality.
- Help protect your users’ sessions from being stolen by cookie thieves.
- Possibly integrate with Flask-Principal or other authorization extensions later on.
However, it does not:
- Impose a particular database or other storage method on you. You are entirely in charge of how the user is loaded.
- Restrict you to using usernames and passwords, OpenIDs, or any other method of authenticating.
- Handle permissions beyond “logged in or not.”
- Handle user registration or account recovery.
Configuring your Application
The most important part of an application that uses Flask-Login is the LoginManagerclass. You should create one for your application somewhere in your code, like this:
login_manager = LoginManager()
The login manager contains the code that lets your application and Flask-Login work together, such as how to load a user from an ID, where to send users when they need to log in, and the like.
Once the actual application object has been created, you can configure it for login with:
login_manager.init_app(app)
How it Works
You will need to provide a user_loader callback. This callback is used to reload the user object from the user ID stored in the session. It should take the unicode ID of a user, and return the corresponding user object. For example:
@login_manager.user_loader
def load_user(userid):
return User.get(userid)
It should return None (not raise an exception) if the ID is not valid. (In that case, the ID will manually be removed from the session and processing will continue.)
Once a user has authenticated, you log them in with the login_user function. For example:
@app.route("/login", methods=["GET", "POST"])
def login():
form = LoginForm()
if form.validate_on_submit():
# login and validate the user...
login_user(user)
flash("Logged in successfully.")
return redirect(request.args.get("next") or url_for("index"))
return render_template("login.html", form=form)
It’s that simple. You can then access the logged-in user with the current_user proxy. Views that require your users to be logged in can be decorated with thelogin_required decorator:
@app.route("/settings")
@login_required
def settings():
pass
When the user is ready to log out:
@app.route("/logout")
@login_required
def logout():
logout_user()
return redirect(somewhere)
They will be logged out, and any cookies for their session will be cleaned up.
Your User Class
The class that you use to represent users needs to implement these methods:
- is_authenticated()
- Returns True if the user is authenticated, i.e. they have provided valid credentials. (Only authenticated users will fulfill the criteria of login_required.)
- is_active()
- Returns True if this is an active user - in addition to being authenticated, they also have activated their account, not been suspended, or any condition your application has for rejecting an account. Inactive accounts may not log in (without being forced of course).
- is_anonymous()
- Returns True if this is an anonymous user. (Actual users should return Falseinstead.)
- get_id()
- Returns a unicode that uniquely identifies this user, and can be used to load the user from the user_loader callback. Note that this must be a unicode - if the ID is natively an int or some other type, you will need to convert it to unicode.
To make implementing a user class easier, you can inherit from UserMixin, which provides default implementations for all of these methods. (It’s not required, though.)
Customizing the Login Process
By default, when a user attempts to access a login_required view without being logged in, Flask-Login will flash a message and redirect them to the log in view. (If the login view is not set, it will abort with a 401 error.)
The name of the log in view can be set as LoginManager.login_view. For example:
login_manager.login_view = "users.login"
The default message flashed is Please log in to access this page. To customize the message, set LoginManager.login_message:
login_manager.login_message = u"Bonvolu ensaluti por uzi tio paĝo."
To customize the message category, set LoginManager.login_message_category:
login_manager.login_message_category = "info"
When the log in view is redirected to, it will have a next variable in the query string, which is the page that the user was trying to access.
If you would like to customize the process further, decorate a function withLoginManager.unauthorized_handler:
@login_manager.unauthorized_handler
def unauthorized():
# do stuff
return a_response
Anonymous Users
By default, when a user is not actually logged in, current_user is set to anAnonymousUserMixin object. It has the following properties:
If you have custom requirements for anonymous users (for example, they need to have a permissions field), you can provide a callable (either a class or factory function) that creates anonymous users to the LoginManager with:
login_manager.anonymous_user = MyAnonymousUser
Remember Me
“Remember Me” functionality can be tricky to implement. However, Flask-Login makes it nearly transparent - just pass remember=True to the login_user call. A cookie will be saved on the user’s computer, and then Flask-Login will automatically restore the user ID from that cookie if it is not in the session. The cookie is tamper-proof, so if the user tampers with it (i.e. inserts someone else’s user ID in place of their own), the cookie will merely be rejected, as if it was not there.
That level of functionality is handled automatically. However, you can (and should, if your application handles any kind of sensitive data) provide additional infrastructure to increase the security of your remember cookies.
Alternative Tokens
Using the user ID as the value of the remember token is not necessarily secure. More secure is a hash of the username and password combined, or something similar. To add an alternative token, add a method to your user objects:
- get_auth_token()
- Returns an authentication token (as unicode) for the user. The auth token should uniquely identify the user, and preferably not be guessable by public information about the user such as their UID and name - nor should it expose such information.
Correspondingly, you should set a token_loader function on the LoginManager, which takes a token (as stored in the cookie) and returns the appropriate User object.
The make_secure_token function is provided for creating auth tokens conveniently. It will concatenate all of its arguments, then HMAC it with the app’s secret key to ensure maximum cryptographic security. (If you store the user’s token in the database permanently, then you may wish to add random data to the token to further impede guessing.)
If your application uses passwords to authenticate users, including the password (or the salted password hash you should be using) in the auth token will ensure that if a user changes their password, their old authentication tokens will cease to be valid.
Fresh Logins
When a user logs in, their session is marked as “fresh,” which indicates that they actually authenticated on that session. When their session is destroyed and they are logged back in with a “remember me” cookie, it is marked as “non-fresh.”login_required does not differentiate between freshness, which is fine for most pages. However, sensitive actions like changing one’s personal information should require a fresh login. (Actions like changing one’s password should always require a password re-entry regardless.)
fresh_login_required, in addition to verifying that the user is logged in, will also ensure that their login is fresh. If not, it will send them to a page where they can re-enter their credentials. You can customize its behavior in the same ways as you can customize login_required, by setting LoginManager.refresh_view,needs_refresh_message, and needs_refresh_message_category:
login_manager.refresh_view = "accounts.reauthenticate"
login_manager.needs_refresh_message = (
u"To protect your account, please reauthenticate to access this page."
)
login_manager.needs_refresh_message_category = "info"
Or by providing your own callback to handle refreshing:
@login_manager.needs_refresh_handler
def refresh():
# do stuff
return a_response
To mark a session as fresh again, call the confirm_login function.
Session Protection
While the features above help secure your “Remember Me” token from cookie thieves, the session cookie is still vulnerable. Flask-Login includes session protection to help prevent your users’ sessions from being stolen.
You can configure session protection on the LoginManager, and in the app’s configuration. If it is enabled, it can operate in either basic or strong mode. To set it on the LoginManager, set the session_protection attribute to "basic" or "strong":
login_manager.session_protection = "strong"
Or, to disable it:
login_manager.session_protection = None
By default, it is activated in "basic" mode. It can be disabled in the app’s configuration by setting the SESSION_PROTECTION setting to None, "basic", or "strong".
When session protection is active, each request, it generates an identifier for the user’s computer (basically, the MD5 hash of the IP address and user agent). If the session does not have an associated identifier, the one generated will be stored. If it has an identifier, and it matches the one generated, then the request is OK.
If the identifiers do not match in basic mode, or when the session is permanent, then the session will simply be marked as non-fresh, and anything requiring a fresh login will force the user to re-authenticate. (Of course, you must be already using fresh logins where appropriate for this to have an effect.)
If the identifiers do not match in strong mode for a non-permanent session, then the entire session (as well as the remember token if it exists) is deleted.
Localization
By default, the LoginManager uses flash to display messages when a user is required to log in. These messages are in English. If you require localization, set thelocalize_callback attribute of LoginManager to a function to be called with these messages before they’re sent to flash, e.g. gettext. This function will be called with the message and its return value will be sent to flash instead.
API Documentation
This documentation is automatically generated from Flask-Login’s source code.
Configuring Login
- class flask.ext.login.LoginManager(app=None,add_context_processor=True)[source]
-
This object is used to hold the settings used for logging in. Instances ofLoginManager are not bound to specific apps, so you can create one in the main body of your code and then bind it to your app in a factory function.
- setup_app(app, add_context_processor=True)[source]
-
This method has been deprecated. Please use LoginManager.init_app()instead.
-
This is called when the user is required to log in. If you register a callback with LoginManager.unauthorized_handler(), then it will be called. Otherwise, it will take the following actions:
- Flash LoginManager.login_message to the user.
- Redirect the user to login_view. (The page they were attempting to access will be passed in the next query string variable, so you can redirect there if present instead of the homepage.)
If LoginManager.login_view is not defined, then it will simply raise a HTTP 401 (Unauthorized) error instead.
This should be returned from a view or before/after_request function, otherwise the redirect will have no effect.
- needs_refresh()[source]
-
This is called when the user is logged in, but they need to be reauthenticated because their session is stale. If you register a callback withneeds_refresh_handler, then it will be called. Otherwise, it will take the following actions:
- Flash LoginManager.needs_refresh_message to the user.
- Redirect the user to LoginManager.refresh_view. (The page they were attempting to access will be passed in the nextquery string variable, so you can redirect there if present instead of the homepage.)
If LoginManager.refresh_view is not defined, then it will simply raise a HTTP 403 (Forbidden) error instead.
This should be returned from a view or before/after_request function, otherwise the redirect will have no effect.
General Configuration
- user_loader(callback)[source]
-
This sets the callback for reloading a user from the session. The function you set should take a user ID (a unicode) and return a user object, or None if the user does not exist.
Parameters: callback (unicode) – The callback for retrieving a user object.
- header_loader(callback)[source]
-
This sets the callback for loading a user from a header value. The function you set should take an authentication token and return a user object, or Noneif the user does not exist.
Parameters: callback – The callback for retrieving a user object.
- token_loader(callback)[source]
-
This sets the callback for loading a user from an authentication token. The function you set should take an authentication token (a unicode, as returned by a user’s get_auth_token method) and return a user object, or None if the user does not exist.
Parameters: callback (unicode) – The callback for retrieving a user object.
- anonymous_user
-
A class or factory function that produces an anonymous user, which is used when no one is logged in.
unauthorized Configuration
- login_view
-
The name of the view to redirect to when the user needs to log in. (This can be an absolute URL as well, if your authentication machinery is external to your application.)
- login_message
-
The message to flash when a user is redirected to the login page.
-
This will set the callback for the unauthorized method, which among other things is used by login_required. It takes no arguments, and should return a response to be sent to the user instead of their normal view.
Parameters: callback (function) – The callback for unauthorized users.
needs_refresh Configuration
- refresh_view
-
The name of the view to redirect to when the user needs to reauthenticate.
- needs_refresh_message
-
The message to flash when a user is redirected to the reauthentication page.
- needs_refresh_handler(callback)[source]
-
This will set the callback for the needs_refresh method, which among other things is used by fresh_login_required. It takes no arguments, and should return a response to be sent to the user instead of their normal view.
Parameters: callback (function) – The callback for unauthorized users.
Login Mechanisms
- flask.ext.login.current_user
-
A proxy for the current user.
- flask.ext.login.login_fresh()[source]
-
This returns True if the current login is fresh.
- flask.ext.login.login_user(user, remember=False, force=False)[source]
-
Logs a user in. You should pass the actual user object to this. If the user’sis_active method returns False, they will not be logged in unless force is True.
This will return True if the log in attempt succeeds, and False if it fails (i.e. because the user is inactive).
Parameters:
- flask.ext.login.logout_user()[source]
-
Logs a user out. (You do not need to pass the actual user.) This will also clean up the remember me cookie if it exists.
- flask.ext.login.confirm_login()[source]
-
This sets the current session as fresh. Sessions become stale when they are reloaded from a cookie.
Protecting Views
- flask.ext.login.login_required(func)[source]
-
If you decorate a view with this, it will ensure that the current user is logged in and authenticated before calling the actual view. (If they are not, it calls theLoginManager.unauthorized callback.) For example:
@app.route('/post') @login_required def post(): pass
If there are only certain times you need to require that your user is logged in, you can do so with:
if not current_user.is_authenticated(): return current_app.login_manager.unauthorized()
...which is essentially the code that this function adds to your views.
It can be convenient to globally turn off authentication when unit testing. To enable this, if either of the application configuration variables LOGIN_DISABLED orTESTING is set to True, this decorator will be ignored.
Parameters: func (function) – The view function to decorate.
- flask.ext.login.fresh_login_required(func)[source]
-
If you decorate a view with this, it will ensure that the current user’s login is fresh - i.e. there session was not restored from a ‘remember me’ cookie. Sensitive operations, like changing a password or e-mail, should be protected with this, to impede the efforts of cookie thieves.
If the user is not authenticated, LoginManager.unauthorized() is called as normal. If they are authenticated, but their session is not fresh, it will callLoginManager.needs_refresh() instead. (In that case, you will need to provide aLoginManager.refresh_view.)
Behaves identically to the login_required() decorator with respect to configutation variables.
Parameters: func (function) – The view function to decorate.
User Object Helpers
- class flask.ext.login.UserMixin[source]
-
This provides default implementations for the methods that Flask-Login expects user objects to have.
Utilities
- flask.ext.login.login_url(login_view, next_url=None, next_field='next')[source]
-
Creates a URL for redirecting to a login page. If only login_view is provided, this will just return the URL for it. If next_url is provided, however, this will append a next=URL parameter to the query string so that the login view can redirect back to that URL.
Parameters:
- flask.ext.login.make_secure_token(*args, **options)[source]
-
This will create a secure token that you can use as an authentication token for your users. It uses heavy-duty HMAC encryption to prevent people from guessing the information. (To make it even more effective, if you will never need to regenerate the token, you can pass some random data as one of the arguments.)
Parameters: - *args – The data to include in the token.
- **options (kwargs) – To manually specify a secret key, passkey=THE_KEY. Otherwise, the current_app secret key will be used.
Signals
See the Flask documentation on signals for information on how to use these signals in your code.
- flask.ext.login.user_logged_in
-
Sent when a user is logged in. In addition to the app (which is the sender), it is passed user, which is the user being logged in.
- flask.ext.login.user_logged_out
-
Sent when a user is logged out. In addition to the app (which is the sender), it is passed user, which is the user being logged out.
- flask.ext.login.user_login_confirmed¶
-
Sent when a user’s login is confirmed, marking it as fresh. (It is not called for a normal login.) It receives no additional arguments besides the app.
-
Sent when the unauthorized method is called on a LoginManager. It receives no additional arguments besides the app.
- flask.ext.login.user_needs_refresh
-
Sent when the needs_refresh method is called on a LoginManager. It receives no additional arguments besides the app.
- flask.ext.login.session_protected
-
Sent whenever session protection takes effect, and a session is either marked non-fresh or deleted. It receives no additional arguments besides the app.
