django-allauth 集成 Figma 第三方登录：应用注册、回调配置与 OAuth2 源码实现解析-平芜编程栈

后端
认证鉴权
身份认证

【免费下载链接】django-allauth

Integrated set of Django applications addressing authentication, registration, account management as well as 3rd party (social) account authentication. 🔁 Mirror of https://codeberg.org/allauth/django-allauth/

项目地址：https://gitcode.com/gh_mirrors/dj/django-allauth

点击查看免费下载

本指南以 django-allauth 仓库中 docs/socialaccount/providers/figma.rst 为骨架，完整讲解如何为 Django 项目接入 Figma 第三方登录：从 Figma 开发者平台注册应用、获取 Client ID/Secret、配置回调地址，到启用figmaprovider、完成登录与账号绑定。读完本文，你将能独立完成 Figma OAuth2 登录的最小可用配置，并理解其底层调用链与用户数据提取逻辑。

一、前置准备：在 Figma 开发者平台注册应用

接入 Figma OAuth2 的第一步是在 Figma 官方开发者平台创建 OAuth 应用，以获取后续配置所必需的Client ID（key）与Client Secret（secret）。原文档明确指出应用注册入口为：

应用注册地址（获取 key 和 secret）：https://www.figma.com/developers/apps

创建应用时，平台会要求你填写应用名称、重定向（回调）地址等基本信息。注册完成后，妥善保存页面上展示的 Client ID 与 Client Secret——它们将分别作为 django-allauth 侧SOCIALACCOUNT_PROVIDERS配置中的client_id与secret字段。

二、开发环境回调地址

OAuth2 授权码流程要求第三方平台在授权完成后将用户重定向回你的站点，因此必须在 Figma 应用配置中登记回调地址。原文档给出的开发环境回调 URL 为：

http://localhost:8000/accounts/figma/login/callback/

该地址由两部分组成：

站点根地址http://localhost:8000（对应本地 Django 开发服务器默认端口，若使用其他端口需同步修改）；
回调路径/accounts/figma/login/callback/，由 django-allauth 的 URL 路由自动生成（见下文“路由与回调链路”一节），无需手工编写视图。

生产环境部署时，将http://localhost:8000替换为你的正式域名，并在 Figma 开发者平台中同步登记该生产回调地址；任何未登记的地址都会在授权回调时被 Figma 拒绝。

三、启用 Figma Provider

1. 安装并注册应用

django-allauth 将 Figma 登录能力封装为独立的 Django 应用allauth.socialaccount.providers.figma，启用方式是在INSTALLED_APPS中加入该应用。参考仓库 docs/installation/quickstart.rst 的完整安装清单，示例配置如下：

