Centos7 搭建KeyCloak 26.1.2 版本（一）--安装篇

零：规划

        KeyCloak 是一款完全开源免费的统一认证平台，其开发社区活跃，非常适合于没有时间和精力独立开发的小公司。但是这个系统在网上的中文资料比较少，我在搭建的过程中结结实实的踩了不少坑，因此打算把我的操作步骤记录下来预祝微分享。

        根据 KeyCloak 官网 介绍，它的安装依赖jdk和本地数据库的支持。其中最新的 26.1.2 版本要求jdk21、MySQL8.4 或PostGreSql 15.x，故而本次的部署也按照官网要求进行，操作系统选择 Centos7.9，数据库选择 MySQL8.4。

        一些重要的前置知识请参考 TLS与自签名证书的创建、作用、用到的工具等知识的介绍

一、准备工作

        1.1、安装 操作系统

        操作系统安装请参考  centos7 系统安装。然后 更新 yum源 。

        1.2、安装 jdk21、MySQL8.4

           与 MySQL8 安装篇请参考前面两个连接。

        然后在 MySQL 上创建 keycloak 使用的数据库，我创建的数据库名就叫“keycloak”

        1.3、关闭selinux和防火墙

        请参考我这两个帖子 如何关闭selinux  ，如何关闭 firewall和 iptables 。

        1.4、下载 keycloak

        点击 KeyCloak 官网下载地址 下载。如下图所示

​

二、安装与配置

        2.1、解压

        将下载到的 KeyCloak-26.1.2.zip 包放到服务器的 /usr/local/目录下，执行命令得到解压后的目录，如下图所示

​

        2.2、安装OpenSSL 并生成私钥

        OpenSSL 的安装方法见本文 OpenSSL 与 自签名Https证书的介绍及用法-CSDN博客。生成密钥的方法如下所示。

## 这里我将keycloak.crt 和 keycloak.key 的输出路径都指定了，方便后续再配置文件中使用
## 另外需注意，这两个文件的有效期是 365天。
## 这里我使用的crt和key文件名称就是 keycloak。诸位可以自行指定，
[root@keycloak conf]# openssl req -x509 -newkey rsa:4096 -keyout /etc/pki/tls/private/keycloak.key -out /etc/pki/tls/certs/keycloak.crt -days 365 -nodes -subj "/C=CN/ST=Beijing/L=Beijing/O=Example/CN=keycloak.example.com"

        2.4、修改配置文件

        进入 /usr/local/keycloak-26.1.2/conf 目录，修改 keycloak.conf 文件，如下图所示

# Basic settings for running in production. Change accordingly before deploying the server.

# Database

# 指定数据库，如果使用 PostGreSql，则写成 db=postgres
db=mysql

# 目标数据库登录名称
db-username=dark

# 目标数据库的登录密码
db-password=darkPwd123

# 目标数据库的访问url。请替换自己的 ip 、 端口号 、 数据库名（我的数据库名称为 keycloak，可任意修改）
db-url=jdbc:mysql://192.168.159.136:3306/keycloak?useSSL=false&allowPublicKeyRetrieval=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai
# Observability

# 健康度检查，目前暂未测试
# health-enabled=true

# If the server should expose metrics endpoints.
# metrics-enabled=true

# HTTP

# The file path to a server certificate or certificate chain in PEM format.
#https-certificate-file=${kc.home.dir}conf/server.crt.pem

# The file path to a private key in PEM format.
# https-certificate-key-file=${kc.home.dir}conf/server.key.pem

# The proxy address forwarding mode if the server is behind a reverse proxy.
# proxy=reencrypt

# Do not attach route to cookies and rely on the session affinity capabilities from reverse proxy
# spi-sticky-session-encoder-infinispan-should-attach-route=false

# Hostname for the Keycloak server.
# 这里的服务器名称慎用，我之前使用了服务器的别名 keycloak之后访问 http://192.168.159.137:8080 的时候跳转到 http://keycload:8080 。但是我把这里注销后就解决了上面的问题
# hostname=keycloak

# 是否允许 使用http 协议而不用 https 的方式登录
http-enabled=true
#下面是https 私钥的配置地址，会在下面说明如何创建和配置、使用
https-certificate-file=/etc/pki/tls/certs/keycloak.crt
https-certificate-key-file=/etc/pki/tls/private/keycloak.key

         配置文件中各个属性的作用我基本都做了说明，请务必仔细了解。

        2.5、关闭防火墙

        操作方法见 centos7的防火墙区别与选择（不断更新）

三、启动

       3.1、尝试启动

        首次启动keycloak 会向数据库创建需要用到的表。同时首次启动的命令推荐如下

[root@keycloak2 bin]# ./kc.sh start-dev --http-port=8080

         用上面的命令启动后，暂时无法真正进入系统，会看到如下的拦截界面。

        3.2 、创建admin用户

        原因是尚未创建 admin用户。而 kc.sh start-dev 属于开发模式，是不能创建管理员账号，因此需要停掉服务重来一次。命令如下

[root@keycloak2 bin]# ./kc.sh bootstrap-admin user --username admin

        执行上面命令的过程中，会让你输入密码并二次确认。执行过程中会告诉我们已经初始化了一系列内容，如下图的红框中所示。（PS：其实应该先创建 admin 用户，然后再以dev模式启动keycloak 才对吧。。。是我上面的次序错了吧。。。）

        3.3、登录 

        创建完 admin账号并完成初始化后，keycloak 会退出命令，此时我们再以 dev模式启动（ ./kc.sh start-dev --http-port=8080），就可以看到如下界面。

        这时，说明真的启动了。输入admin账号和刚刚设置的密码 登录后就看到如下界面。

        3.4、Https 模式

        上面是在 dev 模式下测试使用，在正式上线前肯定要模拟Https 环境使用，如果在启动命令中指定了启动端口参数，那么同时必须指定启动主机/域名。Https 的启动命令如下。

## https-port 参数用于指定https协议端口， hostname 参数用于指定域名，目前尚无域名，因此用服务器ip代替。
[root@keycloak bin]# ./kc.sh start --https-port=8443 --hostname=192.168.159.137

        也可以使用除了8080和8443之外的其他端口。命令如下

[root@keycloak bin]# ./kc.sh start --https-port=8089 --hostname=192.168.159.137

四、问题与心得

        4.1、先建admin后启动

        其实我在第三章那里的执行次序错了， 应该先创建 admin 然后再以 dev 模式启动。但是这个帖子其实是完美复刻了我当时的操作步骤。我也没再次测试如果先创建 admin后启动会怎样。至少大家按照我的操作步骤绝对能把 keycloak启动起来，如果我后续有时间会尝试一下我的设想，然后再在这里说明。

        4.2、更换端口

        这个挺简单，可以直接在启动命令中指定端口，但同时要指定启动的域名或主机名（不需要修改配置文件中的 hostname 属性），示例如下

./kc.sh start --https-port=8089 --hostname=192.168.159.137