1 基础知识

1.1 软件介绍

– Keycloak支持以最小代价为应用程序或安全服务提供身份验证，而程序无需处理存储用户或验证用户。
– Keycloak支持提供用户联合、强身份验证、用户管理、细粒度授权等。

1.2 软件特点

– 支持单点登录，即Single Sign-On，一次登录即可访问多个应用程序。
– 支持标准协议，支持OpenID Connect、OAuth 2.0和SAML 2.0。
– 支持集中管理，针对管理员和用户。
– 支持适配器，适配器支持开发者快速集成身份验证和授权机制，确保应用程序的安全性。
– 支持LDAP和Active Directory，兼容企业当前用户。
– 支持社交登录，可轻松启用社交登录，降低用户注册和登录的障碍
– 支持身份代理，即Identity Brokering，支持使用外部身份提供者进行身份验证。
– 支持高性能，系统轻量设置，能够快速响应请求，支持大规模用户同时访问
– 支持集群，通过集群架构，可确保系统高负载环境下仍然保持稳定和提供高可用性。
– 支持主题，允许企业根据平台要求调整用户界面的外观。
– 支持扩展，支持开发者通过编写代码扩展系统功能，以满足特点业务需求。
– 支持密码策略，管理员可根据安全需求定制密码策略，增强系统安全性。

2 最佳实践

2.1 系统环境

2.1.1 系统信息

OS = RHEL 9.x x86_64
HostName = any
IP Address = 10.168.0.54

2.1.2 更新系统并重启系统

dnf update -y
reboot

2.1.3 安装OpenJDK

dnf install -y java-17-openjdk

安装完成后，你需要使用如下命令确认Java运行时可用，

java -version

可见如下输出，

openjdk version "17.0.12" 2024-07-16 LTS
OpenJDK Runtime Environment (Red_Hat-17.0.12.0.7-1) (build 17.0.12+7-LTS)
OpenJDK 64-Bit Server VM (Red_Hat-17.0.12.0.7-1) (build 17.0.12+7-LTS, mixed mode, sharing)

2.2 部署前的准备

2.2.1 安装所需的软件包

dnf install -y wget unzip vim

2.2.2 下载软件包

wget --no-check-certificate https://access.redhat.com/cspdownload/308a313aac2c3ca5c5082c192f03b943/68831b61/rhbk-26.2.5/rhbk-26.2.5.zip

以上只是下载演示，如果不能下载请从如下连接下载，本章将下载“Red Hat build of Keycloak 26.2.5 Server”作为部署的软件包。
https://access.redhat.com/products/red-hat-build-of-keycloak

2.2.3 解压软件包

unzip rhbk-26.2.5.zip 

2.3 部署应用

2.3.1 创建运行用户

groupadd  -g 987 keycloak
useradd -u 987 -g 987 -d /var/lib/keycloak -s /sbin/nologin keycloak

2.3.2 部署软件包

mkdir /opt/keycloak/
mv rhbk-26.2.5 mkdir /opt/keycloak/

2.3.3 设置环境变量

vim /etc/profile.d/rhbk.sh

输入如下配置，

export RHBK_HOME=/opt/keycloak/rhbk-26.2.5
export PATH=${RHBK_HOME}/bin:$PATH

另外，如果想快速配置，可使用如下命令，

echo 'export RHBK_HOME=/opt/keycloak/rhbk-26.2.5' > /etc/profile.d/rhbk.sh
echo 'export PATH=${RHBK_HOME}/bin:$PATH' >> /etc/profile.d/rhbk.sh

配置完成后，可使用如下命令导入环境变量，

source /etc/profile

然后，你需要使用如下命令测试环境变量的声明，

kc.sh -V

可见如下输出，

Keycloak 26.2.5.redhat-00001
JVM: 17.0.12 (Red Hat, Inc. OpenJDK 64-Bit Server VM 17.0.12+7-LTS)
OS: Linux 5.14.0-503.11.1.el9_5.x86_64 amd64

2.3.4 部署目录

ln -s /opt/keycloak/rhbk-26.2.5/conf /etc/keycloak
chown keycloak:keycloak -R /opt/keycloak/rhbk-26.2.5/

2.4 配置应用

2.4.1 测试服务启动

sudo -u keycloak bash -c '/opt/keycloak/rhbk-26.2.5/bin/kc.sh start-dev --bootstrap-admin-username tmpadm --bootstrap-admin-password tmpadmpwd'

可见如下显示，