INSTALLED_APPS = [ "django.contrib.admin", "django.contrib.auth", "django.contrib.contenttypes", "django.contrib.sessions", "django.contrib.messages", "django.contrib.sites", # allauth 核心 "allauth", "allauth.account", "allauth.socialaccount", # 第三方提供商 "allauth.socialaccount.providers.figma", ]

随后执行数据迁移，创建社交账户相关数据表：

python manage.py migrate

2. 配置 Provider 凭据

在 Django 设置文件中通过SOCIALACCOUNT_PROVIDERS字典配置 Figma 应用凭据（该设置项的完整说明参见 docs/socialaccount/configuration.rst）：

SOCIALACCOUNT_PROVIDERS = { "figma": { "APP": { "client_id": "你的-Figma-Client-ID", "secret": "你的-Figma-Client-Secret", } } }

client_id与secret即第一步在 Figma 开发者平台获取的 key 与 secret。也可以不在此处硬编码，而是通过 Django Admin 的“社交应用（Social applications）”管理界面创建SocialApp记录（provider 选择Figma），并将站点关联到该应用——两种方式最终都会为授权流程提供相同的凭据。

四、URL 路由与登录入口

Figma 登录无需手工编写视图或路由。仓库中 allauth/socialaccount/providers/figma/urls.py 仅有如下内容：

from allauth.socialaccount.providers.figma.provider import FigmaProvider from allauth.socialaccount.providers.oauth2.urls import default_urlpatterns urlpatterns = default_urlpatterns(FigmaProvider)

default_urlpatterns（定义于 allauth/socialaccount/providers/oauth2/urls.py）为每个 provider 统一生成两条路由：

login/：跳转到 Figma 授权页的登录视图（对应figma_login）；
login/callback/：接收 Figma 授权回调的视图（对应figma_callback）。

因此只要你已在根 URLconf 中include("allauth.socialaccount.urls")，上述回调地址/accounts/figma/login/callback/即自动生效。登录链接可通过模板标签生成，例如：

{% load socialaccount %} <a href="{% provider_login_url 'figma' %}">使用 Figma 登录</a>

五、OAuth2 端点与登录流程源码解析

1. 三个关键端点

Figma provider 的 OAuth2 适配器定义于 allauth/socialaccount/providers/figma/views.py，其中明确声明了 Figma 平台的三个核心端点：

用途	URL	源码位置
授权端点（authorize）	`https://www.figma.com/oauth`	views.py`authorize_url`
换取令牌端点（token）	`https://www.figma.com/api/oauth/token`	views.py`access_token_url`
用户信息端点（userinfo）	`https://api.figma.com/v1/me`	views.py`userinfo_url`

这些端点继承自基类OAuth2Adapter（见 allauth/socialaccount/providers/oauth2/views.py），基类还负责令牌解析：parse_token从响应中读取access_token，并将refresh_token存入token_secret、依据expires_in计算过期时间。

2. 完整登录调用链

Figma 登录走标准的 OAuth2 授权码流程，由通用视图OAuth2LoginView与OAuth2CallbackView驱动：

用户访问login/，OAuth2LoginView将用户重定向至https://www.figma.com/oauth，附带client_id、redirect_uri（即/accounts/figma/login/callback/的绝对地址）、state等参数；
用户在 Figma 页面授权后，Figma 携带授权码code重定向回login/callback/；
OAuth2CallbackView使用授权码向https://www.figma.com/api/oauth/token发起 POST 请求换取访问令牌（access_token_method默认为POST）；
随后调用适配器的complete_login拉取用户信息并构造SocialLogin。

3. complete_login 的实现细节

views.py 中的complete_login展示了令牌的使用方式：

def complete_login(self, request, app, token, **kwargs): headers = {"Authorization": f"Bearer {token.token}"} with get_adapter().get_requests_session() as sess: resp = sess.get(self.userinfo_url, headers=headers) resp.raise_for_status() extra_data = resp.json() return self.get_provider().sociallogin_from_response(request, extra_data)

即：将 OAuth2 访问令牌以Authorization: Bearer <token>的形式附加到请求头，请求https://api.figma.com/v1/me获取当前用户资料，再把返回的 JSON 交给 provider 完成登录对象构造。这里的get_requests_session()走 django-allauth 统一的会话管理（见 allauth/socialaccount/adapter.py）。

六、用户数据提取与账号绑定

用户资料如何映射为 Django 用户字段，由 provider 类 allauth/socialaccount/providers/figma/provider.py 定义：

class FigmaProvider(OAuth2Provider): id = "figma" name = "Figma" account_class = FigmaAccount oauth2_adapter_class = FigmaOAuth2Adapter def extract_uid(self, data): return str(data["id"]) def extract_common_fields(self, data): return { "email": data.get("email"), "name": data.get("handle"), } def extract_email_addresses(self, data): email = EmailAddress( email=data.get("email"), primary=True, verified=False, ) return [email]

id：provider 标识符，即 URL 中的figma段，同时用于SOCIALACCOUNT_PROVIDERS字典的键；
extract_uid：以 Figma 用户 API 返回的id字段作为社交账户的唯一标识，用于账号去重与关联；
extract_common_fields：将 Figma 的handle（用户名）映射为 Django 用户name，email直接透传；
extract_email_addresses：把 Figma 邮箱生成为EmailAddress记录，标记为主邮箱（primary=True）。注意verified=False——邮箱验证状态由 Figma 侧返回的数据决定，django-allauth 并未将其视为已验证邮箱，这符合第三方登录邮箱默认不可信的保守策略。

此外，FigmaAccount类提供get_avatar_url()，从extra_data["img_url"]读取 Figma 头像地址，供模板中显示用户头像使用。

provider 定义文件末尾通过providers.registry.register(FigmaProvider)完成注册，这也是所有 provider 的通用注册方式（provider 基类见 allauth/socialaccount/providers/base/provider.py）。

七、常见问题与排障

回调地址不匹配（redirect_uri mismatch）：请逐一核对 Figma 开发者平台登记的回调地址、Django 站点配置中的域名（SITE_ID对应站点的 domain，需与回调绝对地址的域名一致，含http://localhost:8000或生产域名）以及实际访问地址是否三者一致。
邮箱未验证导致的流程中断：由于extract_email_addresses将邮箱标记为verified=False，若项目启用了“邮箱验证后才可登录”等严格策略，Figma 登录后可能要求用户额外验证邮箱。可通过调整ACCOUNT_EMAIL_VERIFICATION等账户设置适配业务需求（参见 docs/account/configuration.rst）。
生产环境必须使用 HTTPS：OAuth2 回调涉及令牌交换，生产环境应确保站点启用 HTTPS，并在 Figma 平台登记对应的https://回调地址。
用户信息拉取失败：complete_login中resp.raise_for_status()会在 Figma 用户信息端点返回非 2xx 时抛出异常，请检查令牌是否有效、应用是否仍处于可用状态（如已被删除或令牌被撤销）。