登录接入(服务端)
本文面向负责后端、MCP Server 和账号系统的开发者,说明如何将自有账号体系接入豆包应用插件。接入完成后,平台能够在用户授权后代表用户调用 MCP 工具,业务服务端也可以通过平台提供的 OpenAPI 获取用户标识或已加密的用户信息。
接入目标
登录接入同时解决两类问题:
-
MCP 用户授权:当豆包应用插件调用一个需要登录的 MCP 工具时,平台发起用户授权。业务服务端完成账号登录,签发一次性授权 Code,平台再通过 OAuth2.0 Token 接口换取用户级
access_token和refresh_token。后续 MCP 请求会透传用户 OpenID 和业务方签发的访问凭证。 -
Server2Server 服务端调用: 在登录流程中,需要业务服务端调用平台 OpenAPI 换取用户身份信息:
- 用
app_id和app_secret获取应用级access_token; - 使用应用端上送的一次性
login_code换取 OpenID; - 使用应用端上送的一次性
phone_code换取已加密的手机号。
- 用
名词解释
前置准备工作
- 在开发者平台完成开发者入驻和豆包应用插件基础信息录入,包括图标、名称、简介等。
- 准备并确认业务侧 服务协议、隐私协议、登录文案和隐私文案,协议需要是业务自己提供的 H5 链接。
- 准备三方 OAuth Endpoint,用于后续标准 OAuth2.0 能力接入。
- 准备宿主通用信息删除回调地址,作为 DeleteUserInfoURL 配置到开发平台。
- 声明 MCP 工具的登录与鉴权配置:哪些工具需要登录、需要哪些 Scope、是否需要向用户展示索权文案。
注意:平台基础设置和开发配置需要提交审核;版本管理中的 MCP Server 地址、Scope、工具登录配置和三类 URL 配置建议在同一轮联调前全部确认,避免链路中途缺配置。
平台配置
-
填写【基础设置】栏后,点击【提交审核】按钮,由豆包侧相关同学完成审核。
-
【开发配置】栏 上传应用证书,完成证书配置步骤完成应用证书配置。证书生成与上传、平台证书获取、私钥保管、证书序列号、签名验签及加密解密统一参见 关于证书,本页不重复展开
-
【版本管理】栏 完成版本创建
-
创建并上传卡片资源(参考 IDE 使用说明)
-
配置 MCP Server 地址,自动解析对应工具列表
-
勾选当前豆包应用插件所需的全部 scope 权限信息。【可选】可为具体 scope 信息配置使用文案
-
完成工具是否需要登录和索权的配置
-
完成登录关键配置: FetchTokenURL / RefreshTokenURL / DeleteUserInfoURL
- FetchTokenURL

登录过程中通过三方颁发的 code 请求该地址,换取表明登录身份的 access_token「三方颁发」
- RefreshTokenURL

登录过程中通过三方颁发的 access_token 请求该地址,换取续期有效的 access_token 和 refresh_token「三方颁发」
- DeleteUserInfoURL

宿主通用信息删除回调地址,用于满足隐私数据删除和平台策略要求(仅通知删除,非解除登录态)

