配置 SSO 登录后跳转至扣子指定页面

通过在单点登录（SSO）配置中传递特定参数，实现用户登录后直接跳转到扣子或扣子编程的指定页面，例如某个扣子编程工作空间、智能体或者某个扣子 Agent。通过精确的登录后跳转，可以无缝优化用户登录体验，提升工作效率。

功能介绍

SSO 登录支持 SAML 和 OAuth 两种主流 SSO 协议。你可以通过构造 RelayState（SAML）或 state（OAuth）参数来携带跳转路径信息，在用户完成身份验证后，将其重定向至预设的 URL。跳转目标由 navigatePath 字段决定：

• 跳转至扣子（coze.cn）：navigatePath 支持使用相对路径或完整 URL，例如 /session/764153****或https://www.coze.cn/session/76415****（某个扣子 Agent）。
• 跳转至扣子编程（code.coze.cn）：navigatePath 需要使用完整 URL。例如 https://code.coze.cn/home（扣子编程主页）。

前提条件

已配置单点登录（SSO）。

SAML SSO 登录

通过构造 RelayState 参数携带跳转路径信息，实现登录后直达扣子或扣子编程的指定页面。

操作步骤如下：

1. 拼接 RelayState 参数。
   RelayState 参数的格式如下：

   // 字符串中的域名和client_id为固定值，请勿修改
   // js代码示例
   const RelayState ='redirect_uri=' + encodeURIComponent('https://signin-saas.volccloudidentity.com/api/cloudidentity/authorize/federateOAuth?client_id=9836804098&state=' + encodeURIComponent(`{"platform":"eps_cloud_identity","navigatePath":"${需要替换的path}","type":"login"}`)
   + '&response_type=code&redirect_uri=' + encodeURIComponent('https://www.coze.cn/auth/callback'))
   

   通过修改 state 参数中 navigatePath 的值、执行两次 URL 编码、拼接至 RelayState，即可得到 RelayState 参数的值。具体流程与示例如下表所示：

   拼接流程	扣子 Agent	扣子编程主页	扣子编程工作空间	扣子编程工作空间中的智能体
   1. 在state参数的navigatePath字段中配置 SSO 跳转的目标页面。	{"platform":"eps_cloud_identity","navigatePath":"/session/764153****","type":"login"}	{"platform":"eps_cloud_identity","navigatePath":"https://code.coze.cn/home","type":"login"}	{"platform":"eps_cloud_identity","navigatePath":"https://code.coze.cn/space","type":"login"}	{"platform":"eps_cloud_identity","navigatePath":"https://code.coze.cn/space/7436975598481899583/bot/754166928014542***5","type":"login"}
   2. 使用在线 URL 编码工具对 state 中的 JSON 字符串执行两次 URL 编码。	%257B%2522platform%2522%253A%2522eps_cloud_identity%2522%252C%2522navigatePath%2522%253A%2522%252Fsession%252F%2520764153****%2522%252C%2522type%2522%253A%2522login%2522%257D	%257B%2522platform%2522%253A%2522eps_cloud_identity%2522%252C%2522navigatePath%2522%253A%2522https%253A%252F%252Fcode.coze.cn%252Fhome%2522%252C%2522type%2522%253A%2522login%2522%257D	%257B%2522platform%2522%253A%2522eps_cloud_identity%2522%252C%2522navigatePath%2522%253A%2522https%253A%252F%252Fcode.coze.cn%252Fspace%2522%252C%2522type%2522%253A%2522login%2522%257D	%257B%2522platform%2522%253A%2522eps_cloud_identity%2522%252C%2522navigatePath%2522%253A%2522https%253A%252F%252Fcode.coze.cn%252Fspace%252F7436975598481899583%252Fbot%252F754166928014542***5%2522%252C%2522type%2522%253A%2522login%2522%257D
   3. 将编码后的值拼接到 RelayState 参数中。	redirect_uri=https%3A%2F%2Fsignin-saas.volccloudidentity.com%2Fapi%2Fcloudidentity%2Fauthorize%2FfederateOAuth%3Fclient_id%3D9836804098%26state%3D%25257B%252522platform%252522%25253A%252522eps_cloud_identity%252522%25252C%252522navigatePath%252522%25253A%252522%25252Fsession%25252F%252520764153%25252A%25252A%25252A%25252A%252522%25252C%252522type%252522%25253A%252522login%252522%25257D%26response_type%3Dcode%26redirect_uri%3Dhttps%253A%252F%252Fwww.coze.cn%252Fauth%252Fcallback%26scenario%3Dcoze	redirect_uri=https%3A%2F%2Fsignin-saas.volccloudidentity.com%2Fapi%2Fcloudidentity%2Fauthorize%2FfederateOAuth%3Fclient_id%3D9836804098%26state%3D%25257B%252522platform%252522%25253A%252522eps_cloud_identity%252522%25252C%252522navigatePath%252522%25253A%252522https%25253A%25252F%25252Fcode.coze.cn%25252Fhome%252522%25252C%252522type%252522%25253A%252522login%252522%25257D%26response_type%3Dcode%26redirect_uri%3Dhttps%253A%252F%252Fwww.coze.cn%252Fauth%252Fcallback%26scenario%3Dcoze	redirect_uri=https%3A%2F%2Fsignin-saas.volccloudidentity.com%2Fapi%2Fcloudidentity%2Fauthorize%2FfederateOAuth%3Fclient_id%3D9836804098%26state%3D%25257B%252522platform%252522%25253A%252522eps_cloud_identity%252522%25252C%252522navigatePath%252522%25253A%252522https%25253A%25252F%25252Fcode.coze.cn%25252Fspace%252522%25252C%252522type%252522%25253A%252522login%252522%25257D%26response_type%3Dcode%26redirect_uri%3Dhttps%253A%252F%252Fwww.coze.cn%252Fauth%252Fcallback%26scenario%3Dcoze	redirect_uri=https%3A%2F%2Fsignin-saas.volccloudidentity.com%2Fapi%2Fcloudidentity%2Fauthorize%2FfederateOAuth%3Fclient_id%3D9836804098%26state%3D%25257B%252522platform%252522%25253A%252522eps_cloud_identity%252522%25252C%252522navigatePath%252522%25253A%252522https%25253A%25252F%25252Fcode.coze.cn%25252Fspace%25252F7436975598481899583%25252Fbot%25252F754166928014542%25252A%25252A%25252A5%252522%25252C%252522type%252522%25253A%252522login%252522%25257D%26response_type%3Dcode%26redirect_uri%3Dhttps%253A%252F%252Fwww.coze.cn%252Fauth%252Fcallback%26scenario%3Dcoze

