Keycloak 入门实战(2)--安装
本文主要介绍 Keycloak 的安装，使用到的软件版本：JDK 1.8.0_151、Keycloak 16.1.1、Redhat 6.6。
1、standalone mode--独立模式安装
1.1、下载安装包并解压
下载地址：https://www.keycloak.org/downloads
解压：
tar zxvf keycloak-16.1.1.tar.gz
1.2、修改ip
默认绑定的地址为 127.0.0.1，可修改为具体的 ip，编辑 standalone/configuration/standalone.xml：
<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:10.49.196.10}"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address:10.49.196.10}"/> </interface> </interfaces>
1.3、启动
nohup bin/standalone.sh &
1.4、访问控制台
http://10.49.196.10:8080/
1.5、增加用户
可以通过 http://localhost:8080/auth 页面 或 bin/add-user-keycloak.sh 脚本增加用户，如果部署在 linux 服务器上无法通过 http://localhost:8080/auth 来访问页面，可通过脚本来增加用户：
bin/add-user-keycloak.sh -u admin
设置密码后，用户增加成功；需重启应用才能使用该用户登录系统。
1.6、使用 MySQL
Keycloak 默认使用的是 h2 数据库，可根据需要改为其他的数据，这里演示改为 MySQL。
1.6.1、安装 MySQL 驱动
创建 MySQL 模块目录：
cd /modules/system/layers/base/com mkdir -p mysql/main
上传 mysql-connector-java-8.0.28.jar 到 modules/system/layers/base/com/mysql/main 目录，并在该目录下创建 module.xml 文件：
<?xml version="1.0" encoding="UTF-8"?> <module name="com.mysql" xmlns="urn:jboss:module:1.9"> <resources> <resource-root path="mysql-connector-java-8.0.28.jar"/> </resources> <dependencies> <module name="javax.api"/> <module name="javax.transaction.api"/> </dependencies> </module>
1.6.2、修改数据源
修改 standalone/configuration/standalone.xml 文件：
<subsystem xmlns="urn:jboss:domain:datasources:6.0"> <datasources> <datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}"> <connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url> <driver>h2</driver> <security> <user-name>sa</user-name> <password>sa</password> </security> </datasource> <datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="${wildfly.datasources.statistics-enabled:${wildfly.statistics-enabled:false}}"> <!--connection-url>jdbc:h2:${jboss.server.data.dir}/keycloak;AUTO_SERVER=TRUE</connection-url--> <connection-url>jdbc:mysql://10.49.196.10:3306/keycloak?useUnicode=true&characterEncoding=UTF-8&useSSL=false</connection-url> <driver>mysql</driver> <security> <user-name>root</user-name> <password>123456</password> </security> </datasource> <drivers> <driver name="h2" module="com.h2database.h2"> <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class> </driver> <driver name="mysql" module="com.mysql"> <xa-datasource-class>com.mysql.cj.jdbc.MysqlXADataSource</xa-datasource-class> </driver> </drivers> </datasources> </subsystem>
1.6.3、重启应用
重启应用后，Keycloak 会自动在 MySQL 中初始化表；初始化完成后，需重新增加用户。
2、standalone clustered mode--独立集群模式安装
2.1、集群规划
| ip | 安装软件 |
| 10.49.196.10 | keycloak |
| 10.49.196.11 | keycloak |
| 10.49.196.12 | nginx |
2.2、先在一台机器上(10.49.196.10)安装 Keycloak
2.2.1、配置为使用 MySQL 数据库
步骤与 1.6、使用 MySQL 一致，但这里修改的配置文件为 standalone/configuration/standalone-ha.xml。
2.2.2、修改 ip
修改 standalone/configuration/standalone-ha.xml：
<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:10.49.196.10}"/> </interface> <interface name="private"> <inet-address value="${jboss.bind.address.private:10.49.196.10}"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address:10.49.196.10}"/> </interface> </interfaces>
2.2.3、设置 proxy-address-forwarding 为 true
编辑 standalone/configuration/standalone-ha.xml：
<server name="default-server"> <ajp-listener name="ajp" socket-binding="ajp"/> <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true" proxy-address-forwarding="true"/> <https-listener name="https" socket-binding="https" ssl-context="applicationSSC" enable-http2="true"/> <host name="default-host" alias="localhost"> <location name="/" handler="welcome-content"/> <http-invoker http-authentication-factory="application-http-authentication"/> </host> </server>
2.2.4、启动
nohup bin/standalone.sh --server-config=standalone-ha.xml &
2.3、在 10.49.196.11 上以同样的方式安装 Keycloak
如果集群有多台，也是同样的安装方式。
2.4、增加用户
只需在一台机器上执行该操作即可。
bin/add-user-keycloak.sh -u admin
用户增加完成后，重启该服务器上的 Keycloak 即可。
2.5、配置代理
这里使用 nginx 作为代理服务器，其配置文件如下：
upstream keycloak { server 10.49.196.10:8080 weight=1; server 10.49.196.11:8080 weight=1; ip_hash; } server { listen 8080; server_name localhost; location /auth { proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-Port $server_port; proxy_pass http://keycloak/auth; } error_page 500 502 503 504 /50x.html; location = /50x.html { root html; } }
这里建议开启 ip_hash，因为 keycloak 默认只会在一台机器上缓存会话信息，如果会话信息不在本机器上会远程查找，这样会影响效率。
启动 nginx 后，通过 http://10.49.196.12:8080/ 来访问 Keycloak。
2.6、使用 JDBC_PING 协议(可选)
Keycloak 集群间信息同步默认使用 udp 方式下的 PING 协议，可以根据需要该为 tcp 方式或 改为 JDBC_PING 协议。这里演示修改为 JDBC_PING 协议。修改 standalone/configuration/standalone-ha.xml：
<subsystem xmlns="urn:jboss:domain:jgroups:8.0"> <channels default="ee"> <channel name="ee" stack="udp" cluster="ejb"/> </channels> <stacks> <stack name="udp"> <transport type="UDP" socket-binding="jgroups-udp"/> <!--protocol type="PING"/--> <protocol type="JDBC_PING"> <property name="datasource_jndi_name">java:jboss/datasources/KeycloakDS</property> <property name="initialize_sql">CREATE TABLE IF NOT EXISTS JGROUPSPING (own_addr varchar(200) NOT NULL, cluster_name varchar(200) NOT NULL, updated TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, ping_data varbinary(5000) DEFAULT NULL, PRIMARY KEY (own_addr, cluster_name)) </property> </protocol> <protocol type="MERGE3"/> <socket-protocol type="FD_SOCK" socket-binding="jgroups-udp-fd"/> <protocol type="FD_ALL"/> <protocol type="VERIFY_SUSPECT"/> <protocol type="pbcast.NAKACK2"/> <protocol type="UNICAST3"/> <protocol type="pbcast.STABLE"/> <protocol type="pbcast.GMS"/> <protocol type="UFC"/> <protocol type="MFC"/> <protocol type="FRAG3"/> </stack> <stack name="tcp"> <transport type="TCP" socket-binding="jgroups-tcp"/> <socket-protocol type="MPING" socket-binding="jgroups-mping"/>
...
所有节点修改后，重启 Keycloak 即可。
3、domain clustered mode--域集群模式安装
3.1、集群规划
| ip | 安装软件 |
| 10.49.196.10 | keycloak master |
| 10.49.196.11 | keycloak slave |
| 10.49.196.12 | nginx |
3.2、先在 10.49.196.10 上安装 keycloak master
该模式对应的配置文件为 domain/configuration/domain.xml，该文件中有三个 profile，一般的修改都是针对 auth-server-clustered profile：
3.2.1、配置为使用 MySQL 数据库
步骤与 1.6、使用 MySQL 一致，这里修改的地方为 domain/configuration/domain.xml 中 auth-server-clustered profile 下对应的配置。
3.2.2、设置 proxy-address-forwarding 为 true
编辑 domain/configuration/domain.xml：
<server name="default-server"> <ajp-listener name="ajp" socket-binding="ajp"/> <http-listener name="default" socket-binding="http" redirect-socket="https" enable-http2="true" proxy-address-forwarding="true"/> <https-listener name="https" socket-binding="https" ssl-context="applicationSSC" enable-http2="true"/> <host name="default-host" alias="localhost"> <location name="/" handler="welcome-content"/> <http-invoker http-authentication-factory="application-http-authentication"/> </host> </server>
3.2.3、修改 ip
编辑 domain/configuration/host-master.xml：
<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:10.49.196.10}"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address:10.49.196.10}"/> </interface> </interfaces>
3.2.4、启动
cd bin nohup ./domain.sh --host-config=host-master.xml -Djboss.bind.address.private=10.49.196.40 &
3.2.5、访问单点 Keycloak
使用域集群模式时，Keycloak 端口相对 8080 有个偏移量，具体可参考 domain/configuration/host-master.xml：
<servers> <server name="load-balancer" group="load-balancer-group"> <jvm name="default"/> </server> <server name="server-one" group="auth-server-group" auto-start="true"> <jvm name="default"/> <socket-bindings port-offset="150"/> </server> </servers>
偏移量为 150，则地址为 http://10.49.196.10:8230/
3.2.6、添加 Keycloak 用户
cd $KEYCLOAK_HOME/domain/servers/server-one mkdir configuration #需先创建该目录 cd $KEYCLOAK_HOME/bin ./add-user-keycloak.sh --sc ../domain/servers/server-one/configuration -u admin #这里需通过--sc指定server的位置
用户增加完成后，重启 Keycloak。
3.2.7、添加 slave 和 master 通信的用户
shell> ./add-user.sh What type of user do you wish to add? a) Management User (mgmt-users.properties) b) Application User (application-users.properties) (a): Enter the details of the new user to add. Using realm 'ManagementRealm' as discovered from the existing property files. Username : admin User 'admin' already exists and is enabled, would you like to... a) Update the existing user password and roles b) Disable the existing user c) Type a new username (a): Password recommendations are listed below. To modify these restrictions edit the add-user.properties configuration file. - The password should be different from the username - The password should not be one of the following restricted values {root, admin, administrator} - The password should contain at least 8 characters, 1 alphabetic character(s), 1 digit(s), 1 non-alphanumeric symbol(s) Password : WFLYDM0099: Password should have at least 8 characters! Are you sure you want to use the password entered yes/no? yes Re-enter Password : What groups do you want this user to belong to? (Please enter a comma separated list, or leave blank for none)[ ]: Updated user 'admin' to file '/dataload/chatops/soft/keycloak-16.1.1-domain/standalone/configuration/mgmt-users.properties' Updated user 'admin' to file '/dataload/chatops/soft/keycloak-16.1.1-domain/domain/configuration/mgmt-users.properties' Updated user 'admin' with groups to file '/dataload/chatops/soft/keycloak-16.1.1-domain/standalone/configuration/mgmt-groups.properties' Updated user 'admin' with groups to file '/dataload/chatops/soft/keycloak-16.1.1-domain/domain/configuration/mgmt-groups.properties' Is this new user going to be used for one AS process to connect to another AS process? e.g. for a slave host controller connecting to the master or for a Remoting connection for server to server Jakarta Enterprise Beans calls. yes/no? yes To represent the user add the following to the server-identities definition <secret value="MTIzNDU2" />
创建完成后会生成一个密钥：<secret value="MTIzNDU2" /> ， 后面在配置 slave 时会用到该密钥。
3.3、在 10.49.196.11 上安装 keycloak slave
3.3.1、安装 MySQL 驱动
步骤与 1.6.1、安装 MySQL 驱动 一致。
3.2.2、修改 ip
编辑 domain/configuration/host-slave.xml：
<interfaces> <interface name="management"> <inet-address value="${jboss.bind.address.management:10.49.196.11}"/> </interface> <interface name="public"> <inet-address value="${jboss.bind.address:10.49.196.11}"/> </interface> </interfaces>
3.2.3、修改与 master 通信的鉴权信息
A、对于 16.0.0 之前(不包含)的版本
编辑 domain/configuration/host-slave.xml：
<management> <security-realms> <security-realm name="ManagementRealm"> <server-identities> <secret value="MTIzNDU2Nw==" /> </server-identities> <authentication> <local default-user="$local" skip-group-loading="true"/> <properties path="mgmt-users.properties" relative-to="jboss.domain.config.dir"/> </authentication> ... <domain-controller> <remote security-realm="ManagementRealm" username="admin"> <discovery-options> <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote+http}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9990}"/> </discovery-options> </remote> </domain-controller>
修改的部分参见斜体字。
B、对于 16.0.0 之后(包含)的版本
编辑 domain/configuration/host-slave.xml：
<domain-controller> <remote authentication-context="hcAuthContext"> <discovery-options> <static-discovery name="primary" protocol="${jboss.domain.master.protocol:remote+http}" host="${jboss.domain.master.address}" port="${jboss.domain.master.port:9990}"/> </discovery-options> </remote> </domain-controller> ... <profile> <subsystem xmlns="urn:jboss:domain:core-management:1.0"/> <subsystem xmlns="urn:wildfly:elytron:15.0" final-providers="combined-providers" disallowed-providers="OracleUcrypto"> <authentication-client> <authentication-configuration name="hostAuthConfig" authentication-name="admin" realm="ManagementRealm"> <credential-reference clear-text="123456"/> </authentication-configuration> <authentication-context name="hcAuthContext"> <match-rule authentication-configuration="hostAuthConfig"/> </authentication-context> </authentication-client> <providers> <aggregate-providers name="combined-providers"> <providers name="elytron"/> <providers name="openssl"/> </aggregate-providers> <provider-loader name="elytron" module="org.wildfly.security.elytron"/> <provider-loader name="openssl" module="org.wildfly.openssl"/> </providers>
...
修改的部分参见斜体字。
3.2.4、启动
cd bin nohup ./domain.sh --host-config=host-slave.xml -Djboss.bind.address.private=10.49.196.11 -Djboss.domain.master.address=10.49.196.11 &
3.2.5、访问单点 Keycloak
使用域集群模式时，Keycloak 端口相对 8080 有个偏移量，具体可参考 domain/configuration/host-slave.xml：
<servers> <server name="server-two" group="auth-server-group" auto-start="true"> <jvm name="default"/> <socket-bindings port-offset="250"/> </server> </servers>
偏移量为 250，则地址为 http://10.49.196.11:8330/
如果有多台 slave 则其部署方法也是一致的。
3.4、使用 Kecloak 内部的代理服务器
默认情况下，Keycloak master 会启动一个 load-balancer 的 server 来作为负载均衡器；正式环境不建议使用自带的代理服务器，应使用其他第三方代理服务器，如 nginx。
内部的代理服务器地址为：http://10.49.196.10:8080
如果需要关闭内部的代理服务器，可编辑 domain/configuration/host-master.xml，注释掉 load-balancer server：
<servers> <!--server name="load-balancer" group="load-balancer-group"> <jvm name="default"/> </server--> <server name="server-one" group="auth-server-group" auto-start="true"> <jvm name="default"/> <socket-bindings port-offset="150"/> </server> </servers>
然后重启 Keycloak master。
3.5、使用第三方代理服务器
这里使用 nginx 作为代理服务器，其配置文件如下：
upstream keycloak {
server 10.49.196.10:8230 weight=1;
server 10.49.196.11:8330 weight=1;
ip_hash;
}
server {
listen 8080;
server_name localhost;
location /auth {
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Port $server_port;
proxy_pass http://keycloak/auth;
}
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root html;
}
}
这里建议开启 ip_hash，因为 keycloak 默认只会在一台机器上缓存会话信息，如果会话信息不在本机器上会远程查找，这样会影响效率。
启动 nginx 后，通过 http://10.49.196.12:8080/ 来访问 Keycloak。
3.6、关闭 Keycloak 集群
对于 master 和 slave，kill 掉节点上的 process controller 进程即可。
4、cross-site replication mode--跨站点复制模式安装
由于该模式还不完全支持，这里就不介绍了；感兴趣的可以查看官网文档：https://www.keycloak.org/docs/16.1/server_installation/index.html#crossdc-mode。
