django-allauth 接入 Sign In with Apple从 Apple Developer 配置到 OAuth2 源码级原理【免费下载链接】django-allauthIntegrated 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 仓库中的 Apple Provider 文档 为主体完整讲解如何在 Django 项目中接入 Apple 登录Sign In with Apple。你将学会在 Apple Developer 后台完成 App ID / Service ID 与私钥注册、在settings.py中正确配置client_id、secret、key与certificate_key理解 Bundle ID 与 Services ID 双 Client 模式的隐藏策略并深入源码看清form_post回调、JWTclient_secret、id_token验签与跨域会话 Cookie 的底层机制从而快速定位并解决集成中的PermissionDenied等问题。一、准备工作Apple Developer 侧的注册项在写任何 Django 代码之前需要先在 Apple Developer 后台完成三类注册django-allauth 的 Apple Provider 依赖这三项才能完成授权与验签App 注册App ID Service ID进入 Apple Developer 的 Certificates, Identifiers Profiles 中创建 App ID然后再创建对应的 Service ID服务标识符。登录流程启动时移动端 iOS 使用 Bundle ID 作为client_idWeb 端授权流程则使用 Services ID两者不可混用详见下文“双 Client ID”一节。私钥注册Private Key / Auth Key在 Keys 页面生成一个登录密钥系统会为你分配一个Key ID并允许你仅下载一次私钥证书文件-----BEGIN PRIVATE KEY-----开头的 PEM 内容请务必保存好后续需要粘贴到certificate_key配置中。开发回调 URL在 Service ID 的配置里登记开发环境回调地址形如http://domain.com/accounts/apple/login/callback/其中domain.com替换为你的实际域名/accounts/apple/login/callback/是 django-allauth 默认注册的 Apple 回调路径见 allauth/socialaccount/providers/apple/urls.py 与 OAuth2 默认 URL 模式。二、在 Django settings.py 中配置 Apple Provider将 Apple Provider 加入INSTALLED_APPSallauth.socialaccount.providers.apple后在settings.py中通过SOCIALACCOUNT_PROVIDERS字典完成配置。原文档给出的完整配置如下SOCIALACCOUNT_PROVIDERS { apple: { APPS: [{ # Your service identifier. client_id: your.service.id, # The Key ID (visible in the View Key Details page). secret: KEYID, # Member ID/App ID Prefix -- you can find it below your name # at the top right corner of the page, or its your App ID # Prefix in your App ID. key: MEMAPPIDPREFIX, settings: { # The certificate you downloaded when generating the key. certificate_key: -----BEGIN PRIVATE KEY----- s3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr 3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3cr3ts3 c3ts3cr3t -----END PRIVATE KEY----- } }] } }各字段含义与来源如下配置键含义获取位置说明client_idService ID 标识符Apple Developer Identifiers 列表登录时作为 OAuth2client_id发送给 ApplesecretKey ID不是私钥本身View Key Details 页面用于 JWTclient_secret的kid请求头keyMember ID / App ID PrefixTeam ID开发者账号右上角或 App ID 的 Prefix用于 JWTclient_secret的iss声明settings.certificate_key私钥证书 PEM 内容生成密钥时唯一一次下载用于对 JWTclient_secret做 ES256 签名从源码 client.py 可以看到这三个值被如何消费generate_client_secret()读取app.key作为 JWT 的iss读取app.settings[certificate_key]作为签名密钥读取self.consumer_secret即secret字段作为请求头kid最终生成一段有效期 1 小时exp now 60 * 60的 ES256 签名 JWT 作为 OAuth2 的client_secret参数claims { iss: app.key, aud: https://appleid.apple.com, sub: self.get_client_id(), iat: now, exp: now 60 * 60, } headers {kid: self.consumer_secret, alg: ES256} client_secret jwt_encode(payloadclaims, keycertificate_key, algorithmES256, headersheaders)注意两点key缺失或certificate_key缺失都会抛出ImproperlyConfigured异常见 client.pysecret字段在 Apple 场景下不是私钥而是 Key ID这是新手最容易配反的地方。三、双 Client IDBundle ID 与 Services IDApple 提供了两类不同的 Client IDBundle IDiOS 移动端 App 的标识符移动端授权流程使用Services IDWeb 授权流程使用。如果你的项目需要同时支持 iOS App 与 Web 两种登录入口就需要在APPS列表中为每个 Client ID 分别添加一个应用条目APPS: [ { # Services ID用于 Web 授权流程 client_id: your.service.id, secret: KEYID, key: MEMAPPIDPREFIX, settings: { certificate_key: ..., }, }, { # Bundle ID用于 iOS App 内登录 client_id: com.example.yourapp, secret: KEYID, key: MEMAPPIDPREFIX, settings: { certificate_key: ..., # 该应用不在 Web 端展示 hidden: True, }, }, ],hidden: True的作用是让指定 Bundle ID 应用不在 Web 登录页面上显示。从源码看该设置被两处消费模板标签 allauth/socialaccount/templatetags/socialaccount.py 在渲染登录按钮时跳过app.settings.get(hidden)的应用适配器 adapter.py 的get_app()在存在多个应用时会过滤掉hidden应用若过滤后可见应用数量不为 1 则抛出MultipleObjectsReturned。此外client_id还支持用逗号分隔多个值AppleProvider.get_auds()会将其拆分后逐一作为id_token的合法 audience见 provider.py。四、回调 URL 与 URL 路由结构Apple Provider 的路由定义在 allauth/socialaccount/providers/apple/urls.py它先复用 OAuth2 默认模式再追加一个专属的 finish 回调urlpatterns default_urlpatterns(AppleProvider) urlpatterns [ path( f{AppleProvider.get_slug()}/login/callback/finish/, oauth2_finish_login, nameapple_finish_callback, ), ]最终得到三条关键路径路径视图作用/accounts/apple/login/oauth2_login发起授权重定向到 Apple/accounts/apple/login/callback/apple_post_callback接收 Apple 的form_post回调/accounts/apple/login/callback/finish/oauth2_finish_login在正常会话中完成 OAuth2 收尾在 Apple Developer 后台登记的回调 URL 对应第一条 callback 路径/accounts/apple/login/callback/而 finish 路径由 django-allauth 内部重定向使用无需在 Apple 侧登记。五、源码级原理OAuth2 变体与 form_post 回调Sign in with Apple 使用的是 OAuth2 的变体与常规 OAuth2 有两个显著差异源码中有明确体现1. 授权请求使用form_post响应模式client.py 中的get_redirect_url()构造的授权参数与常规 OAuth2 不同params { client_id: self.get_client_id(), redirect_uri: self.callback_url, response_mode: form_post, scope: scope, response_type: code id_token, }response_modeform_postApple 会把授权结果以HTTP POST 表单而非 GET 重定向的方式回传response_typecode id_token一次性返回授权码与id_token用户信息含邮箱、姓名由id_token的 JWT 载荷携带。2. 用 JWT 作为 client_secret常规 OAuth2 通常使用静态密钥而 Apple 要求以私钥签名生成 JWT见上文generate_client_secret()并在换取访问令牌时以client_secret字段提交见 client.py 的get_access_token()同时支持 PKCEcode_verifier参数。3. POST 回调的会话隔离与中转由于回调是跨域 POST浏览器不会携带会话 CookieCookie 的SameSiteLax只对 GET 放行。为此 views.py 中的apple_post_callback采用了“中转”策略视图被csrf_exempt与login_not_required装饰允许匿名 POST将code、state、error放进重定向 URL 的查询参数将user、id_token存入独立的 Apple 登录会话名为apple-login-session的 Cookie见 apple_session.py302 重定向到同源的 finish 回调/accounts/apple/login/callback/finish/此时会话 Cookie 可正常携带再由OAuth2CallbackView完成换 token、验签与登录。整个中转流程在测试 tests/apps/socialaccount/providers/apple/tests.py 中有完整验证POST callback 后断言重定向到apple_finish_callback并断言响应中设置了apple-login-sessionCookie会话内容在完成后被清空。六、id_token 的验签与用户数据提取1. 验签流程Apple 的id_token由 Apple 私钥签名公钥从https://appleid.apple.com/auth/keysJWKS 端点获取。源码中 views.py 的get_verified_identity_data()调用 jwtkit.verify_and_decode() 完成读取 JWT 头中的kid从 JWKS 响应中定位对应公钥lookup_kid_jwk支持 RS256 等算法校验签名、iss必须为https://appleid.apple.com、aud必须匹配已配置的 client_id与exp调用verify_jti()做防重放检查若 JWT 带jti声明会按issjti缓存该令牌已使用过的令牌会被拒绝见 jwtkit.py。2. 用户数据映射验签后的 JWT 载荷被合入token.user_data见 views.py随后由 provider.py 提取extract_uid()以sub声明作为唯一用户标识extract_common_fields()从email、name.firstName、name.lastName映射 Django 用户字段extract_email_addresses()读取email与email_verified兼容字符串形式的true构造主邮箱地址get_default_scope()默认请求name作用域仅当QUERY_EMAIL对应SOCIALACCOUNT_QUERY_EMAIL设置开启时才附加email账户展示名AppleAccount.to_str()会优先使用邮箱但跳过以privaterelay.appleid.com结尾的苹果隐私中转邮箱此时回退到姓名拼接见 provider.py。3. Token 直验支持AppleProvider声明了supports_token_authentication True并提供verify_token()方法当客户端如 iOS App自行拿到id_token后可以直接调起验签与登录无需走完整 Web 流程见 provider.py。测试用例test_verify_token验证了这一路径见 tests.py。七、常见问题排查1. 登录时出现 PermissionDenied原文档明确指出Sign in with Apple 的form_post回调不会携带会话 Cookie。若在回调处理链中遇到PermissionDenied应检查是否存在第三方中间件在跨域 POST 时重新生成了 session导致后续 finish 回调无法访问原始会话确认回调路径上没有强制登录的中间件login_not_required只作用于视图本身。2. 换 token 报错或验签失败确认secret填的是Key ID而非私钥内容确认certificate_key是完整的 PEM含-----BEGIN/END PRIVATE KEY-----首尾行确认key是Team IDApp ID Prefix若多 Client 场景下出现MultipleObjectsReturned检查是否所有可见应用的hidden配置都正确adapter.py 要求可见应用恰好一个。3. 使用隐私中转邮箱时的账号合并Apple 允许用户隐藏真实邮箱此时返回的邮箱形如xxxprivaterelay.appleid.com。django-allauth 在展示与匹配时已对该类型邮箱做了特殊处理集成时无需额外代码但需注意同一用户在不同设备登录时sub保持一致因此用户关联以sub为准。八、本地测试与验证仓库的测试套件为 Apple Provider 提供了完整可复现的验证路径tests/apps/socialaccount/providers/apple/tests.py使用本地生成的 RSA 密钥对模拟 Apple JWKS 公钥端点响应TESTING_JWT_KEYSET与KEY_SERVER_RESP_JSONsign_id_token()模拟 Apple 签名id_token载荷含iss、aud、sub、email、email_verified等真实字段测试覆盖完整登录流程发起授权 → POST callback → 中转重定向 → finish 验签换 token → 登录成功并断言apple-login-sessionCookie 的路径与会话清理tests.py。你可以参考该测试文件理解整个授权-验签链路的每一步数据形态或在本地跑通测试验证环境配置的正确性。九、参考文件速查配置文档docs/socialaccount/providers/apple.rstProvider 与用户数据提取allauth/socialaccount/providers/apple/provider.py自定义 OAuth2 客户端JWT secret 与 form_postallauth/socialaccount/providers/apple/client.py适配器与回调中转视图allauth/socialaccount/providers/apple/views.pyURL 路由allauth/socialaccount/providers/apple/urls.pyApple 专用会话allauth/socialaccount/providers/apple/apple_session.pyJWT 通用验签工具allauth/socialaccount/internal/jwtkit.py测试用例tests/apps/socialaccount/providers/apple/tests.py【免费下载链接】django-allauthIntegrated 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
