# INSTALLED_APPS 中添加
INSTALLED_APPS = [
    ...
    'oauth2_connect',
]

# AUTHENTICATION_BACKENDS 中添加（放在 ModelBackend 之前）
AUTHENTICATION_BACKENDS = [
    'oauth2_connect.auth.OAuth2Backend',
    'django.contrib.auth.backends.ModelBackend',
]

# 添加 URL
ROOT_URLCONF = [
    ...
    path('oauth2/', include('oauth2_connect.urls')),
]

# 可选配置
OAUTH2_CONNECT = {
    # 站点 URL（用于自动生成回调地址）
    'SITE_URL': 'https://your-domain.com',

    # 登录成功后的重定向地址
    'LOGIN_REDIRECT_URL': '/',

    # 登录失败时的重定向地址
    'LOGIN_URL': '/oauth2/login/',
}

2. 执行数据库迁移

python manage.py migrate

3. 在 Admin 后台添加 OAuth2 Provider

以 GitHub 为例：

配置项	值
Name	GitHub
Slug	github
Client ID	（从 GitHub OAuth Apps 获取）
Client Secret	（从 GitHub OAuth Apps 获取）
Authorize URL	https://github.com/login/oauth/authorize
Token URL	https://github.com/login/oauth/access_token
User Info URL	https://api.github.com/user
Scope	read:user user:email
Unique ID Field	id
Username Field	login
Email Field	email

以 Google 为例：

配置项	值
Name	Google
Slug	google
Client ID	（从 Google Cloud Console 获取）
Client Secret	（从 Google Cloud Console 获取）
Authorize URL	https://accounts.google.com/o/oauth2/v2/auth
Token URL	https://oauth2.googleapis.com/token
User Info URL	https://www.googleapis.com/oauth2/v2/userinfo
Scope	openid email profile
Unique ID Field	id
Username Field	name
Email Field	email
Avatar Field	picture

4. 访问登录页面

浏览器访问 /oauth2/login/，选择 OAuth2 Provider 进行登录。

OAuth2 流程

用户 → 点击「GitHub 登录」
     → 重定向到 GitHub 授权页面
     → 用户在 GitHub 同意授权
     → GitHub 回调 /oauth2/callback/github/?code=xxx&state=yyy
     → 程序用 code 交换 access_token
     → 用 access_token 获取用户信息
     → 创建/更新 Django User，建立关联
     → 登录成功，重定向到首页

高级配置

用户组自动绑定

在 Admin 后台配置 Provider 的「Auto Groups」字段，选择用户登录后自动加入的用户组。

字段映射

extra_data_fields 支持将 Provider 用户信息中的任意字段映射到 Django User 模型字段：

{
    "first_name": "first_name",
    "last_name": "last_name"
}

监听信号

from oauth2_connect.signals import oauth2_user_login, oauth2_user_created

def on_oauth2_login(sender, provider, user, user_info, request, **kwargs):
    print(f"用户 {user.username} 通过 {provider.name} 登录")

def on_oauth2_created(sender, provider, user, user_info, request, **kwargs):
    print(f"新用户 {user.username} 通过 {provider.name} 注册")

oauth2_user_login.connect(on_oauth2_login)
oauth2_user_created.connect(on_oauth2_created)

自定义用户头像

如果项目的 User 模型有 avatar 字段，OAuth2 登录时会自动保存头像 URL。

API

视图

URL	说明
`/oauth2/login/`	登录选择页面，展示所有可用的 OAuth2 Provider
`/oauth2/login/<slug>/`	发起 OAuth2 授权，重定向到 Provider 授权页面
`/oauth2/callback/<slug>/`	OAuth2 回调地址，处理授权码并完成登录

信号

信号	触发时机
`oauth2_user_login`	用户通过 OAuth2 登录成功后
`oauth2_user_created`	新用户首次通过 OAuth2 创建后
`oauth2_user_updated`	用户信息更新后

模型

模型	说明
`OAuth2Provider`	OAuth2 服务提供商配置
`OAuth2User`	用户与 Provider 的关联记录

项目结构

oauth2_connect/
├── __init__.py          # 包初始化
├── apps.py              # Django App 配置
├── models.py            # 数据模型（OAuth2Provider, OAuth2User）
├── auth.py              # Django 认证后端
├── services.py          # OAuth2 核心服务（授权、Token 交换、用户信息获取）
├── views.py             # 登录页面视图
├── urls.py              # URL 路由配置
├── admin.py             # Django Admin 配置
├── utils.py             # 工具函数（JSON 路径提取、授权 URL 构建）
├── signals.py           # 信号定义
├── settings.py          # 默认配置
├── migrations/          # 数据库迁移
├── templates/           # 模板文件
│   └── oauth2_connect/
│       └── login.html   # 登录选择页面
└── locale/              # 国际化文件