-
OAuth 能力、通用信息删除能力的开发
标准 OAuth2.0 能力
获取 Token 接口
Token 刷新接口
豆包通用信息删除能力
登录流程结合开发步骤详细说明
在豆包应用插件场景中,用户可以通过两种方式使用三方豆包应用插件的相关功能
- 对话内链路:用户在对话框内通过 Query 触发
- 豆包应用插件内回访:用户通过卡片进入豆包应用插件
在对话链路中,豆包需要调用三方提供的 MCP 工具来获取数据。三方可以通过 OAuth 方式来授权豆包访问三方 MCP。
登录流程简要说明
当用户在对话中触发需要登录的应用插件工具时,豆包将依次通过登录引导卡片、隐私协议提示、登录方式选择三个环节,引导用户完成登录授权。具体流程如下:
步骤一:登录引导卡片
豆包调用需登录的应用插件工具时,会在对话内拉起登录引导卡片,向用户说明登录后可获得的服务能力,并提供"登录"与"暂不登录"选项。
步骤二:隐私协议提示
用户点击"登录"后,页面将展示隐私协议提示,明确告知用户豆包与三方应用插件之间的信息访问与共享范围。用户须需点击"同意并继续"后方可进入后续登录环节。
步骤三:登录方式选择
用户同意隐私协议后,将进入登录方式选择卡片,提供以下两种登录途径:
- 豆包绑定号码登录:用户选择使用豆包绑定的手机号进行登录时,授权流程在豆包前端直接完成,豆包将用户手机号传递给三方开发者。此场景下,三方开发者无需再弹出任何额外的登录或授权页面。
- 其他登录方式:用户选择其他登录方式时,三方开发者需自行拉起自有登录页面供用户完成登录,并将登录结果回传至豆包。三方开发者可自定义登录页面的界面与文案,但页面中不得包含任何豆包相关的文字、图标或视觉元素。

图1:登录引导卡片

图2:隐私协议提示

图3:登录方式选择
三方开发者登录页面要求
- 采用豆包绑定号码登录时,授权交互在豆包侧完成,三方开发者不得叠加任何中间页面。
- 采用其他登录方式时,三方自有登录页面须保持品牌独立性,禁止使用豆包品牌元素(包括但不限于"豆包"文字、豆包Logo、豆包视觉风格等),避免造成用户混淆或误认。
工具配置登录
在开发者平台注册 MCP 工具时,选择需要登录,并填写三方 Auth 服务器 Endpoint。
配置个人信息使用说明
只要 manifest.yaml 中任一 MCP 工具标记为需要登录,项目根目录的 business-templates.yaml 就必须包含 personal_information。未配置或配置未通过校验时,CLI 会阻止提交,应用插件版本无法提交。
personal_information 用于向用户说明:登录后,服务方会向豆包提供哪些个人信息,以及每类信息的使用目的。
personal_information.items 可以包含多个 PersonalInformationItem。登录授权页面会按配置顺序展示这些项目,每个项目对应一条“name:description”说明。例如,下列配置会生成图中红框内的三条说明:

personal_information 是应用级配置,对应用的所有版本生效。新版本默认继承上一版本的配置。如果个人信息类型或使用目的发生变化,请同步更新 items,确保页面展示内容与实际处理方式一致。
上传或提交应用插件版本时,CLI 会校验该配置。如果 manifest.yaml 中存在需要登录的工具,但 personal_information 缺失或格式错误,校验会失败并阻止提交。补充或修正配置后,才能提交应用插件版本。
对话内链路登录时序图

