Django-OAuth-Toolkit 的 OpenID Connect 集成指南

什么是 OpenID Connect

OpenID Connect（简称 OIDC）是基于 OAuth 2.0 协议的身份认证层，它标准化了认证流程并提供了与其他系统的即插即用集成。在 Django-OAuth-Toolkit 中，OIDC 支持为开发者提供了以下核心功能：

• 在登录过程中生成 ID Token（JWT 格式），用于描述用户信息
• 基于元数据的提供者自动配置
• 用户信息端点（UserInfo Endpoint），应用可查询获取更多用户信息

启用 OIDC 不会影响现有的 OAuth 2.0 流程，两者可以并行工作。

支持的 OIDC 流程

Django-OAuth-Toolkit 支持以下 OIDC 标准流程：

1. 授权码流程（Authorization Code Flow） - 最安全的流程，推荐使用
2. 隐式流程（Implicit Flow） - 适用于纯前端应用
3. 混合流程（Hybrid Flow） - 结合了授权码和隐式流程的特点

此外，还支持 RP-Initiated 注销（RP-Initiated Logout）功能，允许依赖方（RP）发起注销请求。

配置 OIDC

基本配置

OIDC 默认不启用，需要额外配置。Django-OAuth-Toolkit 支持两种 JWT 签名算法：

1. RS256（推荐）：使用非对称 RSA 密钥（公钥+私钥）
2. HS256：使用对称密钥（客户端密钥）

RS256 配置步骤

1. 生成 RSA 私钥：

openssl genrsa -out oidc.key 4096

2. 安全存储私钥（切勿提交到版本控制）

3. 在 settings.py 中配置：

import os

OAUTH2_PROVIDER = {
    "OIDC_ENABLED": True,
    "OIDC_RSA_PRIVATE_KEY": os.environ.get("OIDC_RSA_PRIVATE_KEY"),
    "SCOPES": {
        "openid": "OpenID Connect scope",
        # 其他作用域...
    },
    # 其他设置...
}

HS256 配置

仅需在 settings.py 中启用 OIDC 并添加 openid 作用域：

OAUTH2_PROVIDER = {
    "OIDC_ENABLED": True,
    "SCOPES": {
        "openid": "OpenID Connect scope",
        # 其他作用域...
    },
    # 其他设置...
}

注意：HS256 仅适用于机密客户端，不推荐用于生产环境。

密钥轮换

可通过 OIDC_RSA_PRIVATE_KEYS_INACTIVE 设置实现密钥轮换：

OAUTH2_PROVIDER = {
    "OIDC_RSA_PRIVATE_KEY": os.environ.get("OIDC_RSA_PRIVATE_KEY"),
    "OIDC_RSA_PRIVATE_KEYS_INACTIVE": [
        os.environ.get("OIDC_RSA_PRIVATE_KEY_2"),
        os.environ.get("OIDC_RSA_PRIVATE_KEY_3")
    ]
    # 其他设置...
}

轮换步骤：

1. 生成新密钥并添加到 inactive 集合
2. 交换 active 和 inactive 密钥
3. 等待足够时间后移除旧密钥

RP-Initiated 注销配置

OAUTH2_PROVIDER = {
    "OIDC_ENABLED": True,
    "OIDC_RP_INITIATED_LOGOUT_ENABLED": True,
    "OIDC_RP_INITIATED_LOGOUT_ALWAYS_PROMPT": True,
    # 其他设置...
}

客户端配置

授权码流程客户端

1. 创建应用，授权类型选择 "Authorization code"
2. 选择签名算法（推荐 RS256）
3. 授权请求中必须包含 openid 作用域

隐式流程客户端

1. 创建应用，授权类型选择 "Implicit"
2. 选择签名算法（必须 RS256）
3. 配置客户端请求 openid 作用域和 OIDC 响应类型

混合流程客户端

1. 创建应用，授权类型选择 "OpenID connect hybrid"
2. 选择签名算法（推荐 RS256）

自定义 OIDC 响应

自定义验证器

创建自定义验证器类：

from oauth2_provider.oauth2_validators import OAuth2Validator

class CustomOAuth2Validator(OAuth2Validator):
    pass

在 settings.py 中配置：

OAUTH2_PROVIDER = {
    "OAUTH2_VALIDATOR_CLASS": "my_project.oauth_validators.CustomOAuth2Validator",
    # 其他设置...
}

添加 ID Token 声明

有两种方式添加声明：

1. 直接返回声明字典：

def get_additional_claims(self, request):
    return {
        "given_name": request.user.first_name,
        "family_name": request.user.last_name,
        # 其他声明...
    }

2. 返回声明生成函数：

oidc_claim_scope = OAuth2Validator.oidc_claim_scope
oidc_claim_scope.update({"permissions": "permissions"})

def get_additional_claims(self):
    return {
        "given_name": lambda request: request.user.first_name,
        "permissions": lambda request: list(request.user.get_group_permissions()),
        # 其他声明...
    }

自定义 UserInfo 端点

def get_userinfo_claims(self, request):
    claims = super().get_userinfo_claims(request)
    claims["custom_claim"] = "custom_value"
    return claims

OIDC 视图

启用 OIDC 后会添加以下视图：

1. ConnectDiscoveryInfoView (/.well-known/openid-configuration) - 提供自动发现信息
2. JwksInfoView (/.well-known/jwks.json) - 提供 JWT 签名密钥信息
3. UserInfoView (/userinfo/) - 提供用户信息
4. RPInitiatedLogoutView (/logout/) - 处理 RP 发起的注销请求

最佳实践

1. 生产环境始终使用 RS256 算法
2. 妥善保管 RSA 私钥，考虑使用密钥管理系统
3. 定期轮换密钥
4. 为不同客户端选择合适的授权流程
5. 仅返回必要的用户声明信息
6. 实现完整的注销流程

通过以上配置，开发者可以轻松地在 Django-OAuth-Toolkit 中实现符合标准的 OpenID Connect 认证服务，为应用提供安全、标准的身份认证解决方案。