Django-OAuth-Toolkit 的 OpenID Connect 集成指南-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00110/article/details/148601734

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

django-oauth-toolkit 项目地址: https://gitcode.com/gh_mirrors/dja/django-oauth-toolkit

什么是 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 标准流程：

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

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

配置 OIDC

基本配置

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

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

RS256 配置步骤

生成 RSA 私钥：

openssl genrsa -out oidc.key 4096

安全存储私钥（切勿提交到版本控制）
在 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")
    ]
    # 其他设置...
}

轮换步骤：

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

RP-Initiated 注销配置

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

客户端配置

授权码流程客户端

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

隐式流程客户端

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

混合流程客户端

创建应用，授权类型选择 "OpenID connect hybrid"
选择签名算法（推荐 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 声明

有两种方式添加声明：

直接返回声明字典：

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

返回声明生成函数：

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