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&amp;characterEncoding=UTF-8&amp;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.40.96.132: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.40.96.10 &

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。