2. 将拼接好的 RelayState 参数的值配置至 IdP 平台的登录跳转地址中：

   // js代码示例
   // POST方式
   {"RelayState": `${RelayStateString}`}
   
   //Redirect方式
   `&RelayState=${encodeURIComponent(RelayStateString)}`
   

OAuth SSO 登录

通过构造并传递 state 参数携带跳转路径信息，实现登录后直达扣子或扣子编程的指定页面，操作步骤如下：

1. 构造一个 coze_state JSON 对象。
   1. 按以下示例构造coze_state JSON 对象，用于指定目标跳转页面。

      const coze_state =  '{"platform":"eps_cloud_identity","navigatePath":"/space","type":"login"}'
      

      参数说明如下：

      参数	说明
      platform	平台标识，固定值为eps_cloud_identity。
      navigatePath	目标页面路径。取值如下： /session/764153****：某个扣子 Agent。 https://code.coze.cn/home：扣子编程主页 https://code.coze.cn/space：扣子编程工作空间 https://code.coze.cn/space/74****/bot/75****：扣子编程工作空间下的某个智能体 说明 如果路径中包含传参，需要进行 encodeURIComponent 编码。
      type	操作类型，固定值为login。

   2. 将上一步生成的coze_state JSON 字符串进行encodeURIComponent编码。
2. 构造 redirect_uri。
   1. 将云身份中心实例名、client_id 、编码后的coze_state等参数填入模板。

      const redirect_uri = `https://${instance_name}.volccloudidentity.com/api/cloudidentity/authorize/federateOAuth?client_id=9836804098&state=${encodeURIComponent(coze_state)}&response_type=code&redirect_uri=https%3A%2F%2Fwww.coze.cn%2Fauth%2Fcallback&scenario=coze`
      

      参数	说明
      instance_name	云身份中心实例名称。
      client_id	云身份中心的client_id，固定值为9836804098。
      state	步骤 1 中生成的编码后的 coze_state 字符串。
      response_type	响应类型，固定值为 code。
      redirect_uri	扣子的回调地址，固定值为 https%3A%2F%2Fwww.coze.cn%2Fauth%2Fcallback。
      scenario	场景标识，固定值为 coze。

   2. 对整个redirect_uri再执行一次 URL 编码，得到encodeURIComponent(redirect_uri)。
3. 构造state参数。
   将编码后的redirect_uri作为值，拼接到redirect_uri=前缀后，再执行一次 URL 编码，得到最终用于 OAuth 请求的state参数：

   const state = encodeURIComponent('redirect_uri=' + encodeURIComponent(redirect_uri))
   

4. 构造完整的 SSO 登录地址。
   将云身份中心EntityID和最终的state参数填入地址模板：

   https://signin.volcengine.com/cloud-identity/cn-beijing/${entity_id}/userlogin/oauth/sso?state=${state}
   

   用户访问该地址，即可完成 OAuth SSO 登录并直接跳转扣子或扣子编程的指定页面。