Flask Login 中文文檔 · Flask 擴展文檔匯總

{% raw %} # Flask-Login Flask-Login 為 Flask 提供了用戶會話管理。它處理了日常的登入，登出并且長時間記住用戶的會話。它會: * 在會話中存儲當前活躍的用戶 ID，讓你能夠自由地登入和登出。 * 讓你限制登入(或者登出)用戶可以訪問的視圖。 * 處理讓人棘手的 “記住我” 功能。 * 幫助你保護用戶會話免遭 cookie 被盜的牽連。 * 可以與以后可能使用的 Flask-Principal 或其它認證擴展集成。但是，它不會: * 限制你使用特定的數據庫或其它存儲方法。如何加載用戶完全由你決定。 * 限制你使用用戶名和密碼，OpenIDs，或者其它的認證方法。 * 處理超越 “登入或者登出” 之外的權限。 * 處理用戶注冊或者賬號恢復。 * [配置你的應用](#id1) * [它是如何工作](#id2) * [你的用戶類](#id3) * [Login 示例](#login) * [定制登入過程](#id4) * [使用授權頭(Authorization header)登錄](#authorization-header) * [使用 Request Loader 定制登錄](#request-loader) * [匿名用戶](#id5) * [記住我](#id6) * [可選令牌](#id7) * [”新鮮的“登錄(Fresh Logins)](#fresh-logins) * [Cookie 設置](#cookie) * [會話保護](#id8) * [本地化](#id9) * [API 文檔](#api) * [配置登錄](#id10) * [登錄機制](#id11) * [保護視圖](#id12) * [用戶對象助手](#id13) * [工具](#id14) * [信號](#id15) ## 配置你的應用對一個使用 Flask-Login 的應用最重要的一部分就是 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 類。你應該在你的代碼的某處為應用創建一個，像這樣: ``` login_manager = LoginManager() ``` 登錄管理(login manager)包含了讓你的應用和 Flask-Login 協同工作的代碼，比如怎樣從一個 ID 加載用戶，當用戶需要登錄的時候跳轉到哪里等等。一旦實際的應用對象創建后，你能夠這樣配置它來實現登錄: ``` login_manager.init_app(app) ``` ## 它是如何工作你必須提供一個 [`user_loader`](#flask.ext.login.LoginManager.user_loader "flask.ext.login.LoginManager.user_loader") 回調。這個回調用于從會話中存儲的用戶 ID 重新加載用戶對象。它應該接受一個用戶的 [`unicode`](http://docs.python.org/library/functions.html#unicode "(in Python v2.7)") ID 作為參數，并且返回相應的用戶對象。比如: ``` @login_manager.user_loader def load_user(userid): return User.get(userid) ``` 如果 ID 無效的話，它應該返回 [`None`](http://docs.python.org/library/constants.html#None "(in Python v2.7)") (**而不是拋出異常**)。(在這種情況下，ID 會被手動從會話中移除且處理會繼續) ## 你的用戶類你用來表示用戶的類需要實現這些屬性和方法: `is_authenticated` 當用戶通過驗證時，也即提供有效證明時返回 [`True`](http://docs.python.org/library/constants.html#True "(in Python v2.7)") 。（只有通過驗證的用戶會滿足 [`login_required`](#flask.ext.login.login_required "flask.ext.login.login_required") 的條件。） `is_active` 如果這是一個活動用戶且通過驗證，賬戶也已激活，未被停用，也不符合任何你的應用拒絕一個賬號的條件，返回 [`True`](http://docs.python.org/library/constants.html#True "(in Python v2.7)") 。不活動的賬號可能不會登入（當然，是在沒被強制的情況下）。 `is_anonymous` 如果是一個匿名用戶，返回 [`True`](http://docs.python.org/library/constants.html#True "(in Python v2.7)") 。（真實用戶應返回 [`False`](http://docs.python.org/library/constants.html#False "(in Python v2.7)") 。） `get_id()` 返回一個能唯一識別用戶的，并能用于從 [`user_loader`](#flask.ext.login.LoginManager.user_loader "flask.ext.login.LoginManager.user_loader") 回調中加載用戶的 [`unicode`](http://docs.python.org/library/functions.html#unicode "(in Python v2.7)") 。注意著 **必須** 是一個 [`unicode`](http://docs.python.org/library/functions.html#unicode "(in Python v2.7)") —— 如果 ID 原本是一個 [`int`](http://docs.python.org/library/functions.html#int "(in Python v2.7)") 或其它類型，你需要把它轉換為 [`unicode`](http://docs.python.org/library/functions.html#unicode "(in Python v2.7)") 。要簡便地實現用戶類，你可以從 [`UserMixin`](#flask.ext.login.UserMixin "flask.ext.login.UserMixin") 繼承，它提供了對所有這些方法的默認實現。（雖然這不是必須的。） ## Login 示例一旦用戶通過驗證，你可以使用 [`login_user`](#flask.ext.login.login_user "flask.ext.login.login_user") 函數讓用戶登錄。例如: ``` @app.route('/login', methods=['GET', 'POST']) def login(): # Here we use a class of some kind to represent and validate our # client-side form data. For example, WTForms is a library that will # handle this for us, and we use a custom LoginForm to validate. form = LoginForm() if form.validate_on_submit(): # Login and validate the user. # user should be an instance of your `User` class login_user(user) flask.flash('Logged in successfully.') next = flask.request.args.get('next') # next_is_valid should check if the user has valid # permission to access the `next` url if not next_is_valid(next): return flask.abort(400) return flask.redirect(next or flask.url_for('index')) return flask.render_template('login.html', form=form) ``` _警告:_ 你必須驗證 [`next`](http://docs.python.org/library/functions.html#next "(in Python v2.7)") 參數的值。如果不驗證的話，你的應用將會受到重定向的攻擊。就這么簡單。你可用使用 [`current_user`](#flask.ext.login.current_user "flask.ext.login.current_user") 代理來訪問登錄的用戶，在每一個模板中都可以使用 [`current_user`](#flask.ext.login.current_user "flask.ext.login.current_user"): ``` {% if current_user.is_authenticated() %} Hi {{ current_user.name }}! {% endif %} ``` 需要用戶登入的視圖可以用 [`login_required`](#flask.ext.login.login_required "flask.ext.login.login_required") 裝飾器來裝飾: ``` @app.route("/settings") @login_required def settings(): pass ``` 當用戶要登出時: ``` @app.route("/logout") @login_required def logout(): logout_user() return redirect(somewhere) ``` 他們會被登出，且他們會話產生的任何 cookie 都會被清理干凈。 ## 定制登入過程默認情況下，當未登錄的用戶嘗試訪問一個 [`login_required`](#flask.ext.login.login_required "flask.ext.login.login_required") 裝飾的視圖，Flask-Login 會閃現一條消息并且重定向到登錄視圖。(如果未設置登錄視圖，它將會以 401 錯誤退出。) 登錄視圖的名稱可以設置成 [`LoginManager.login_view`](#flask.ext.login.LoginManager.login_view "flask.ext.login.LoginManager.login_view")。例如: ``` login_manager.login_view = "users.login" ``` 默認的閃現消息是 `Please log in to access this page.`。要自定義該信息，請設置 [`LoginManager.login_message`](#flask.ext.login.LoginManager.login_message "flask.ext.login.LoginManager.login_message"): ``` login_manager.login_message = u"Bonvolu ensaluti por uzi tio pa臐o." ``` 要自定義消息分類的話，請設置 `LoginManager.login_message_category`: ``` login_manager.login_message_category = "info" ``` 當重定向到登入視圖，它的請求字符串中會有一個 `next` 變量，其值為用戶之前訪問的頁面。如果你想要進一步自定義登入過程，請使用 [`LoginManager.unauthorized_handler`](#flask.ext.login.LoginManager.unauthorized_handler "flask.ext.login.LoginManager.unauthorized_handler") 裝飾函數: ``` @login_manager.unauthorized_handler def unauthorized(): # do stuff return a_response ``` ## 使用授權頭(Authorization header)登錄 Caution 該方法將會被棄用，使用下一節的 `request_loader` 來代替。有些時候你要支持使用 `Authorization` 頭的基本認證登錄，比如 API 請求。為了支持通過頭登錄你需要提供一個 [`header_loader`](#flask.ext.login.LoginManager.header_loader "flask.ext.login.LoginManager.header_loader") 回調。這個回調和 [`user_loader`](#flask.ext.login.LoginManager.user_loader "flask.ext.login.LoginManager.user_loader") 回調作用一樣，只是它接受一個 HTTP 頭(Authorization)而不是用戶 id。例如: ``` @login_manager.header_loader def load_user_from_header(header_val): header_val = header_val.replace('Basic ', '', 1) try: header_val = base64.b64decode(header_val) except TypeError: pass return User.query.filter_by(api_key=header_val).first() ``` 默認情況下 `Authorization` 的值傳給 [`header_loader`](#flask.ext.login.LoginManager.header_loader "flask.ext.login.LoginManager.header_loader") 回調。你可以使用 `AUTH_HEADER_NAME` 配置來修改使用的 HTTP 頭(可以不使用 `Authorization`，使用 `Token`)。 ## 使用 Request Loader 定制登錄有時你想要不使用 cookies 情況下登錄用戶，比如使用 HTTP 頭或者一個作為查詢參數的 api 密鑰。這種情況下，你應該使用 `request_loader` 回調。這個回調和 [`user_loader`](#flask.ext.login.LoginManager.user_loader "flask.ext.login.LoginManager.user_loader") 回調作用一樣，但是 [`user_loader`](#flask.ext.login.LoginManager.user_loader "flask.ext.login.LoginManager.user_loader") 回調只接受 Flask 請求而不是一個 user_id。例如，為了同時支持一個 url 參數和使用 `Authorization` 頭的基本用戶認證的登錄: ``` @login_manager.request_loader def load_user_from_request(request): # first, try to login using the api_key url arg api_key = request.args.get('api_key') if api_key: user = User.query.filter_by(api_key=api_key).first() if user: return user # next, try to login using Basic Auth api_key = request.headers.get('Authorization') if api_key: api_key = api_key.replace('Basic ', '', 1) try: api_key = base64.b64decode(api_key) except TypeError: pass user = User.query.filter_by(api_key=api_key).first() if user: return user # finally, return None if both methods did not login the user return None ``` ## 匿名用戶默認情況下，當一個用戶沒有真正地登錄，[`current_user`](#flask.ext.login.current_user "flask.ext.login.current_user") 被設置成一個 `AnonymousUserMixin` 對象。它由如下的屬性和方法: * `is_active` 和 `is_authenticated` 的值為 [`False`](http://docs.python.org/library/constants.html#False "(in Python v2.7)") * `is_anonymous` 的值為 [`True`](http://docs.python.org/library/constants.html#True "(in Python v2.7)") * `get_id()` 返回 [`None`](http://docs.python.org/library/constants.html#None "(in Python v2.7)") 如果需要為匿名用戶定制一些需求(比如，需要一個權限域)，你可以向 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 提供一個創建匿名用戶的回調（類或工廠函數）: ``` login_manager.anonymous_user = MyAnonymousUser ``` ## 記住我 “記住我”的功能很難實現。但是，Flask-Login 幾乎透明地實現它 - 只要把 `remember=True` 傳遞給 [`login_user`](#flask.ext.login.login_user "flask.ext.login.login_user")。一個 cookie 將會存儲在用戶計算機中，如果用戶會話中沒有用戶 ID 的話，Flask-Login 會自動地從 cookie 中恢復用戶 ID。cookie 是防纂改的，因此如果用戶纂改過它(比如，使用其它的一些東西來代替用戶的 ID)，它就會被拒絕，就像不存在。該層功能是被自動實現的。但你能（且應該，如果你的應用處理任何敏感的數據）提供額外基礎工作來增強你記住的 cookie 的安全性。 ### 可選令牌使用用戶 ID 作為記住的令牌值不一定是安全的。更安全的方法是使用用戶名和密碼聯合的 hash 值，或類似的東西。要添加一個額外的令牌，向你的用戶對象添加一個方法： `get_auth_token()` 返回用戶的認證令牌（返回為 [`unicode`](http://docs.python.org/library/functions.html#unicode "(in Python v2.7)") ）。這個認證令牌應能唯一識別用戶，且不易通過用戶的公開信息，如 UID 和名稱來猜測出——同樣也不應暴露這些信息。相應地，你應該在 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 上設置一個 [`token_loader`](#flask.ext.login.LoginManager.token_loader "flask.ext.login.LoginManager.token_loader") 函數，它接受令牌（存儲在 cookie 中）作為參數并返回合適的 User 對象。 [`make_secure_token`](#flask.ext.login.make_secure_token "flask.ext.login.make_secure_token") 函數用于便利創建認證令牌。它會連接所有的參數，然后用應用的密鑰來 HMAC 它確保最大的密碼學安全。（如果你永久地在數據庫中存儲用戶令牌，那么你會希望向令牌中添加隨機數據來阻礙猜測。）如果你的應用使用密碼來驗證用戶，在認證令牌中包含密碼（或你應使用的加鹽值的密碼 hash ）能確保若用戶更改密碼，他們的舊認證令牌會失效。 ### ”新鮮的“登錄(Fresh Logins) 當用戶登入，他們的會話被標記成“新鮮的”，就是說在這個會話只中用戶實際上登錄過。當會話銷毀用戶使用“記住我”的 cookie 重新登入，會話被標記成“非新鮮的”。[`login_required`](#flask.ext.login.login_required "flask.ext.login.login_required") 并不在意它們之間的不同，這適用于大部分頁面。然而，更改某人的個人信息這樣的敏感操作應需要一個“新鮮的”的登入。（像修改密碼這樣的操作總是需要密碼，無論是否重登入。） [`fresh_login_required`](#flask.ext.login.fresh_login_required "flask.ext.login.fresh_login_required")，除了驗證用戶登錄，也將確保他們的登錄是“新鮮的”。如果不是“新鮮的”，它會把用戶送到可以重輸入驗證條件的頁面。你可以定制 [`fresh_login_required`](#flask.ext.login.fresh_login_required "flask.ext.login.fresh_login_required") 就像定制 [`login_required`](#flask.ext.login.login_required "flask.ext.login.login_required") 那樣，通過設置 [`LoginManager.refresh_view`](#flask.ext.login.LoginManager.refresh_view "flask.ext.login.LoginManager.refresh_view")，[`needs_refresh_message`](#flask.ext.login.LoginManager.needs_refresh_message "flask.ext.login.LoginManager.needs_refresh_message")，和 `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" ``` 或者提供自己的回調來處理“非新鮮的”刷新: ``` @login_manager.needs_refresh_handler def refresh(): # do stuff return a_response ``` 調用 [`confirm_login`](#flask.ext.login.confirm_login "flask.ext.login.confirm_login") 函數可以重新標記會話為”新鮮“。 ### Cookie 設置 cookie 的細節可以在應用設置中定義。 | | | | --- | --- | | `REMEMBER_COOKIE_NAME` | 存儲“記住我”信息的 cookie 名。 **默認值**： remember_token | | `REMEMBER_COOKIE_DURATION` | cookie 過期時間，為一個 [`datetime.timedelta`](http://docs.python.org/library/datetime.html#datetime.timedelta "(in Python v2.7)") 對象。 **默認值：** 365 天 (1 非閏陽歷年) | | `REMEMBER_COOKIE_DOMAIN` | 如果“記住我” cookie 應跨域，在此處設置域名值（即 .example.com 會允許 example 下所有子域名）。 **默認值：** None | | `REMEMBER_COOKIE_PATH` | 限制”記住我“ cookie 存儲到某一路徑下。 **默認值：** `/` | | `REMEMBER_COOKIE_SECURE` | 限制 “Remember Me” cookie 在某些安全通道下有用（典型地 HTTPS）。**默認值：** [`None`](http://docs.python.org/library/constants.html#None "(in Python v2.7)") | | `REMEMBER_COOKIE_HTTPONLY` | 保護 “Remember Me” cookie 不能通過客戶端腳本訪問。 **默認值：** [`False`](http://docs.python.org/library/constants.html#False "(in Python v2.7)") | ## 會話保護當上述特性保護“記住我”令牌免遭 cookie 竊取時，會話 cookie 仍然是脆弱的。 Flask-Login 包含了會話保護來幫助阻止用戶會話被盜用。你可以在 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 上和應用配置中配置會話保護。如果它被啟用，它可以在 `basic` 或 `strong` 兩種模式中運行。要在 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 上設置它，設置 `session_protection` 屬性為 `"basic"` 或 `"strong"`: ``` login_manager.session_protection = "strong" ``` 或者，禁用它: ``` login_manager.session_protection = None ``` 默認，它被激活為 `"basic"` 模式。它可以在應用配置中設定 `SESSION_PROTECTION` 為 [`None`](http://docs.python.org/library/constants.html#None "(in Python v2.7)") 、 `"basic"` 或 `"strong"` 來禁用。當啟用了會話保護，每個請求，它生成一個用戶電腦的標識（基本上是 IP 地址和 User Agent 的 MD5 hash 值）。如果會話不包含相關的標識，則存儲生成的。如果存在標識，則匹配生成的，之后請求可用。在 `basic` 模式下或會話是永久的，如果該標識未匹配，會話會簡單地被標記為非活躍的，且任何需要活躍登入的東西會強制用戶重新驗證。（當然，你必須已經使用了活躍登入機制才能奏效。）在 `strong` 模式下的非永久會話，如果該標識未匹配，整個會話（記住的令牌如果存在，則同樣）被刪除。 ## 本地化默認情況下，當用戶需要登錄，[`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 使用 `flash` 來顯示信息。這些信息都是英文的。如果你需要本地化，設置 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 的 `localize_callback` 屬性為一個函數，該函數在消息被發送到 `flash` 的時候被調用，比如，`gettext`。 ## API 文檔這部分文檔是從 Flask-Login 源碼中自動生成的。 ### 配置登錄 `class flask.ext.login.LoginManager(app=None, add_context_processor=True)` This object is used to hold the settings used for logging in. Instances of [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 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)` This method has been deprecated. Please use `LoginManager.init_app()` instead. `unauthorized()` This is called when the user is required to log in. If you register a callback with [`LoginManager.unauthorized_handler()`](#flask.ext.login.LoginManager.unauthorized_handler "flask.ext.login.LoginManager.unauthorized_handler"), then it will be called. Otherwise, it will take the following actions: * Flash [`LoginManager.login_message`](#flask.ext.login.LoginManager.login_message "flask.ext.login.LoginManager.login_message") to the user. * If the app is using blueprints find the login view for the current blueprint using `blueprint_login_views`. If the app is not using blueprints or the login view for the current blueprint is not specified use the value of [`login_view`](#flask.ext.login.LoginManager.login_view "flask.ext.login.LoginManager.login_view"). Redirect the user to the 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`](#flask.ext.login.LoginManager.login_view "flask.ext.login.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()` 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 with [`needs_refresh_handler`](#flask.ext.login.LoginManager.needs_refresh_handler "flask.ext.login.LoginManager.needs_refresh_handler"), then it will be called. Otherwise, it will take the following actions: * Flash [`LoginManager.needs_refresh_message`](#flask.ext.login.LoginManager.needs_refresh_message "flask.ext.login.LoginManager.needs_refresh_message") to the user. * Redirect the user to [`LoginManager.refresh_view`](#flask.ext.login.LoginManager.refresh_view "flask.ext.login.LoginManager.refresh_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.refresh_view`](#flask.ext.login.LoginManager.refresh_view "flask.ext.login.LoginManager.refresh_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. General Configuration `user_loader(callback)` 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** ([_callable_](http://docs.python.org/library/functions.html#callable "(in Python v2.7)")) – The callback for retrieving a user object. `header_loader(callback)` 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 [`None`](http://docs.python.org/library/constants.html#None "(in Python v2.7)") if the user does not exist. Parameters: **callback** ([_callable_](http://docs.python.org/library/functions.html#callable "(in Python v2.7)")) – The callback for retrieving a user object. `token_loader(callback)` 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** ([_callable_](http://docs.python.org/library/functions.html#callable "(in Python v2.7)")) – 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`](#flask.ext.login.LoginManager.unauthorized "flask.ext.login.LoginManager.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. `unauthorized_handler(callback)` This will set the callback for the [`unauthorized`](#flask.ext.login.LoginManager.unauthorized "flask.ext.login.LoginManager.unauthorized") method, which among other things is used by [`login_required`](#flask.ext.login.login_required "flask.ext.login.login_required"). It takes no arguments, and should return a response to be sent to the user instead of their normal view. Parameters: **callback** ([_callable_](http://docs.python.org/library/functions.html#callable "(in Python v2.7)")) – The callback for unauthorized users. [`needs_refresh`](#flask.ext.login.LoginManager.needs_refresh "flask.ext.login.LoginManager.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)` This will set the callback for the [`needs_refresh`](#flask.ext.login.LoginManager.needs_refresh "flask.ext.login.LoginManager.needs_refresh") method, which among other things is used by [`fresh_login_required`](#flask.ext.login.fresh_login_required "flask.ext.login.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** ([_callable_](http://docs.python.org/library/functions.html#callable "(in Python v2.7)")) – The callback for unauthorized users. ### 登錄機制 `flask.ext.login.current_user` A proxy for the current user. `flask.ext.login.login_fresh()` This returns `True` if the current login is fresh. `flask.ext.login.login_user(user, remember=False, force=False, fresh=True)` Logs a user in. You should pass the actual user object to this. If the user’s `is_active` property is `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: * **user** ([_object_](http://docs.python.org/library/functions.html#object "(in Python v2.7)")) – The user object to log in. * **remember** ([_bool_](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – Whether to remember the user after their session expires. Defaults to `False`. * **force** ([_bool_](http://docs.python.org/library/functions.html#bool "(in Python v2.7)")) – If the user is inactive, setting this to `True` will log them in regardless. Defaults to `False`. * **fresh** – setting this to `False` will log in the user with a session marked as not “fresh”. Defaults to `True`. :type fresh: bool `flask.ext.login.logout_user()` 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. `lask.ext.login.confirm_login()` This sets the current session as fresh. Sessions become stale when they are reloaded from a cookie. ### 保護視圖 `flask.ext.login.login_required(func)` 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 the [`LoginManager.unauthorized`](#flask.ext.login.LoginManager.unauthorized "flask.ext.login.LoginManager.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 the application configuration variable `LOGIN_DISABLED` is set to [`True`](http://docs.python.org/library/constants.html#True "(in Python v2.7)"), this decorator will be ignored. Parameters: **func** (_function_) – The view function to decorate. `flask.ext.login.fresh_login_required(func)` 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()`](#flask.ext.login.LoginManager.unauthorized "flask.ext.login.LoginManager.unauthorized") is called as normal. If they are authenticated, but their session is not fresh, it will call [`LoginManager.needs_refresh()`](#flask.ext.login.LoginManager.needs_refresh "flask.ext.login.LoginManager.needs_refresh") instead. (In that case, you will need to provide a [`LoginManager.refresh_view`](#flask.ext.login.LoginManager.refresh_view "flask.ext.login.LoginManager.refresh_view").) Behaves identically to the [`login_required()`](#flask.ext.login.login_required "flask.ext.login.login_required") decorator with respect to configutation variables. Parameters: **func** (_function_) – The view function to decorate. ### 用戶對象助手 `class flask.ext.login.UserMixin` This provides default implementations for the methods that Flask-Login expects user objects to have. ### 工具 `flask.ext.login.login_url(login_view, next_url=None, next_field='next')` 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: * **login_view** ([_str_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – The name of the login view. (Alternately, the actual URL to the login view.) * **next_url** ([_str_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – The URL to give the login view for redirection. * **next_field** ([_str_](http://docs.python.org/library/functions.html#str "(in Python v2.7)")) – What field to store the next URL in. (It defaults to `next`.) `flask.ext.login.make_secure_token(*args, **options)` 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, pass `key=THE_KEY`. Otherwise, the `current_app` secret key will be used. ### 信號如何在你的代碼中使用這些信號請參閱 [Flask documentation on signals](http://flask.pocoo.org/docs/signals/)。 `flask.ext.login.user_logged_in` 當一個用戶登入的時候發出。除應用（信號的發送者）之外，它還傳遞正登入的用戶 [`user`](http://docs.python.org/library/user.html#module-user "(in Python v2.7)") 。 `flask.ext.login.user_logged_out` 當一個用戶登出的時候發出。除應用（信號的發送者）之外，它還傳遞正登出的用戶 [`user`](http://docs.python.org/library/user.html#module-user "(in Python v2.7)") 。 `flask.ext.login.user_login_confirmed` 當用戶的登入被證實，把它標記為活躍的。（它不用于常規登入的調用。）它不接受應用以外的任何其它參數。 `flask.ext.login.user_unauthorized` 當 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 上的 `unauthorized` 方法被調用時發出。它不接受應用以外的任何其它參數。 `flask.ext.login.user_needs_refresh` 當 [`LoginManager`](#flask.ext.login.LoginManager "flask.ext.login.LoginManager") 上的 `needs_refresh` 方法被調用時發出。它不接受應用以外的任何其它參數。 `flask.ext.login.session_protected` 當會話保護起作用時，且會話被標記為非活躍或刪除時發出。它不接受應用以外的任何其它參數。 {% endraw %}