Python Flask 应用¶

本指南演示如何使用 Authlib OAuth 库，为基于 Flask 框架构建的 Python Web 应用添加 Authany 身份验证。该示例项目的完整源代码可以在 GitHub 仓库中找到。

Learning objectives¶

您将学习以下内容：

如何在 Authany 上创建应用。
如何启用基于邮箱的登录。
为 Flask 应用添加注册和登录功能。

Prerequisites¶

开始之前，您需要准备好以下内容：

一个免费的 Authany 账号。如果还没有账号，请注册。
确保您的机器上安装了 3.10 或更高版本的 Python。
下载并安装 Pip 来管理项目包。

Part 1: Configure Authany¶

要使用 Authany 服务，您需要先在 Authany 管理台中设置一个应用。完成设置后，用户在 Authany 完成身份验证后即可自动登录 Flask 应用。

Step 1: Configure an application¶

要设置应用，请打开 Authany 管理台，在左侧导航栏中选择 Applications（应用）。使用交互式选择器创建一个新的 Authany OIDC 客户端应用，或者选择一个代表您要集成的项目的现有应用。

Authany 中的每个应用都会分配一个由字母数字组成的唯一客户端 ID，您的应用代码会通过 Flask 应用中的 Authlib 客户端库，用它来调用 Authany API。请记下输出结果中生成的 Authany Issuer Domain（例如 example-auth.authgear-apps.com）、CLIENT ID、CLIENT SECRET。第 2 部分配置 Flask 应用时会用到这些值。

Step 2: Configure Redirect URI¶

应用的授权重定向 URI（Authorized Redirect URI）是用户在 Authany 完成身份验证后，Authany 会重定向到的 URL，以完成身份验证流程。在本例中，它是我们 Flask 应用的主页，运行地址为 http://localhost:3000。

在 Authorized Redirect URIs 字段中设置以下地址：http://localhost:3000/callback。如果不设置，用户登录后将无法返回您的应用。

创建好 Authany 应用 后，需要选择用户在登录页面上的身份验证方式。在 Authentication（身份验证） 标签页中进入 Login Methods（登录方式），可以从邮箱、手机号、社交账号、用户名或自定义方式等多种选项中选择一种登录方式。在本示例中，我们选择 Email+Passwordless 方式，用户需要注册账号并使用邮箱登录，登录时会收到发送到邮箱的一次性密码（OTP），验证该验证码后即可使用应用。

Part 2: Create a Flask application¶

接下来，创建一个 Flask 应用，包含一个页面，以及首页、回调、登录和登出流程对应的路由。

Step 1: Configure an .env file ¶

首先在项目目录中创建一个 requirements.txt 文件：

flask>=2.0.3
python-dotenv>=0.19.2
authlib>=1.0
requests>=2.27.1

在命令行界面运行 pip install -r requirements.txt，让 Python 项目能够使用这些依赖。

Step 2: Setup the application ¶

在项目目录中创建一个包含应用逻辑的 server.py 文件，并添加应用所需的库。

import json
from os import environ as env
from urllib.parse import quote_plus, urlencode

from authlib.integrations.flask_client import OAuth
from dotenv import find_dotenv, load_dotenv
from flask import Flask, redirect, render_template, session, url_for

加载配置文件 .env，以便在应用中使用 AUTHGEAR_CLIENT_ID AUTHGEAR_CLIENT_SECRET、AUTHGEAR_DOMAIN 和 APP_SECRET_KEY 等值。

配置 Authlib，基于 OIDC 处理应用与 Authany 之间的身份验证：

oauth = OAuth(app)

oauth.register(
    "authgear",
    client_id=env.get("AUTHGEAR_CLIENT_ID"),
    client_secret=env.get("AUTHGEAR_CLIENT_SECRET"),
    client_kwargs={
        "scope": "openid offline_access",
    },
    server_metadata_url=f'https://{env.get("AUTHGEAR_DOMAIN")}/.well-known/openid-configuration',
)

Step 3: Setup the application routes ¶

访问者访问应用的 /login 路由时，会被重定向到 Authany 以开始身份验证流程。

@app.route("/login")
def login():
    return oauth.authgear.authorize_redirect(
        redirect_uri=url_for("callback", _external=True)
    )

用户通过 Authany 完成登录流程后，会被重定向回应用的 /callback 路由。这个路由会确保用户的会话被保存下来，这样用户后续访问时就不需要再次登录。

@app.route("/callback", methods=["GET", "POST"])
def callback():
    token = oauth.authgear.authorize_access_token()
    session["user"] = token
    return redirect("/")

Refresh Token

调用 Flask Authlib 包的 authorize_access_token() 方法时，只要 Flask 应用的 OAuth 2.0 作用域中包含 offline_access，令牌响应中就会包含刷新令牌。

当前访问令牌过期后，Authlib 还会自动使用刷新令牌获取新的访问令牌。

Logout

/logout 路由负责处理用户从应用登出的流程。它会清除应用内的用户会话，并短暂重定向到 Authany 的登出端点，以确保会话被彻底清除。之后，用户会被导回首页路由（稍后会介绍）。

@app.route("/logout")
def logout():
    session.clear()
    return redirect(
        "https://"
        + env.get("AUTHGEAR_DOMAIN")
        + "/oauth2/end_session"
    )

首页路由会显示已登录用户的详细信息，或者为访问者提供登录选项。

@app.route("/")
def home():
    return render_template(
        "home.html",
        session=session.get("user"),
        pretty=json.dumps(session.get("user"), indent=4),
    )

Step 4: Add UI page ¶

在项目文件夹中新建一个名为 templates 的子目录，并在其中创建 home.html 文件。

<html>
  <head>
    <meta charset="utf-8" />
    <title>Authgear Flak Login Example</title>
  </head>
  <body>
    <div data-gb-custom-block data-tag="if">
    <h1>Welcome {{session.userinfo.name}}!</h1>
    <p><a href="/logout" id="qsLogoutBtn">Logout</a></p>
    <div><pre>{{pretty}}</pre></div>
    <div data-gb-custom-block data-tag="else"></div>
    <h1 id="profileDropDown">Welcome Guest</h1>
    <p><a href="/login" id="qsLoginBtn">Login</a></p>
    </div>
  </body>
</html>

Step 5: Run the application¶

在项目根目录下运行应用：

python server.py

现在可以在浏览器中通过 http://localhost:3000 访问该应用。

Next steps¶

使用 Authany 还可以做更多事情。您可以探索其他登录方式，例如邮件中的魔法链接、社交登录，或 WhatsApp OTP。对于当前应用，您还可以从 Authany 管理台添加更多用户。