SwanLab

管理员配置 OAuth2 SSO 登录（以 Keycloak 为例） ​

本文说明如何在 SwanLab 中配置 OAuth2 SSO Provider，以及 IdP 侧需要填写的回调地址。

一、功能简介 ​

OAuth2 SSO 适用于只提供 OAuth2 Authorization Code 流程的身份服务。SwanLab 会跳转到 IdP 授权页，使用授权码换取 Access Token，再调用 Userinfo 接口读取第三方用户信息。

账号策略：

  • 首次 OAuth2 登录必须绑定已有 SwanLab 账号。
  • 已绑定用户：认证成功后直接登录。

二、操作流程 ​

2.1 SwanLab 配置 ​

  1. 在 SwanLab 管理员控制面板点击创建 OAuth2

  1. 填写基础配置
字段是否必填说明
名称是Provider 唯一标识，最多 25 个字符，只允许字母、数字、下划线、连字符
展示名称是登录按钮展示的名称，最多 100 个字符

  1. 填写 OAuth2 配置
字段是否必填说明
Client ID是IdP 上配置的 Client ID，一般在 IdP 上配置时手动填写
Client Secret是IdP 分配给 SwanLab 的 OAuth2 Client Secret，一般为 IdP 自动生成，需要从 IdP 获取
授权地址是OAuth2 Authorization Endpoint，不同认证服务可能不同，需要查看 IdP 文档获取
Access Token 地址是使用授权码换取 Access Token 的 Token Endpoint，不同认证服务可能不同，需要查看 IdP 文档获取
用户信息地址是使用 Access Token 拉取用户资料的 Userinfo Endpoint，不同认证服务可能不同，需要查看 IdP 文档获取
Scopes否空格分隔的授权范围，留空时默认 openid profile，但建议手动填写

其中“授权地址”、“Access Token 地址”、“用户信息地址”是 OAuth2 协议内容，但不同服务并没有统一的路径要求，例如对于“授权地址”：

  • keycloak：https://<IdP URL>/realms/<realm name>/protocol/openid-connect/auth
  • authentik: https://<IdP URL>/application/o/authorize/

在这里以 keycloak 为例：

  1. 填写展示配置

图标 URL 推荐填写在线链接

  1. 启用 IdP

创建后即可在列表中查看当前已有 IdP，启用后即可进行测试、使用：

  1. 在登录列表中查看

三、IdP 侧配置 ​

重点需要在 IdP 的 OAuth2 应用中配置 Redirect URI：

text
https://<SwanLab 外部访问地址>/api/auth/sso/oauth2/callback/<Provider 名称>

请确保该地址与 SwanLab 实际生成的地址完全一致，包括协议、域名、端口、子路径和 Provider 名称。 示例：

text
https://swanlab.example.com/api/auth/sso/oauth2/callback/arui-oauth2

以 keycloak 中的配置为例：

Client Secret 一般由 IdP 生成，需要复制并填写到 SwanLab 配置：