为你的 Python Web 应用添加认证 (Authentication)
本指南将向你展示如何将 Logto 集成到你的 Python Web 应用中。
- 示例使用 Flask,但概念对于其他框架是相同的。
- Python 示例项目可在我们的 Python SDK 仓库 中找到。
- Logto SDK 利用协程,调用异步函数时请记得使用
await
。
先决条件
- 一个 Logto Cloud 账户或一个 自托管 Logto。
- 一个已创建的 Logto 传统 Web 应用。
安装
在项目根目录执行:
pip install logto # 或者 `poetry add logto` 或者你使用的其他工具
集成
初始化 LogtoClient
首先,创建一个 Logto 配置:
from logto import LogtoClient, LogtoConfig
client = LogtoClient(
LogtoConfig(
endpoint="https://you-logto-endpoint.app", # 用你的 Logto endpoint 替换
appId="replace-with-your-app-id",
appSecret="replace-with-your-app-secret",
),
)
你可以在管理控制台的应用详情页面找到并复制“应用密钥”:
还可以将默认的内存存储替换为持久存储,例如:
from logto import LogtoClient, LogtoConfig, Storage
from flask import session
from typing import Union
class SessionStorage(Storage):
def get(self, key: str) -> Union[str, None]:
return session.get(key, None)
def set(self, key: str, value: Union[str, None]) -> None:
session[key] = value
def delete(self, key: str) -> None:
session.pop(key, None)
client = LogtoClient(
LogtoConfig(...),
storage=SessionStorage(),
)
查看 Storage 了解更多详情。
配置重定向 URI
在我们深入细节之前,这里是终端用户体验的快速概述。登录过程可以简化如下:
- 你的应用调用登录方法。
- 用户被重定向到 Logto 登录页面。对于原生应用,将打开系统浏览器。
- 用户登录并被重定向回你的应用(配置为重定向 URI)。
关于基于重定向的登录
- 此认证 (Authentication) 过程遵循 OpenID Connect (OIDC) 协议,Logto 强制执行严格的安全措施以保护用户登录。
- 如果你有多个应用程序,可以使用相同的身份提供商 (IdP)(日志 (Logto))。一旦用户登录到一个应用程序,当用户访问另一个应用程序时,Logto 将自动完成登录过程。
要了解有关基于重定向的登录的原理和好处的更多信息,请参阅 Logto 登录体验解释。
在以下代码片段中,我们假设你的应用程序运行在 http://localhost:3000/
。
配置重定向 URI
切换到 Logto Console 的应用详情页面。添加一个重定向 URI http://localhost:3000/callback
。
就像登录一样,用户应该被重定向到 Logto 以注销共享会话。完成后,最好将用户重定向回你的网站。例如,添加 http://localhost:3000/
作为注销后重定向 URI 部分。
然后点击“保存”以保存更改。
实现登录和登出路由
在你的 Web 应用中,添加一个路由来正确处理用户的登录请求。我们以 /sign-in
为例:
@app.route("/sign-in")
async def sign_in():
# 获取登录 URL 并重定向用户到该 URL
return redirect(await client.signIn(
redirectUri="http://localhost:3000/callback",
))
将 http://localhost:3000/callback
替换为你在 Logto Console 中为此应用设置的回调 URL。
如果你想在第一个屏幕显示注册页面,可以将 interactionMode
设置为 signUp
:
@app.route("/sign-in")
async def sign_in():
return redirect(await client.signIn(
redirectUri="http://localhost:3000/callback",
interactionMode="signUp", # 在第一个屏幕显示注册页面
))
现在,每当你的用户访问 http://localhost:3000/sign-in
时,就会启动一个新的登录尝试,并将用户重定向到 Logto 登录页面。
注意 创建一个登录路由并不是启动登录尝试的唯一方法。你可以随时使用
signIn
方法获取登录 URL 并将用户重定向到该 URL。
在用户发出注销请求后,Logto 将清除会话中的所有用户认证 (Authentication) 信息。
要清理 Python 会话和 Logto 会话,可以实现一个注销路由,如下所示:
@app.route("/sign-out")
async def sign_out():
return redirect(
# 在成功注销后将用户重定向到主页
await client.signOut(postLogoutRedirectUri="http://localhost:3000/")
)
处理认证 (Authentication) 状态
在 Logto SDK 中,我们可以使用 client.isAuthenticated()
来检查认证 (Authentication) 状态,如果用户已登录,值将为 true,否则,值将为 false。
这里我们还实现了一个简单的主页用于演示:
- 如果用户未登录,显示一个登录按钮;
- 如果用户已登录,显示一个登出按钮。
@app.route("/")
async def home():
if client.isAuthenticated() is False:
return "未认证 <a href='/sign-in'>登录</a>"
return "已认证 <a href='/sign-out'>登出</a>"
检查点:测试你的应用程序
现在,你可以测试你的应用程序:
- 运行你的应用程序,你将看到登录按钮。
- 点击登录按钮,SDK 将初始化登录过程并将你重定向到 Logto 登录页面。
- 登录后,你将被重定向回你的应用程序,并看到登出按钮。
- 点击登出按钮以清除令牌存储并登出。
获取用户信息
显示用户信息
要显示用户的信息,你可以使用 getIdTokenClaims
方法或 fetchUserInfo
方法来获取用户信息。getIdTokenClaims
返回包含在 ID 令牌中的用户信息,而 fetchUserInfo
从 userinfo 端点获取用户信息。
如你所见,我们使用 @authenticated
装饰器将用户信息上下文带到 Flask 应用程序 API 中。
from functools import wraps
from flask import g, jsonify, redirect
from samples.client import client
def authenticated(shouldRedirect: bool = False, fetchUserInfo: bool = False):
def decorator(func):
@wraps(func)
async def wrapper(*args, **kwargs):
if client.isAuthenticated() is False:
if shouldRedirect:
return redirect("/sign-in")
return jsonify({"error": "Not authenticated"}), 401
# Store user info in Flask application context
g.user = (
await client.fetchUserInfo()
if fetchUserInfo
else client.getIdTokenClaims()
)
return await func(*args, **kwargs)
return wrapper
return decorator
例如,要在 API 中显示用户的信息,你可以使用以下代码:
@app.route("/protected/userinfo")
@authenticated(shouldRedirect=True, fetchUserInfo=True)
async def protectedUserinfo():
try:
return (
"<h2>User info</h2>"
+ g.user.model_dump_json(indent=2, exclude_unset=True).replace("\n", "<br>")
+ navigationHtml
)
except LogtoException as e:
return "<h2>Error</h2>" + str(e) + "<br>" + navigationHtml
我们的数据模型基于 pydantic,所以你可以使用 model_dump_json
将数据模型导出为 JSON。
添加 exclude_unset=True
将从 JSON 输出中排除未设置的字段,使输出更精确。
例如,如果我们在登录时没有请求 email
权限,email
字段将从 JSON 输出中排除。然而,如果我们请求了 email
权限,但用户没有电子邮件地址,email
字段将在 JSON 输出中以 null
值包含。
要了解更多关于权限和声明的信息,请参阅 获取用户信息。
请求额外的声明
你可能会发现从 client.getIdTokenClaims()
返回的对象中缺少一些用户信息。这是因为 OAuth 2.0 和 OpenID Connect (OIDC) 的设计遵循最小权限原则 (PoLP),而 Logto 是基于这些标准构建的。
默认情况下,返回的声明(Claim)是有限的。如果你需要更多信息,可以请求额外的权限(Scope)以访问更多的声明(Claim)。
“声明(Claim)”是关于主体的断言;“权限(Scope)”是一组声明。在当前情况下,声明是关于用户的一条信息。
以下是权限(Scope)与声明(Claim)关系的非规范性示例:
“sub” 声明(Claim)表示“主体(Subject)”,即用户的唯一标识符(例如用户 ID)。
Logto SDK 将始终请求三个权限(Scope):openid
、profile
和 offline_access
。
要请求额外的权限,你可以将权限传递给 LogtoConfig
对象。例如:
from logto import UserInfoScope
client = LogtoClient(
LogtoConfig(
# ...other configurations
scopes = [
UserInfoScope.email,
UserInfoScope.phone,
],
),
storage=SessionStorage(),
)
然后你可以在 client.getIdTokenClaims()
的返回值中访问额外的声明:
idTokenClaims = await client.getIdTokenClaims();
需要网络请求的声明
为了防止 ID 令牌 (ID token) 过大,一些声明需要通过网络请求来获取。例如,即使在权限中请求了 custom_data
声明,它也不会包含在用户对象中。要访问这些声明,你可以使用 client.fetchUserInfo()
方法:
(await client.fetchUserInfo()).custom_data
权限和声明
Logto 使用 OIDC 权限和声明约定 来定义从 ID 令牌和 OIDC 用户信息端点检索用户信息的权限和声明。“权限”和“声明”都是 OAuth 2.0 和 OpenID Connect (OIDC) 规范中的术语。
以下是支持的权限 (Scopes) 列表及相应的声明 (Claims):
openid
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
sub | string | 用户的唯一标识符 | 否 |
profile
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
name | string | 用户的全名 | 否 |
username | string | 用户名 | 否 |
picture | string | 终端用户的个人资料图片的 URL。此 URL 必须指向一个图像文件(例如 PNG、JPEG 或 GIF 图像文件),而不是包含图像的网页。请注意,此 URL 应特别引用适合在描述终端用户时显示的终端用户的个人资料照片,而不是终端用户拍摄的任意照片。 | 否 |
created_at | number | 终端用户创建的时间。时间表示为自 Unix 纪元(1970-01-01T00:00:00Z)以来的毫秒数。 | 否 |
updated_at | number | 终端用户信息最后更新的时间。时间表示为自 Unix 纪元(1970-01-01T00:00:00Z)以来的毫秒数。 | 否 |
其他 标准声明 包括 family_name
、given_name
、middle_name
、nickname
、preferred_username
、profile
、website
、gender
、birthdate
、zoneinfo
和 locale
也将包含在 profile
权限中,无需请求用户信息端点。与上述声明的区别在于,这些声明只有在其值不为空时才会返回,而上述声明在值为空时将返回 null
。
与标准声明不同,created_at
和 updated_at
声明使用毫秒而不是秒。
email
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
string | 用户的电子邮件地址 | 否 | |
email_verified | boolean | 电子邮件地址是否已验证 | 否 |
phone
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
phone_number | string | 用户的电话号码 | 否 |
phone_number_verified | boolean | 电话号码是否已验证 | 否 |
address
有关地址声明的详细信息,请参阅 OpenID Connect Core 1.0。
custom_data
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
custom_data | object | 用户的自定义数据 | 是 |
identities
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
identities | object | 用户的关联身份 | 是 |
sso_identities | array | 用户的关联 SSO 身份 | 是 |
roles
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
roles | string[] | 用户的角色 | 否 |
urn:logto:scope:organizations
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
organizations | string[] | 用户所属的组织 ID | 否 |
organization_data | object[] | 用户所属的组织数据 | 是 |
urn:logto:scope:organization_roles
声明名称 | 类型 | 描述 | 需要用户信息吗? |
---|---|---|---|
organization_roles | string[] | 用户所属的组织角色,格式为 <organization_id>:<role_name> | 否 |
考虑到性能和数据大小,如果“需要用户信息吗?”为“是”,则表示声明不会显示在 ID 令牌中,而会在 用户信息端点 响应中返回。
API 资源和组织 (Organizations)
我们建议首先阅读 🔐 基于角色的访问控制 (RBAC),以了解 Logto RBAC 的基本概念以及如何正确设置 API 资源。
配置 Logto 客户端
一旦你设置了 API 资源,就可以在应用中配置 Logto 时添加它们:
client = LogtoClient(
LogtoConfig(
# ...other configs
resources=["https://shopping.your-app.com/api", "https://store.your-app.com/api"], # 添加 API 资源 (API resources)
),
)
每个 API 资源都有其自己的权限(权限)。
例如,https://shopping.your-app.com/api
资源具有 shopping:read
和 shopping:write
权限,而 https://store.your-app.com/api
资源具有 store:read
和 store:write
权限。
要请求这些权限,你可以在应用中配置 Logto 时添加它们:
client = LogtoClient(
LogtoConfig(
# ...other configs
scopes=["shopping:read", "shopping:write", "store:read", "store:write"],
resources=["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
),
)
你可能会注意到权限是与 API 资源分开定义的。这是因为 OAuth 2.0 的资源指示器 指定请求的最终权限将是所有目标服务中所有权限的笛卡尔积。
因此,在上述情况下,权限可以从 Logto 中的定义简化,两个 API 资源都可以拥有 read
和 write
权限,而无需前缀。然后,在 Logto 配置中:
client = LogtoClient(
LogtoConfig(
# ...other configs
scopes=["read", "write"],
resources=["https://shopping.your-app.com/api", "https://store.your-app.com/api"],
),
)
对于每个 API 资源,它将请求 read
和 write
权限。
请求 API 资源中未定义的权限是可以的。例如,即使 API 资源没有可用的 email
权限,你也可以请求 email
权限。不可用的权限将被安全地忽略。
成功登录后,Logto 将根据用户的角色向 API 资源发布适当的权限。
为 API 资源获取访问令牌
要获取特定 API 资源的访问令牌 (access token),你可以使用 获取访问令牌 (Access token)
方法:
accessToken = await client.getAccessToken("https://shopping.your-app.com/api")
# 或者
claims = await client.getAccessTokenClaims("https://shopping.your-app.com/api")
此方法将返回一个 JWT 访问令牌 (access token),当用户具有相关权限时,可以用来访问 API 资源。如果当前缓存的访问令牌 (access token) 已过期,此方法将自动尝试使用刷新令牌 (refresh token) 获取新的访问令牌 (access token)。
获取组织令牌
如果你对组织不熟悉,请阅读 🏢 组织(多租户) 以开始了解。
在配置 Logto 客户端时,你需要添加 core.UserScopeOrganizations
权限:
from logto import LogtoClient, LogtoConfig, UserInfoScope
client = LogtoClient(
LogtoConfig(
# ...other configs
scopes=[UserInfoScope.organizations],
),
)
用户登录后,你可以获取用户的组织令牌:
# 将参数替换为有效的组织 (Organization) ID。
# 用户的有效组织 (Organization) ID 可以在 ID 令牌 (ID token) 声明 (claim) `organizations` 中找到。
organizationToken = await client.getOrganizationToken(organization_id)
# 或者
organizationTokenClaims = await client.getOrganizationTokenClaims(organization_id)