单点登录，缩写就是SSO，全称：Single Sign-On 读起来就有种很厉害的感觉：）
实则我们对SSO并不陌生，许多互联网产品，APP应用等都会有SSO的身影，列如：
- 阿里系：登录淘宝后，无需再登录天猫、支付宝、闲鱼（统一用淘宝 / 支付宝账号作为 IdP）；
- 腾讯系：登录微信后，可直接登录微信支付、王者荣耀、腾讯视频、QQ 音乐（微信账号作为 IdP）；
- 谷歌：登录gmail邮箱后就可以使用其他google服务，列如谷歌云盘（drive），广告平台（Adsense等。
许多大公司都有自己的SSO平台，一般是自研或者外采三方平台的，一些小公司为节约成本也在寻求开源方案，今天就给大家介绍一下这款超级不错的SSO开源工具：Keycloak，官网地址：https://www.keycloak.org/，通过实战，我们一步步把SSO跑起来，让你也成为公司最了解SSO的专家！
可能有人会问：“我有开发能力，自己写认证逻辑不行吗？” 当然可以啊，但 Keycloak 真的有好多核心优势，节约时间和精力，还能规避许多风险：
1. 开箱即用，不用重复 “造轮子”
Keycloak 已经帮你封装好了所有常用的认证功能：
基础的账号密码登录、手机验证码登录、邮箱验证；
第三方登录（支持微信、QQ、GitHub、Google 等，不用自己对接第三方接口）；
密码重置、账号锁定（列如输错 5 次密码锁定账号）、会话管理（列如强制用户下线）。
你不用再写 “密码加密存储”“验证码发送” 这些代码，直接调用 Keycloak 的接口就能实现，开发效率至少提升 50%。
2. 支持 “单点登录（SSO）” 和 “单点登出”
这是 Keycloak 最核心的功能之一。列如用户登录了 OA 系统，再打开 CRM 系统时，Keycloak 会自动识别 “用户已经登录过”，不用再输密码；如果用户退出 OA 系统，Keycloak 会同时让 CRM 系统的登录状态失效，避免 “退出了一个系统，另一个系统还在登录” 的安全隐患。
无论是 Web 应用、手机 APP 还是桌面软件，只要对接了 Keycloak，都能实现单点登录，特别适合企业内部多系统的场景。
3. 灵活的权限控制，精细到 “按钮级别”
Keycloak 的权限管理基于 “角色（Role）” 和 “资源（Resource）” 设计，列如：
- 给 “销售经理” 角色分配 “查看所有客户”“修改客户信息” 的权限；
- 给 “普通销售” 角色分配 “查看自己的客户”“新增客户” 的权限；
- 甚至能控制 “某个按钮是否显示”（列如只有管理员能看到 “删除用户” 按钮）。
你不用在应用里写一堆 “if-else 判断权限” 的代码，只需要在 Keycloak 里配置好角色和权限，应用再从 Keycloak 获取用户的权限信息，就能实现权限控制。
4. 开源免费，安全性有保障
Keycloak 是完全开源的，代码可以在 GitHub 上查看（
https://github.com/keycloak/keycloak），没有隐藏收费项；而且 Red Hat 会定期更新补丁，修复安全漏洞（列如防止 SQL 注入、XSS 攻击、CSRF 攻击等），比自己写的认证逻辑更安全 —— 毕竟自己写的代码很容易忽略一些安全细节，列如密码没做加盐哈希，或者会话管理有漏洞。
5. 跨语言、跨平台，兼容性强
不管你的应用是用什么语言开发的（Java、Python、Node.js、Go），也不管是 Web 应用、移动端还是后端接口，Keycloak 都能对接。它支持标准的认证协议（OAuth 2.0、OpenID Connect、SAML 2.0），只要你的应用支持这些协议，就能和 Keycloak 集成 —— 相当于 Keycloak 提供了一个 “通用的认证接口”，所有应用都能对接。
还可以集成LDAP。
下面进入正题
Keycloak 测试环境搭建
环境搭建，还是使用docker最为方便，测试环境启动使用了start-dev命令，没有使用持久化存储，端口映射出来8083
$ cat docker-compose.yml
services:
keycloak:
image: keycloak/keycloak:26.4
container_name: keycloak
restart: always
environment:
KC_BOOTSTRAP_ADMIN_USERNAME: admin
KC_BOOTSTRAP_ADMIN_PASSWORD: myadminpwd
command: start-dev
ports:
- '8083:8080'正常启动后，就可以使用admin/myadminpwd登录了。
看看当前版本状态，26.4.1 哈哈，最新版！
先概述一下Keycloak认证的总体思路，这样更方便各位理解：
就是在Keycloak里配置一个类似于命名空间的东西，在里面配置应用，用户，角色和各种策略。具体的应用（客户端）需要接入到Keycloak，客户端配置好sso auth地址，跳转url，security key等即可。
好，接下来开始具体配置
步骤一：创建 Realm (认证域)
Realm 是 Keycloak 管理的核心。它是一个独立的空间，用于管理一组用户、应用、角色和策略。master Realm 默认存在，但它主要用于管理 Keycloak 自身，最佳实践是为你的所有应用创建一个新的 Realm。
登录后，将鼠标悬停在左上角的 master 字样上。
点击 Create Realm 按钮。
输入一个 Realm name (例如：my-app-realm) 并点击 Create。
创建成功后，Keycloak 会自动切换到你新创建的 my-app-realm。之后的所有操作都将在此 Realm 中进行。
步骤二：配置权限 (Roles)
权限在 Keycloak 中通过 Roles 来定义。Roles 分为两种：
- Realm Roles (领域角色): 全局角色，适用于此 Realm 下的所有应用 (Clients)。例如 admin, user。
- Client Roles (客户端角色): 仅适用于特定应用的角色。例如某个应用独有的 report-generator 角色。
举例 创建 Realm Role (推荐用于通用权限)
在左侧菜单中，确保你处于 my-app-realm 下。
点击 Realm roles。
点击 Create role 按钮。
输入 Role name (例如：user_basic)。
(可选) 输入描述，然后点击 Save。
重复此步骤创建其他角色，例如 admin。
步骤三：配置应用 (Clients)
Client 指的是需要 Keycloak 提供认证服务的应用（例如你的网站、API、移动 App 等）。
在左侧菜单中，点击 Clients。
点击 Create client 按钮。
在 General Settings 步骤中，填写以下信息：
Client type: 保持 OpenID Connect 不变。
Client ID: 你的应用的唯一标识符 (例如：my-web-app)。
在 Capability config 步骤中：
Client authentication: 打开此开关。这表明你的应用是一个“机密客户端”（Confidential Client），能够安全地存储一个密钥，推荐用于后端服务。
Authorization: 保持关闭（除非你需要细粒度的授权服务）。
Authentication flow: 保持 Standard flow（标准登录流程）勾选。
点击 Next。
在 Login settings 步骤中，配置你的应用回调地址：
Root URL: (可选) 你的应用根地址，例如
http://10.133.254.123:5002/。
Valid redirect URIs: [最重大] 登录成功后 Keycloak 将用户重定向回的地址。必须准确匹配。
http://10.133.254.123:5002/auth/callback。
Valid post logout redirect URIs: (可选) 登出后重定向的地址:
http://10.133.254.123:5002/
点击 Save。
获取应用密钥 (Client Secret)：
应用创建成功后，会自动跳转到其配置页面。
切换到 Credentials 标签页。
你会看到一个 Client secret。点击旁边的“复制”图标。
妥善保管这个 Secret。你的后端应用在与 Keycloak 通信时需要用到它和 Client ID。
至此，你的应用 my-web-app 已经注册完毕。
步骤四：创建用户 (Users)
目前，我们来创建一些登录用的账号。
在左侧菜单中，点击 Users。
点击 Create user 按钮。
填写用户信息：
Username: 必填，用户的登录名 (例如：testuser)。
(可选) Email, First name, Last name。
点击 Create。
设置用户密码:
用户创建成功后，自动进入该用户的详情页面。
切换到 Credentials 标签页。
点击 Set password。
输入你的密码，并确认密码。
Temporary: 默认开启。表明用户下次登录时必须修改密码。如果你只是测试，可以将其关闭。
点击 Save，然后再次确认保存。
步骤五：为用户分配权限 (关联 User 和 Role)
这是将用户、应用、权限三者关联起来的关键一步。
在左侧菜单中，点击 Users，然后点击你刚刚创建的 testuser。
切换到 Role mappings 标签页。
点击 Assign role 按钮。
你目前会看到所有可分配的 Realm Roles。
在搜索框中输入或直接在列表中找到你之前创建的 myapp_role 角色。
选中 myapp_role。
点击 Assign。
目前，testuser 用户就拥有了 user_basic 这个 Realm 角色。
看看目前的状态：
OK，以上Keycloak配置已经完毕，接下来配置客户端
客户端我们准备来个Python+Flask的站点，有主页，登录，退出页面等
代码比较长，先截图：
静态资源模版
启动web服务：
python app1.py 监听端口为5002，有两个链接：首页和登录
点击登录后会跳转到keycloak的地址
输入前面创建的用户：testuser账号和密码
登录后的状态：
可以看到拿到了用户的许多信息，测试代码是把这些登录信息都写在了本地硬盘里
token_data = oauth.keycloak.authorize_access_token()
# Authlib 自动从 id_token 或 UserInfo 端点解析用户信息
# (取决于 Keycloak 的配置)
user_info = token_data.get('userinfo')
看看/profile
{
"acr": "1",
"at_hash": "6F0artucXmgd9hp-pINUCw",
"aud": "my-web-app",
"auth_time": 1761008868,
"azp": "my-web-app",
"email": "testuser@aaa.com",
"email_verified": true,
"exp": 1761009168,
"family_name": "user",
"given_name": "test",
"iat": 1761008868,
"iss": "http://10.133.254.123:8083/realms/my-app-realm",
"jti": "621016d7-6782-d150-d2df-48b7a69e68bb",
"name": "test user",
"nonce": "KLvu2UpvXIXKNeJNa42q",
"preferred_username": "testuser",
"sid": "adfd0c0b-e9b7-47e7-7e04-fdc836a2937b",
"sub": "1045c06d-37b7-4978-a54c-8fbb3a72c5b8",
"typ": "ID"
}
点击退出会跳回首页，这也是在keycloak配置的
回到首页
当用户testuser登录进去后，在keycloak console里面也能看到登录用户的session信息
这里点击用户后面的三个点，也可以强制让用户退出登录状态。
如果有多个应用也是类似，只要配置新的client即可，用户可以按组分，也可以按照应用加入。只要在任何一个平台登录过，就可以在所有接入了keycloak的应用中任意穿梭了，人生从此再无阻碍。
我在实际调试和配置中也遇到几个问题，列如：
1. {“error”:”invalid_grant”,”error_description”:”Invalid user credentials”}
2. 无法收到Keycloak的授权码
重点是keycloak几个地址，特别是Valid redirect URIs的配置，再就是新版本的auth地址有所变化，已经没有/auth这样的地址了。
用户的Temporary状态也要去掉，第一次登录默认要修改密码。
如果您也觉着试用着还不错，那么就可以准备生产环境了。
生产环境使用 Keycloak，需要注意以下几点：
1. 改用 “生产模式” 启动
生产环境启动时，需要指定配置文件，并且设置管理员密码（不能像开发模式那样首次访问时设置）：
先创建一个配置文件（列如prod-config.yaml），里面配置数据库、端口、HTTPS 等信息（Keycloak 支持 MySQL、PostgreSQL、Oracle 等数据库，不提议用默认的 H2 内存数据库）；
用命令启动：kc start –config-file=prod-config.yaml。
2. 必须开启 HTTPS
Keycloak 传输的是用户账号密码、授权码等敏感信息，所以必须用 HTTPS 加密。可以给 Keycloak 配置 SSL 证书（列如 Let's Encrypt 的免费证书），或者把 Keycloak 放在反向代理（列如 Nginx）后面，由反向代理处理 HTTPS。
3. 配置数据库持久化
开发模式下，Keycloak 的用户数据、配置信息都存在内存里，重启后就会丢失。生产环境必须把数据存到数据库里（列如 MySQL），在配置文件里指定数据库连接信息即可。
4. 开启集群模式（如果用户量大）
如果你的应用用户量很大，单台 Keycloak 服务器可能扛不住，这时候需要部署 Keycloak 集群：多台 Keycloak 服务器连接同一个数据库，并且配置会话共享（列如用 Redis 存储会话），这样即使其中一台服务器宕机，其他服务器也能正常提供服务。
如果想美化修改主体，也可以定制和修饰一番
因文章长度有限，需要完整演示代码的可以私信发出。
（全文完）
暂无评论内容