diff --git a/docSite/assets/imgs/sso18.png b/docSite/assets/imgs/sso18.png new file mode 100644 index 000000000..fb247abaf Binary files /dev/null and b/docSite/assets/imgs/sso18.png differ diff --git a/docSite/assets/imgs/sso2.png b/docSite/assets/imgs/sso2.png index ce8269456..0cfa4f5d0 100644 Binary files a/docSite/assets/imgs/sso2.png and b/docSite/assets/imgs/sso2.png differ diff --git a/docSite/content/zh-cn/docs/guide/admin/sso.md b/docSite/content/zh-cn/docs/guide/admin/sso.md index 3ca90d6e2..b29a4bb14 100644 --- a/docSite/content/zh-cn/docs/guide/admin/sso.md +++ b/docSite/content/zh-cn/docs/guide/admin/sso.md @@ -24,6 +24,8 @@ FastGPT-pro 中,有一套标准的SSO 和成员同步接口,系统会根据 FastGPT-SSO-Service 是为了聚合不同来源的 SSO 和成员同步接口,将他们转成 fastgpt-pro 可识别的接口。 + ![](/imgs/sso2.png) + ## 系统配置教程 ### 1. 部署 SSO-service 镜像 @@ -344,59 +346,128 @@ fastgpt-sso: 以下是 FastGPT-pro 中,SSO 和成员同步的标准接口文档,如果需要对接非标准系统,可以参考该章节进行开发。 -![](/imgs/sso2.png) +![](/imgs/sso18.png) FastGPT 提供如下标准接口支持: -1. https://example.com/getAuthURL 获取鉴权重定向地址 +1. https://example.com/login/oauth/getAuthURL 获取鉴权重定向地址 2. https://example.com/login/oauth/getUserInfo?code=xxxxx 消费 code,换取用户信息 3. https://example.com/org/list 获取组织列表 4. https://example.com/user/list 获取成员列表 -### 获取登录重定向地址 +### 获取 SSO 登录重定向地址 -返回一个重定向登录地址,fastgpt 会自动重定向到该地址。 +返回一个重定向登录地址,fastgpt 会自动重定向到该地址。redirect_uri 会自动拼接到该地址的 query中。 -redirect_uri 会自动拼接到该地址的 query中。 +{{< tabs tabTotal="2" >}} +{{< tab tabName="请求示例" >}} +{{< markdownify >}} + +```bash +curl -X GET "https://redict.example/login/oauth/getAuthURL?redirect_uri=xxx&state=xxxx" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` + +{{< /markdownify >}} +{{< /tab >}} + +{{< tab tabName="响应示例" >}} +{{< markdownify >}} + +成功: -GET /login/oauth/getAuthURL ```JSON { "success": true, - "message": "错误信息", + "message": "", "authURL": "https://example.com/somepath/login/oauth?redirect_uri=https%3A%2F%2Ffastgpt.cn%2Flogin%2Fprovider%0A" } ``` -### 获取用户信息 - -该接口接受一个 code 参数作为鉴权,消费 code 返回用户信息。 - -https://oauth.example/login/oauth/getUserInfo?code=xxxx - -GET /login/oauth/getUserInfo?code=xxxxxx -返回如下信息(JSON): +失败: ```JSON { - "success": true, - "message": "错误信息", - "username": "用户名,用于注册 fastgpt,全局唯一的, fastgpt不会自动拼接任何前缀", - "avatar": "头像,可以为空", - "contact": "联系方式,最好不为空" + "success": false, + "message": "错误信息", + "authURL": "" } ``` +{{< /markdownify >}} +{{< /tab >}} +{{< /tabs >}} + + +### SSO 获取用户信息 + +该接口接受一个 code 参数作为鉴权,消费 code 返回用户信息。 + +{{< tabs tabTotal="2" >}} +{{< tab tabName="请求示例" >}} +{{< markdownify >}} + +```bash +curl -X GET "https://oauth.example/login/oauth/getUserInfo?code=xxxxxx" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` + +{{< /markdownify >}} +{{< /tab >}} + +{{< tab tabName="响应示例" >}} +{{< markdownify >}} + +成功: +```JSON +{ + "success": true, + "message": "", + "username": "fastgpt-123456789", + "avatar": "https://example.webp", + "contact": "+861234567890", + "memberName": "成员名(非必填)", +} +``` + +失败: +```JSON +{ + "success": false, + "message": "错误信息", + "username": "", + "avatar": "", + "contact": "" +} +``` + +{{< /markdownify >}} +{{< /tab >}} +{{< /tabs >}} + ### 获取组织 -1. 同步组织 /org/list +{{< tabs tabTotal="2" >}} +{{< tab tabName="请求示例" >}} +{{< markdownify >}} -GET https://example.com/org/list +```bash +curl -X GET "https://example.com/org/list" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` -⚠️注意:只能存在一个根部门。如果你的系统中存在多个根部门,需要先进行处理,加一个虚拟的根部门。 -返回值类型: +{{< /markdownify >}} +{{< /tab >}} -```typescript +{{< tab tabName="响应示例" >}} +{{< markdownify >}} + +⚠️注意:只能存在一个根部门。如果你的系统中存在多个根部门,需要先进行处理,加一个虚拟的根部门。返回值类型: + +```ts type OrgListResponseType = { message?: string; // 报错信息 success: boolean; @@ -408,11 +479,48 @@ type OrgListResponseType = { } ``` +```JSON +{ + "success": true, + "message": "", + "orgList": [ + { + "id": "od-125151515", + "name": "根部门", + "parentId": "" + }, + { + "id": "od-51516152", + "name": "子部门", + "parentId": "od-125151515" + } + ] +} +``` + +{{< /markdownify >}} +{{< /tab >}} +{{< /tabs >}} + + ### 获取成员 -1. 同步用户 /user/list -GET https://example.com/user/list +{{< tabs tabTotal="2" >}} +{{< tab tabName="请求示例" >}} +{{< markdownify >}} + +```bash +curl -X GET "https://example.com/user/list" \ +-H "Authorization: Bearer your_token_here" \ +-H "Content-Type: application/json" +``` + +{{< /markdownify >}} +{{< /tab >}} + +{{< tab tabName="响应示例" >}} +{{< markdownify >}} 返回值类型: @@ -421,8 +529,7 @@ type UserListResponseListType = { message?: string; // 报错信息 success: boolean; userList: { - username: string; // 唯一 id username 必须与 SSO 接口返回的用户 username 相同 - // 必须携带一个前缀,例如: sync-aaaaa,和 sso 接口返回的前缀一致 + username: string; // 唯一 id username 必须与 SSO 接口返回的用户 username 相同。并且必须携带一个前缀,例如: sync-aaaaa,和 sso 接口返回的前缀一致 memberName?: string; // 名字,作为 tmbname avatar?: string; contact?: string; // email or phone number @@ -430,6 +537,38 @@ type UserListResponseListType = { }[]; } ``` +curl示例 + +```JSON +{ + "success": true, + "message": "", + "userList": [ + { + "username": "fastgpt-123456789", + "memberName": "张三", + "avatar": "https://example.webp", + "contact": "+861234567890", + "orgs": ["od-125151515", "od-51516152"] + }, + { + "username": "fastgpt-12345678999", + "memberName": "李四", + "avatar": "", + "contact": "", + "orgs": ["od-125151515"] + } + ] + +} +``` + +{{< /markdownify >}} +{{< /tab >}} +{{< /tabs >}} + + + ## 如何对接非标准系统