问题引入
近期在折腾单点登录, 了解到了 keycloak 这个工具, 简单的用 Docker 部署之后, 发现 Harbor 可以用 OIDC 接入, 就动了试试看的心思.
在按照官方文档简单的配置后, 很快就完成了基础登陆的配置, 但面对 OIDC Admin Group 功能我陷入了沉默, 官方文档对此介绍少之又少, 在一番折腾后我也是成功配置了, 故此写下这篇博文留做记录.
环境说明
keycloak 版本: 26.0.6
Harbor 版本: v2.10.2-1a741cb7-aarch64
字段约定与介绍
Keycloak
Token: 自身携带信息的用户身份凭证, 通过 keycloak 接口可以解析出来其中的信息, 一般是一个 json.Client: 能够操作的程序所能调用的接口, 这些接口的 Endpoint 不同但是接口都是相同的.Role: 角色, 其实就是包含了对某个资源的访问控制描述, 比如读某个资源什么的, 一个用户可以绑定多个角色, 这些角色所代表的权限在一起形成这个用户的最终权限列表.在 Harbor 里被叫做 Group.Clients Role: 客户端角色, 日常管理的最底层权限角色了, 算是比较细的, 针对某一方面的权限了.Realms Role: 领域角色, 你在领域里定义的角色, 一般由多个其他角色组合起来的.
Harbor
Auth Mode: 验证模式, 这里我是选择 OIDC. 要注意的是, 如果使用了本地数据库创建其他用户会导致看不到其他的登陆方式选项Primary Auth Mode: 是否仅使用选中的方式登陆, 选中之后进入登陆状态就直接跳转到单点登录页面无需手动选择了OIDC Provider Name: 一个可视化的名字, 给 SSO 服务起个名字用来显示的OIDC Endpoint: 这里是你的登陆端点, 照着http[s]://your.keycloak.host/realms/your realm name来填写OIDC Client ID: 在 keycloak 里创建的用于登陆的客户端ID, 这个两边一致就好OIDC Client Secret: 在 keycloak 里创建完客户端后, 你查看客户端详情就能在凭证(Secret) 选项卡里复制了OIDC Group Filter: 由于 groups 实际上是一个数组, 为了加快效率或者增加安全性, 你能写一个正则表达式来匹配生效的组名, 我在这里直接留空了Group Claim Name: Token 中存储 Groups 的字段名OIDC Admin Group: 当 Groups 这个列表中包含这个组名时, 就认为这个 Token 是管理员OIDC Scope: 参照文档, 这里需要填成openid,profile,email,offline_access, 其他的可以自由扩充Verify Certificate: 是否验证 SSL 证书, 如果你站点的 SSL 证书(让 HTTP 转 HTTPS 那个证书)是自己签发的(不由 CA 验证), 就要关掉这个选项Automatic onboarding: 直接从 OICD 回传的 Token 中取出字段来填充用户信息, 需要勾上Username Claim: 存储用户名的字段名, 这个字段应该填为preferred_username
操作引导
在开始操作之前, 我默认你完成了以下步骤:
1. 完成了 Harbor 的搭建并以管理员身份登陆了账号, 如果没有那你需要参阅 Harbor Installation and Configuration
2. 完成了 keycloak 的搭建, 如果没有那你需要参阅 keycloak - guides 里的 Getting started
3. 创建了一个 master 以外的 realm , 在本示例中, 这个 realm 的 realm name 为 sso. 如果没有那你需要参阅 Creating a realm
2. 在你新创建的 realm 有至少一个用户并设置了密码, 如果没有那你需要参阅 Creating users
在 Keycloak 创建客户端
首先参阅 Keycloak – Create Realm, Client, Roles, and User 创建客户端, 其中一些字段如下所述填写:
Client type: OpenID ConnectClient ID: 填写个你喜欢的, 但需要记下来, 等会要用. 这里的示例为harborName: 填写个你喜欢的, 这里的示例为harborClient authentication:OnRoot URL:http[s]://Home URL:http[s]://Valid redirect URIs:http[s]:///c/oidc/callbackValid post logout redirect URIs:http[s]://Web origins:http[s]://
创建完成后, 点击左侧的 Clients -> your client id (e.g. harbor) -> credentials, 直接复制 Client Secret 等会备用
在 Keycloak 创建客户端范围
点击左侧的 Client scopes -> Create client scope, 创建客户端范围, 其中一些字段如下所述填写:
Name: 给此范围起一个名字, 可以随便起, 不会影响最终结果. 在本示例中为groupsType:DefaultProtocol:OpenID ConnectDisplay on consent screen:OffInclude in token scope:On
完成后点击 Save 即可保存, 接下来点击左侧的 Client scopes -> your client scope Name (e.g. groups) -> Mappers -> Add mapper -> From predefined mappers
在弹出的对话框左上角搜索 groups, 勾选结果中的 groups 后点击 Add
将 groups 字段放入 Token 中
点击左侧的 Clients -> your client id (e.g. harbor) -> Client scopes -> Add client scope
在弹出的对话框左上角搜索 groups, 勾选结果中的 groups 后点击 Add -> Default
创建领域角色并将其分配到一个组
创建领域角色
点击左侧的 Realm roles -> Create role, 创建领域角色, Role name 填你希望的名称. 在本例中为 harboradmin.
接下来是一个进阶操作, 将一个用户组与某个角色绑定, 这样你就可以不用手动给用户分配角色了. 如果你不需要, 你现在就可以直接给用户指定领域角色然后跳过本大节.
创建成员组
点击左侧的 Groups -> Create group, 创建成员组, Name 填你希望的名称. 在本例中为 harboradmin.
将组与角色关联
点击左侧的 Groups -> your group name (e.g. harboradmin) -> Role mapping -> Assign role
在弹出的对话框中, 点击左上角的过滤器切换到 Filter by realm roles 在勾选我们刚刚创建的 harboradmin 角色后点击 Assign保存配置.
在 Harbor 中配置 OIDC
接下来使用管理员身份打开 Harbor, 点击左侧的 Administration -> Configuration.
将 Auth Mode 切换为 OICD, 如果你看不到或者无法操作, 说明在 Harbor 的本地数据库中存在其他用户, 请删除后再继续.
其余字段如下所示:
OIDC Provider Name: 填你喜欢的就好, 会显示在 Harbor 的登陆界面OIDC Endpoint: 照着http[s]://your.keycloak.host/realms/your realm name来填写OIDC Client ID: 创建客户端时设置的客户端 ID. 在本示例中应该填harborOIDC Client Secret: 刚才在客户端配置时复制的Secret还记得吗? 不记得也没关系, 去复制就好Group Claim Name: 我们在客户端范围里搜索到的groups字段. 这里就填groupsOIDC Admin Group: 我们刚刚创建的角色harboradmin. 这里就填harboradminOIDC Scope:openid,profile,email,offline_accessVerify Certificate:OnAutomatic onboarding:OnUsername Claim:preferred_username
完成后, 就可以在新的隐私浏览器窗口进行测试