django-allauth 集成 Kakao 登录：OAuth2 配置指南与源码解析

django-allauth 集成 Kakao 登录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-allauthKakao카카오是韩国主流的社交与支付平台其 OAuth2 账号体系被大量 Web 应用用作第三方登录入口。本文以 django-allauth 仓库中的 Kakao Provider 文档 为主体完整讲解从 Kakao 开发者平台注册应用、到在 Django 中完成 SocialApp 配置与回调地址设置的完整流程并结合仓库源码剖析 Kakao 适配器的授权端点、用户信息拉取与字段映射实现。读完本文你将能在自己的 Django 项目中快速、可靠地接入 Kakao 登录。Kakao 应用注册获取 Client ID接入 Kakao 登录的第一步是在 Kakao 开发者平台创建应用并获取凭据。原文档给出的入口与本地开发回调地址如下应用注册入口Kakao Developers 控制台的「应用」管理页面developers.kakao.com/apps在此创建应用后即可拿到 REST API 密钥即 OAuth2 术语中的 Client IDKakao 平台称之为 REST API Key。开发环境回调 URLCallback URLhttp://localhost:8000/accounts/kakao/login/callback/回调 URL 的构成与 django-allauth 的路由约定直接相关。查看 Kakao Provider 的 urls.py它调用 OAuth2 提供商的default_urlpatterns工厂函数生成路由from allauth.socialaccount.providers.kakao.provider import KakaoProvider from allauth.socialaccount.providers.oauth2.urls import default_urlpatterns urlpatterns default_urlpatterns(KakaoProvider)而 oauth2/urls.py 中的工厂函数会为每个提供商生成两条路径urlpatterns [ path(login/, login_view, namef{provider.id}_login), path(login/callback/, callback_view, namef{provider.id}_callback), ] return [path(f{provider.get_slug()}/, include(urlpatterns))]因此 Kakao 的登录入口为/accounts/kakao/login/回调入口为/accounts/kakao/login/callback/。由于 Django 开发服务器默认监听8000端口http://localhost:8000/accounts/kakao/login/callback/正是本地联调时的标准回调地址。回调 URL 必须与 Kakao 平台配置完全一致含协议、域名、端口与路径否则登录时会收到类似 An error occurred while attempting to login via your social network account 的失败提示——这是 Providers 总览文档 特别强调的常见坑。Django 侧配置启用应用与填写凭据在 Django 中启用 Kakao 提供商需要两步把该提供商加入INSTALLED_APPS然后通过 Django 管理后台登记应用凭据。1. 注册 Provider 应用在项目的settings.py中添加INSTALLED_APPS [ ... django.contrib.sites, allauth, allauth.account, allauth.socialaccount, allauth.socialaccount.providers.kakao, ]同时确保SITE_ID已配置因为SocialApp记录与Site关联Kakao 登录页面按当前站点过滤可用的 SocialApp。2. 通过 Admin 创建 SocialApp进入/admin/socialaccount/socialapp/新建一条 SocialApp 记录表单填写要点参见 Providers 总览文档 的通用说明字段填写内容Provider选择KakaoName自定义建议填 KakaoClient idKakao 应用控制台中的REST API KeySecret keyKakao 应用控制台「启用 Client Secret」后生成并复制的Client SecretKey不需要留空即可Sites选择你配置的站点与SITE_ID对应需要说明的是Kakao 平台的 Client Secret 默认是关闭状态。如果需要通过授权码换取令牌django-allauth 的 OAuth2 流程必须需要在 Kakao 控制台的应用设置中启用 Client Secret 功能并将其填入Secret key字段。3. 可选SCOPE / AUTH_PARAMS 配置Kakao 遵循 django-allauth 通用 OAuth2 配置机制见 oauth2.rst 与 OAuth2 Provider 基类。你可以在settings.py中覆盖默认 scope 与授权参数SOCIALACCOUNT_PROVIDERS { kakao: { SCOPE: [ profile_nickname, profile_image, account_email, ], AUTH_PARAMS: { # 例如强制显示账号选择页prompt: login, }, } }从源码看get_scope()oauth2/provider.py会优先读取SOCIALACCOUNT_PROVIDERS[kakao][SCOPE]未配置时回退到get_default_scope()OAuth2 基类默认返回空列表[]get_auth_params()oauth2/provider.py同理读取AUTH_PARAMS。这些参数最终会拼入跳转到 Kakao 授权页的 redirect URL。注意Kakao 的账号信息昵称、邮箱、手机号等默认需要用户在授权时单独勾选同意scope 声明之外的信息是否返回取决于 Kakao 账号的「카카오 계정Kakao Account」信息提供设置与用户授权时的勾选情况。源码解析KakaoOAuth2Adapter 的三段式 OAuth2 流程Kakao Provider 是标准的 OAuth2 实现其核心逻辑集中在 views.py 的KakaoOAuth2Adapter中class KakaoOAuth2Adapter(OAuth2Adapter): provider_id kakao access_token_url https://kauth.kakao.com/oauth/token # nosec authorize_url https://kauth.kakao.com/oauth/authorize profile_url https://kapi.kakao.com/v2/user/me def complete_login(self, request, app, token, **kwargs): headers {Authorization: fBearer {token.token}} with get_adapter().get_requests_session() as sess: resp sess.get(self.profile_url, headersheaders) resp.raise_for_status() extra_data resp.json() return self.get_provider().sociallogin_from_response(request, extra_data)三个 URL 常量构成了完整的 OAuth2 授权码流程authorize_urlhttps://kauth.kakao.com/oauth/authorize用户浏览器跳转到 Kakao 的授权页携带client_id、redirect_uri、response_typecode、scope与 state 参数。用户登录 Kakao 并同意授权后Kakao 会以302重定向回redirect_uri并附带授权码code。access_token_urlhttps://kauth.kakao.com/oauth/tokendjango-allauth 的OAuth2Client在后台用授权码 client_idclient_secret换取access_tokenKakao 还支持在该步骤返回 refresh token取决于请求参数。profile_urlhttps://kapi.kakao.com/v2/user/mecomplete_login使用Authorization: Bearer access_token请求 Kakao 的/v2/user/me接口获取用户资料 JSON随后调用sociallogin_from_response把原始数据交给 Provider 解析最终完成SocialLogin的构建。注意请求通过get_adapter().get_requests_session()的共享会话发出便于统一超时、重试与代理配置。这段complete_login逻辑与 Kakao 测试用例 中的 mock 数据一一对应测试里构造的/v2/user/me响应直接用于验证整个登录链路。用户资料提取extra_data 的字段映射Kakao 的/v2/user/me返回结构以kakao_account为信息主体django-allauth 在 provider.py 中完成了以下映射UID 提取def extract_uid(self, data): return str(data[id])Kakao 返回的顶层id是该用户在此应用内的唯一标识long类型被转换为字符串作为 django-allauth 的SocialAccount.uid。通用字段提取def extract_common_fields(self, data): email data.get(kakao_account, {}).get(email) nickname data.get(kakao_account, {}).get(profile, {}).get(nickname) return dict(emailemail, usernamenickname)即邮箱映射到email昵称映射到usernameDjango 用户模型的username字段。邮箱验证状态提取def extract_email_addresses(self, data): ret [] data data.get(kakao_account, {}) email data.get(email) if email: verified data.get(is_email_verified) # data[is_email_verified] imply the email address is verified ret.append(EmailAddress(emailemail, verifiedverified, primaryTrue)) return ret如果 Kakao 返回了email则同步创建EmailAddress记录并将is_email_verified直接作为邮箱验证状态源码注释明确指出 Kakao 的is_email_verified已隐含邮箱通过验证同时标记primaryTrue。因此务必在 Kakao 控制台开启邮箱同意项否则拿不到邮箱django-allauth 可能要求用户额外填写邮箱或触发邮箱验证流程。头像与账号对象KakaoAccount提供了两个便捷属性与一个头像方法provider.pyproperties读取extra_data[properties]Kakao 允许开发者自定义的属性集合profile读取extra_data[kakao_account][profile]get_avatar_url()优先取profile[profile_image_url]回退到properties[profile_image]可满足{% avatar_url %}等模板标签的需要。测试视角/v2/user/me 的标准响应结构仓库中的 Kakao 测试用例 使用OAuth2TestsMixin对完整登录流程做回归验证其 mock 的/v2/user/me响应展示了 Kakao 用户信息 JSON 的典型全貌可作为字段映射的权威参考{ id: 123456789, connected_at: 2022-04-11T01:45:28Z, kakao_account: { profile_nickname_needs_agreement: false, profile_image_needs_agreement: false, profile: { nickname: 홍길동, thumbnail_image_url: http://yyy.kakao.com/.../img_110x110.jpg, profile_image_url: http://yyy.kakao.com/dn/.../img_640x640.jpg, is_default_image: false, is_default_nickname: false }, name: 홍길동, is_email_valid: true, is_email_verified: true, email: samplesample.com, age_range: 20~29, birthyear: 2002, birthday: 1130, birthday_type: SOLAR, gender: female, phone_number: 82 010-1234-5678 }, properties: { CUSTOM_PROPERTY_KEY: CUSTOM_PROPERTY_VALUE } }测试中get_expected_to_str()返回samplesample.com验证了通过邮箱字符串化SocialAccount对象的预期行为。真实环境里age_range、birthday、gender、phone_number等字段是否返回完全取决于用户在 Kakao 授权页上是否勾选对应同意项即控制台的「필수/선택 동의」配置。常见问题与排错要点登录跳转后报错 An error occurred while attempting to login via your social network account绝大多数情况是回调 URL 不匹配。检查 Kakao 控制台填写的http://localhost:8000/accounts/kakao/login/callback/是否与 Django 实际访问的域名、端口、路径完全一致且 Django 的ALLOWED_HOSTS包含对应域名。拿不到用户邮箱确认已在 Kakao 控制台启用邮箱同意项且用户授权时勾选了邮箱否则extract_email_addresses返回空列表可能触发邮箱补齐流程。Client Secret 未启用Kakao 默认关闭 Client Secret令牌交换阶段会因缺少client_secret而失败需要在控制台显式启用并把密钥填入 SocialApp 的Secret key。想要自定义授权参数通过SOCIALACCOUNT_PROVIDERS[kakao][AUTH_PARAMS]或 SocialApp 记录中的 settings 传入实现层面由get_auth_params()与get_auth_params_from_request()oauth2/provider.py合并处理。小结Kakao Provider 是 django-allauth 上百个第三方登录提供商中结构最标准的 OAuth2 实现之一注册入口、回调 URL、Admin 凭据登记三步即可跑通而KakaoOAuth2Adapter与KakaoProvider的源码又清晰展示了授权码换取令牌、/v2/user/me拉取资料、kakao_account字段映射的全链路。若需扩展可继续阅读 Kakao Provider 完整源码、OAuth2 通用配置说明 以及 Providers 总览文档。【免费下载链接】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），仅供参考