Updating the configuration and installing your custom providers, if any. Please wait.
2025-07-25 15:46:45,362 INFO  [io.quarkus.deployment.QuarkusAugmentor] (main) Quarkus augmentation completed in 5708ms
Running the server in development mode. DO NOT use this configuration in production.
2025-07-25 15:46:50,176 INFO  [org.keycloak.quarkus.runtime.storage.database.liquibase.QuarkusJpaUpdaterProvider] (main) Initializing database schema. Using changelog META-INF/jpa-changelog-master.xml
2025-07-25 15:46:53,311 INFO  [org.keycloak.quarkus.runtime.storage.infinispan.CacheManagerFactory] (main) Starting Infinispan embedded cache manager
2025-07-25 15:46:53,372 INFO  [org.keycloak.quarkus.runtime.storage.infinispan.CacheManagerFactory] (main) JGroups JDBC_PING discovery enabled.
2025-07-25 15:46:53,662 INFO  [org.infinispan.CONTAINER] (main) ISPN000556: Starting user marshaller 'org.infinispan.commons.marshall.ImmutableProtoStreamMarshaller'
2025-07-25 15:46:53,985 INFO  [org.keycloak.connections.infinispan.DefaultInfinispanConnectionProviderFactory] (main) Node name: node_481693, Site name: null
2025-07-25 15:46:54,256 INFO  [org.keycloak.services] (main) KC-SERVICES0050: Initializing master realm
2025-07-25 15:46:55,977 INFO  [org.keycloak.services] (main) KC-SERVICES0077: Created temporary admin user with username tmpadm
2025-07-25 15:46:56,123 INFO  [io.quarkus] (main) Keycloak 26.2.5.redhat-00001 on JVM (powered by Quarkus 3.20.0.redhat-00002) started in 10.660s. Listening on: http://0.0.0.0:8080
2025-07-25 15:46:56,123 INFO  [io.quarkus] (main) Profile dev activated. 
2025-07-25 15:46:56,123 INFO  [io.quarkus] (main) Installed features: [agroal, cdi, hibernate-orm, jdbc-h2, keycloak, narayana-jta, opentelemetry, reactive-routes, rest, rest-jackson, smallrye-context-propagation, vertx]

你可以使用如下命令查看运行的进程，

pgrep -u keycloak java -a

可见如下输出，

3408961 java -Dkc.config.built=true -Djava.util.concurrent.ForkJoinPool.common.threadFactory=io.quarkus.bootstrap.forkjoin.QuarkusForkJoinWorkerThreadFactory -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Dfile.encoding=UTF-8 -Dsun.stdout.encoding=UTF-8 -Dsun.err.encoding=UTF-8 -Dstdout.encoding=UTF-8 -Dstderr.encoding=UTF-8 -XX:+ExitOnOutOfMemoryError -Djava.security.egd=file:/dev/urandom -XX:+UseG1GC -XX:FlightRecorderOptions=stackdepth=512 -Xms64m -Xmx512m --add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.util.concurrent=ALL-UNNAMED --add-opens=java.base/java.security=ALL-UNNAMED -Duser.language=en -Duser.country=US -Dkc.home.dir=/opt/keycloak/rhbk-26.2.5/bin/.. -Djboss.server.config.dir=/opt/keycloak/rhbk-26.2.5/bin/../conf -Djava.util.logging.manager=org.jboss.logmanager.LogManager -Dpicocli.disable.closures=true -Dquarkus-log-max-startup-records=10000 -cp /opt/keycloak/rhbk-26.2.5/bin/../lib/quarkus-run.jar io.quarkus.bootstrap.runner.QuarkusEntryPoint --profile=dev start-dev --bootstrap-admin-username tmpadm --bootstrap-admin-password tmpadmpwd

你可以使用如下命令查看端口倾听，

ss -antp | grep $(pgrep -u keycloak java)

可见如下输出，

LISTEN 0      50     [::ffff:127.0.0.1]:38073            *:*     users:(("java",pid=3404360,fd=303))                        
LISTEN 0      4096                    *:8080             *:*     users:(("java",pid=3404360,fd=348))  

根据以上的端口需求，你需要执行如下命令开放端口，

firewall-cmd --permanent --add-port 8080/tcp
firewall-cmd --reload
firewall-cmd --list-all

然后，使用如下连接测试服务，
http://10.168.0.54:8080/
可见如下显示，

2.4.2 创建服务控制脚本

vim /etc/systemd/system/keycloak.service

加入如下配置，

[Unit]
Description=Redhat build of Keycloak (RHBK)
Requires=network.target
After=syslog.target network.target

[Service]
Type=simple
User=keycloak
Group=keycloak
WorkingDirectory=/opt/keycloak/rhbk-26.2.5
ExecStart=/usr/bin/bash -c '/opt/keycloak/rhbk-26.2.5/bin/kc.sh start-dev --bootstrap-admin-username tmpadm --bootstrap-admin-password tmpadmpwd'
Restart=on-failure
StandardOutput=journal
LimitNOFILE=102642

[Install]
WantedBy=multi-user.target

配置创建后，你需要使用如下命令重载服务使配置生效，

systemctl daemon-reload

测试服务启动并设置自动运行，

systemctl start keycloak.service
systemctl enable keycloak.service

如果遇到启动异常，请使用如下命令查看日志，

journalctl -u keycloak.service -b

2.4.3 测试登录

http://10.168.0.54:8080/

User: tmpadm
Password: tmpadmpwd

参阅文档
================
keycloak github
——————–
https://github.com/keycloak/keycloak

keycloak官方文档
——————-
https://www.keycloak.org/documentation.html
https://www.keycloak.org/server/bootstrap-admin-recovery

Red Hat的keycloak文档
—————-
https://docs.redhat.com/zh-cn/documentation/red_hat_build_of_keycloak/26.2/html-single/getting_started_guide/index