- 豆包调用需要登录的 MCP 工具时,会拉起登录流程
- 用户同意登录后,若选择“豆包绑定号码登录”,则会完成鉴权流程;若选择“其他登录方式”,则会拉起三方自己的登录页面,并注册回调 callback。
- 三方豆包应用插件登录页中,开发者可以使用豆包应用插件 API 和 OpenAPI 获取用户在豆包内的信息。
- 三方完成自身登录流程后,需要生成三方短期兑换 Code 并回调至 callback,也可以通过端 API 读写三方登录态。
- 豆包会使用三方的短期登录 Code,换取三方颁发给豆包的 MCP 鉴权 Token。
登录步骤拆解(开发者视角)
- 服务端 OpenAPI 请求域名: 参见 服务端API总览
- 端侧触发登录或手机号授权,得到豆包一次性
login_code和phone_code。 - 端侧把一次性 code 传给三方服务端,不要在端侧保存长期 Token。
- 三方服务端调用豆包 OpenAPI 换取
open_id或加密手机号。 - 三方服务端完成三方账号登录或绑定,并生成三方短期兑换 Code。
- 端侧调用
postLoginResult,把三方短期兑换 Code 回传给豆包 MCP Server。 - 豆包服务端随后调用
FetchTokenURL,用短期 Code 换取三方 MCP 调用授权 Token。
- 豆包侧发起对应 Query,豆包服务端下发对应豆包应用插件工具的登录卡片
- 用户点击登录,弹起对应隐私弹窗页面
-
用户点击同意隐私协议,弹出登录页面,用户选择使用豆包手机号一键登录:
- 三方前端开发者底层调用获取 OpenID 票据的 JSB:
- 三方前端开发者底层调用获取手机号票据的 JSB:
-
三方前端开发者将获取到的 OpenID 票据和手机号票据传给三方服务端(均为一次性,时效为 5 分钟,过期或使用后均需重新获取)
-
三方服务端调用豆包服务端的 OpenAPI 获取用户的 OpenID 和加密手机号(需解密)
-
通过 appId 和 appSecret 获取应用级 accessToken(获取手机号接口需要)
-
通过 getopenid 接口获取 OpenID
-
通过 getuserphonenumber 接口获取手机号
-
根据应用私钥和加密手机号来解密手机号 (手机号属于敏感信息。接口返回
encrypt_phone_number密文,业务服务端使用与平台登记的开发者证书配套的私钥完成解密。更详细的要求参见 关于证书)
Step 1:解析返回字段
解析得到:
- version
- ephemeral_pub_key
- data_key_cipher
- data_cipher
Step 2:解封装 dataKey
开发者使用自己的 ECC P-256 私钥 dev_priv:
- 计算共享密钥:
- 对共享密钥进行 SHA-256 哈希,得到 KEK:
- 使用 KEK 解密 data_key_cipher,得到 dataKey
Step 3:解密业务数据
Step 4:解析 data JSON(可选,有些加密数据可能不是 Json 格式)
即可获得解密后的明文手机号
解密代码示例
-
-
三方服务端将颁发给豆包侧后续换取token的一次性code下发给三方前端
-
三方前端携带code调用postLoginResult JSB完成MCP登录结果回传
-
豆包客户端框架将code传给豆包服务端,豆包服务端调用三方提供的oauth endpoint完成token的交换,返回success状态
-
豆包客户端框架收到
success状态后,自动关闭 MCP 登录页,并重新发送 Query。 -
豆包服务端将三方服务端颁发的
access_token和 OpenID 身份标识透传在 Header 中,调用三方 MCP 工具,并返回对应数据和卡片内容。
豆包应用插件全页内链路登录时序图
- 整体流程跟对话内链路登录时序类似,仅仅少了前置的用户发自然语言的 Query 步骤和具体 MCP 工具调用的步骤

- 用户进入豆包应用插件之后,豆包应用插件如果判断需要三方登录(根据自定义登录态是否过期判断),可以调用拉起三方登录页
- 三方登录流程完成之后,需要将三方兑换 code 回调到豆包应用插件框架提供的默认 callback 上,完成对豆包的授权
运行时链路总结说明
完整时序说明
- 开发者在开发者平台为 MCP Server 选择“需要登录”,并配置业务方的
FetchTokenURL、RefreshTokenURL、DeleteUserInfoURL、服务协议、隐私政策和回调地址。 - 豆包应用插件准备调用需授权的 MCP 工具时,拉起登录授权流程。
- 用户同意后进入业务方登录页。业务服务端完成账号校验,以
open_id为外部身份建立或查找本地账号绑定。 - 业务服务端签发一个短时、一次性授权 Code,并通过前端 JSB 调用透给平台侧服务端。
- 平台从业务 Token 获取地址用 Code 换取
access_token和refresh_token。 - 后续 MCP 请求通过 Header 透传身份和凭证:
X-DB-OPENID表示用户,X-DB-ACCESS-TOKEN表示业务授权的凭证身份。 - 用户 Token 过期时,平台使用
refresh_token调用刷新接口;刷新失败或用户已撤销授权或登录态失效时,重新进入交互式登录。
对话内链路
- 用户在豆包对话框内通过 Query 触发三方能力。
- 豆包调用需要登录的 MCP 工具时,如果没有可用授权,会拉起登录流程。
- 用户同意登录后,平台拉起三方登录页面,并注册回调。
- 三方登录页面通过容器 API 获取一次性登录凭证,并由三方服务端换取 OpenID、手机号等信息。
- 三方完成自己的账号登录后,生成三方短期兑换 Code,并通过
postLoginResult或回调交给豆包。 - 豆包用短期 Code 调用三方
FetchTokenURL,换取 MCP 调用授权 Token。 - 后续豆包调用三方 MCP 工具时,会在请求 Header 中透传
X-DB-OPENID;三方工具的inputSchema不需要显式声明 OpenID 字段。
豆包应用插件内回访链路
- 用户通过卡片或其他入口进入三方豆包应用插件。
- 豆包应用插件根据三方自定义登录态判断是否需要重新登录。
- 如果需要登录,豆包应用插件调用登录页或
doubao.login(),完成三方登录。 - 三方登录完成后,把三方兑换 code 回调到豆包应用插件框架提供的默认 callback,完成对豆包的授权。
- 登录完成后刷新卡片或页面状态,确保用户看到最新业务数据。
用户身份标识与多端登录场景说明
身份标识
平台调用三方服务时,使用 OpenID 标识用户。三方需维护 OpenID 与三方账号的关联。
手机号给到三方起到一个账号对撞的作用,当前手机号在三方已经存在账号时,使用已有账号进行关联,否则新注册一个账号进行关联。
多端登录
豆包 APP 可以多端登录(即同一个账号可以同时登录多个设备)。在多端登录场景下:
- 三方颁发给豆包的鉴权 Token 支持多端同步,即多个设备在主 Bot 对话内链路复用同一个鉴权 token
- 豆包应用插件内登录态由三方开发者维护,平台不存储三方登录态,推荐开发者在豆包应用插件中使用 doubao.login() 来实现静默登录

OpenID、Token 与登录态维护规则
开发者必须维护
OpenID与三方账号的绑定关系。- 三方 MCP 授权 Token 与 RefreshToken 的生命周期。
- 豆包应用插件内自定义登录态,平台不存储三方登录态。
平台会提供和透传
- 登录、手机号、隐私授权相关容器能力。
- 服务端 OpenAPI:获取 OpenID、手机号、应用级 AccessToken。
- MCP 调用时通过
X-DB-OPENID透传用户标识。 - 多端登录场景下,豆包侧会复用同一 MCP 授权 Token。
推荐:豆包应用插件内登录态由三方维护,建议在豆包应用插件中使用 doubao.login() 做静默登录或快速恢复,避免多端场景下出现用户重复授权。
异常情况处理
关于登录有效期
三方颁发给豆包的授权 Token 有效期与三方豆包应用插件内的自定义登录态有效期不一致会出现用户体验问题。对于这种异常场景的处理建议如下
所以这里推荐开发者尽量维持颁发给豆包的授权 Token 有效期与三方自定义登录态的有效期保持一致,否则可能出现 MCP 还能调用但豆包应用插件内已退出,或豆包应用插件仍登录但 MCP Token 已过期的体验不一致问题。
其他异常与边界场景
业务主动拉起登录场景
- 由于豆包侧存储的
access_token可能在以下场景调用到业务侧已经失效,此时需要有能够主动拉起应用插件重新登录流程的能力:- 时序问题到达业务方的
access_token刚好到失效期 - 命中安全策略(如
token泄露等),业务方可主动失效掉已经颁发给豆包宿主的access_token
- 时序问题到达业务方的
- 对于以上场景豆包侧的处理流程:
access_token过期:- 需要业务侧返回
http status_code状态码为401(内部rpc业务返回50401),豆包侧识别到该状态码之后会主动强制拉起登录,让用户重新完成登录流程,获取业务方新颁发的access_token(注意在其他返回状态码的场景中不要混用401以免服务报错)。
- 需要业务侧返回
refresh_token过期:- 对应刷新
token的接口返回的Code = 50401&&Msg = "token expired"(注意二者均需按照要求返回)
- 对应刷新
OpenAPI 接入流程
调试环境说明
真实 AppID 已支持在 Sandbox 中使用,但 AppID 类型不代表当前运行环境。登录流程中的应用凭证、login_code、phone_code、应用级 Access Token 和 OpenAPI 必须属于同一环境,不能混用。
真实 AppID 在 Sandbox 中运行时,生成的仍是 Sandbox 环境的
login_code和phone_code,必须搭配 Sandbox 环境的应用级 Access Token 和 OpenAPI 使用。
调试阶段建议
建议开发者在调试版本中对登录各步骤增加显式错误提示,避免错误被页面吞掉,便于确认流程中断位置:
- 获取
login_code或phone_code。 - 使用
login_code换取 OpenID。 - 使用
phone_code换取加密手机号。 - 完成三方登录并生成短期兑换 Code。
- 调用
postLoginResult回传登录结果。
错误提示建议包含当前步骤、接口返回的 code、msg 和 log_id。请勿展示或记录 AppSecret、完整 Access Token、完整 login_code、完整 phone_code 等敏感信息;详细错误提示仅用于调试版本。
获取应用级 Token
- 需要调用应用级 OpenAPI 时,服务端调用
/api/token/v1/developer/get_client_token,传入app_id、app_secret和grant_type=client_credential。获取后按expires_in缓存,不要在每个业务请求中重新获取。 - 推荐将应用级 Token 收口到一个服务端 Token Provider:统一缓存、提前刷新、并发单飞(single-flight)、原子换新和失败重试。避免多实例同时刷新导致旧 Token 立即失效。
用 login_code 换取 OpenID
- 豆包应用插件端完成用户登录授权后,获得一次性
login_code并传给业务服务端。服务端立即调用/api/login/v1/developer/get_openid,使用app_id、app_secret、grant_type=authorization_code和login_code换取open_id。 - 该接口直接使用应用密钥验证身份,不需要额外携带应用级 Token。交换成功后,以
app_id + open_id为外部身份唯一键,不要用手机号或昵称代替。
用 phone_code 换取已加密手机号
- 应用端在用户明确授权后获得一次性
phone_code,服务端调用/api/login/v1/developer/get_user_phonenumber: - 请求头
x-DB-AccessToken携带有效的应用级 Token。 - 请求体携带
phone_code。 - 返回的
encrypt_phone_number是密文,业务服务端需使用与平台登记的开发者证书配套的私钥解密。具体加密格式、解密方法和安全要求参见 关于证书
服务端需要实现的能力
开发者平台的三个关键 URL
Token 生命周期策略
- 用户 Token。 访问 Token 过期前预留少量时钟偏差,尽量由平台使用
refresh_token静默刷新。如果业务方返回新的refresh_token,应使用新值原子替换旧值。用户退出、解绑或合规删除时,立即撤销相关 Token。 - 平台应用级 Token。 按
expires_in缓存,推荐在剩余 5%~10% 有效期时刷新,并加入小幅随机抖动避免集群同时刷新。当 OpenAPI 明确返回 Token 失效时,只允许强制刷新并重试一次,避免无限重试。 - 业务会话对齐。 如果用户 Token 比业务会话更长,平台仍可以调用 MCP,但用户进入业务界面后可能需要重建会话;如果用户 Token 更短,用户尚处于业务会话中却可能被要求重新授权。建议在安全策略允许的前提下对齐两者有效期。
推荐实施顺序
- 完成平台配置。 准备应用基本信息、服务协议、隐私政策、
FetchTokenURL、RefreshTokenURL、DeleteUserInfoURL、回调白名单和 MCP 工具鉴权声明。 - 打通账号映射。 先完成
login_code -> open_id -> 业务账号闭环,并覆盖重试、重放和并发绑定。 - 实现 OAuth2.0 服务。 完成授权 Code 签发、Code 换 Token、刷新 Token、Scope 校验、撤销和审计。
- 接入 MCP 鉴权中间件。 对所有需登录工具强制执行统一校验,再开放联调。
- 完成应用级 OpenAPI Client。 实现 Token 缓存、OpenID 交换、已加密手机号获取和解密。
- 完成异常与合规链路。 覆盖 Token 过期、授权撤销、用户拒绝、通用信息删除、证书轮换和审计。


