Keycloak是针对Web应用程序和RESTful Web服务的单一登录解决方案。Keycloak的目标是简化安全性，以便应用程序开发人员可以轻松保护已部署在组织中的应用程序和服务。开箱即用地提供了开发人员通常必须为自己编写的安全功能，可以轻松地针对组织的个性化需求进行定制。Keycloak提供可自定义的用户界面，用于登录，注册，管理和帐户管理。您还可以将Keycloak用作集成平台，以将其挂接到现有的LDAP和Active Directory服务器中。您还可以将身份验证委派给第三方身份提供商，例如Facebook和Google。

• 浏览器应用程序的单点登录和单点登录。

• OpenID Connect支持。

• OAuth 2.0支持。

• SAML支持。

• 身份代理-通过外部OpenID Connect或SAML身份提供程序进行身份验证。

• 社交登录-启用通过Google，GitHub，Facebook，Twitter和其他社交网络的登录。

• 用户联合-同步LDAP和Active Directory服务器中的用户。

• Kerberos桥-自动验证登录到Kerberos服务器的用户。

• 管理控制台，用于集中管理用户，角色，角色映射，客户端和配置。

• 帐户管理控制台，允许用户集中管理其帐户。

• 主题支持-自定义所有面向用户的页面以与您的应用程序和品牌集成。

• 两因素身份验证-通过Google Authenticator或FreeOTP支持TOTP HOTP。

• 登录流程-可选的用户自我注册，恢复密码，验证电子邮件，要求密码更新等。

• 会话管理-管理员和用户本身可以查看和管理用户会话。

• 令牌映射器-将用户属性，角色等映射到令牌和语句的方式。

• 每个领域，应用程序和用户的撤销策略。

• CORS支持-客户端适配器具有对CORS的内置支持。

• 服务提供商接口（SPI）-用于自定义服务器各个方面的许多SPI。身份验证流，用户联合提供程序，协议映射器等等。

• 适用于JavaScript应用程序，WildFly，JBoss EAP，Fuse，Tomcat，Jetty，Spring等的客户端适配器。

• 支持任何具有OpenID Connect依赖方库或SAML 2.0服务提供商库的平台/语言。

Keycloak是您在网络上管理的单独服务器。应用程序被配置为指向该服务器并受其保护。Keycloak使用开放协议标准，例如OpenID Connect 或SAML 2.0保护您的应用程序。浏览器应用程序将用户的浏览器从应用程序重定向到Keycloak身份验证服务器，并在其中输入其凭据。这很重要，因为用户与应用程序完全隔离，并且应用程序永远看不到用户的凭据。相反，为应用程序提供了经过密码签名的身份令牌或断言。这些令牌可以具有身份信息，例如用户名，地址，电子邮件和其他配置文件数据。他们还可以保存许可数据，以便应用程序可以做出授权决策。这些令牌还可以用于对基于REST的服务进行安全调用。

在尝试使用Keycloak保护Web应用程序和REST服务之前，应注意一些关键概念和术语。

• users

  用户是能够登录系统的实体。他们可以具有与自己相关联的属性，例如电子邮件，用户名，地址，电话号码和生日。可以为他们分配组成员身份，并为其分配特定的角色。

• authentication

  识别和验证用户的过程。

• authorization

  授予用户访问权限的过程。

• credentials

  凭证是Keycloak用来验证用户身份的数据。比如是密码，一次性密码，数字证书甚至指纹。

• roles

  角色标识用户的类型或类别。 Admin
  ，user
  ，manager
  ，并且employee
  是可以在一个组织中存在的所有典型的角色。应用程序通常将访问和权限分配给特定角色，而不是单个用户，因为与用户打交道可能过于精细且难以管理。

• user role mapping

  用户角色映射定义角色和用户之间的映射。一个用户可以与零个或多个角色相关联。可以将此角色映射信息封装到令牌和断言中，以便应用程序可以决定对其管理的各种资源的访问权限。

• composite roles

  复合角色是可以与其他角色关联的角色。例如，superuser
  复合角色可以与sales-admin
  和order-entry-admin
  角色相关联 。如果将用户映射到superuser
  角色，他们还将继承sales-admin
  和order-entry-admin
  角色。

• groups

  组管理用户组。可以为组定义属性。您也可以将角色映射到组。成为组成员的用户将继承该组定义的属性和角色映射。

• realms

  领域管理一组用户，凭据，角色和组。用户属于并登录到领域。领域彼此隔离，并且只能管理和认证他们控制的用户。

• clients

  客户端是可以请求Keycloak验证用户身份的实体。大多数情况下，客户端是希望使用Keycloak来保护自身并提供单一登录解决方案的应用程序和服务。客户端也可以是只想请求身份信息或访问令牌的实体，以便它们可以安全地调用网络上由Keycloak保护的其他服务。

• client adapters

  客户端适配器是您安装到应用程序环境中的插件，以便能够通过Keycloak进行通信和保护。Keycloak有许多可以下载的用于不同平台的适配器。您还可以获得针对我们未涵盖的环境的第三方适配器。

• consent

  同意是指您作为管理员希望用户在客户端可以参与身份验证过程之前向其授予权限。用户提供凭据后，Keycloak将弹出一个屏幕，该屏幕标识请求登录的客户端以及请求用户的身份信息。用户可以决定是否准予该请求。

• client scopes

  注册客户端后，您必须为该客户端定义协议映射器和角色范围映射。存储客户端范围通常很有用，通过共享一些通用设置使创建新客户端更加容易。这对于根据scope
  参数的值有条件地要求某些声明或角色也很有用。Keycloak为此提供了客户端作用域的概念。

• client role

  客户可以定义特定于他们的角色。这基本上是专用于客户端的角色名称空间。

• identity token

  提供有关用户身份信息的令牌。OpenID Connect规范的一部分。

• access token

  可以作为HTTP请求的一部分提供的令牌，该令牌授予对正在调用的服务的访问权限。这是OpenID Connect和OAuth 2.0规范的一部分。

• assertion

  有关用户的信息。这通常与XML Blob有关，该XML Blob包含在SAML身份验证响应中，该响应提供有关已验证用户的身份元数据。

• service account

  每个客户端都有一个内置的服务帐户，该帐户允许其获取访问令牌。

• direct grant

  Client通过REST调用代表用户获取访问令牌的一种方式。

• protocol mappers

  对于每个客户端，您可以定制OIDC令牌或SAML断言中存储的声明和断言。您可以通过创建和配置协议映射器为每个客户端执行此操作。

• session

  用户登录时，将创建一个会话来管理登录会话。会话包含诸如用户何时登录以及在该会话期间哪些应用程序参与了单点登录之类的信息。管理员和用户都可以查看会话信息。

• user federation provider

  Keycloak可以存储和管理用户。通常，公司已经拥有存储用户和凭证信息的LDAP或Active Directory服务。您可以指向Keycloak来验证来自那些外部存储的凭据并提取身份信息。

• identity provider

  身份提供者（IDP）是可以对用户进行身份验证的服务。Keycloak是一个IDP。

• identity provider federation

  可以将Keycloak配置为将身份验证委派给一个或多个IDP。通过Facebook或Google+的社交登录是身份提供商联盟的一个示例。您也可以挂钩Keycloak，以将身份验证委派给任何其他OpenID Connect或SAML 2.0 IDP。

• identity provider mappers

  执行IDP联合时，您可以将传入的令牌和断言映射到用户和会话属性。这可以帮助您将身份信息从外部IDP传播到请求身份验证的客户端。

• required actions

  必需的操作是用户在身份验证过程中必须执行的操作。在完成这些操作之前，用户将无法完成身份验证过程。例如，管理员可以安排用户每月重新设置其密码。一个update password
  需要行动将所有这些用户设置。

• authentication flows

  认证流程是用户在与系统的某些方面进行交互时必须执行的工作流程。登录流程可以定义所需的凭据类型。注册流程定义用户必须输入哪些配置文件信息，以及是否必须使用诸如reCAPTCHA之类的内容来过滤出僵尸程序。凭据重置流程定义用户在重置密码之前必须执行的操作。

• events

  事件是管理员可以查看和连接的审核流。

• themes

  Keycloak提供的每个屏幕都有一个主题支持。主题定义HTML模板和样式表，您可以根据需要覆盖它们。

• 默认情况下，没有创建管理员用户，因此您将无法登录到管理控制台。要创建管理员帐户，您需要使用环境变量来传递初始用户名和密码。这是通过运行以下命令完成的：

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:11.0.1

Keycloak 的端口是8080，账号密码都为admin

• 您还可以通过运行以下命令在已运行的容器上创建帐户：

docker exec <CONTAINER> opt/jboss/keycloak/bin/add-user-keycloak.sh -u <USERNAME> -p <PASSWORD>

要创建管理员帐户并导入以前导出的领域运行，请执行以下操作：

docker run -e KEYCLOAK_USER=<USERNAME> -e KEYCLOAK_PASSWORD=<PASSWORD> \
    -e KEYCLOAK_IMPORT=/tmp/example-realm.json -v tmp/example-realm.json:/tmp/example-realm.json jboss/keycloak

如果要导出已创建/更新的领域，请在运行在Docker容器中的Keycloak实例上。您需要确保运行Keycloak的容器已映射卷。例如，您可以使用以下命令通过docker启动Keycloak：

docker run -d -p 8180:8080 -e KEYCLOAK_USER=admin -e \
KEYCLOAK_PASSWORD=admin -v $(pwd):/tmp --name kc \
jboss/keycloak

然后，您可以通过运行从该实例获取导出（注意，我们使用-Djboss.socket.binding.port-offset=100
导出以便在与Keycloak本身不同的端口上运行）：

docker exec -it kc opt/jboss/keycloak/bin/standalone.sh \
-Djboss.socket.binding.port-offset=100 -Dkeycloak.migration.action=export \
-Dkeycloak.migration.provider=singleFile \
-Dkeycloak.migration.realmName=my_realm \
-Dkeycloak.migration.usersExportStrategy=REALM_FILE \
-Dkeycloak.migration.file=/tmp/my_realm.json

您可以在Keycloak的主要文档站点上找到有关可用于导出功能的选项的更多详细信息，位于：导出和导入

该映像支持使用H2，MySQL，PostgreSQL，MariaDB，Oracle或Microsoft SQL Server作为数据库。

您可以直接使用DB_VENDOR
环境变量指定数据库供应商。支持的值为：

• h2
   对于嵌入式H2数据库，

• postgres
   对于Postgres数据库，

• mysql
   用于MySql数据库。

• mariadb
   用于MariaDB数据库。

• oracle
   用于Oracle数据库。

• mssql
   用于Microsoft SQL Server数据库

如果DB_VENDOR
未指定value，则映像将根据以下逻辑尝试检测数据库供应商：

• 是使用了DB将默认主机名getent hosts
  （postgres
  ，mysql
  ，mariadb
  ，oracle
  ，mssql
  ）。如果您使用的是用户定义的网络以及下面指定的默认名称，则此方法有效。

• 是否有一个特定的数据库_ADDR
  环境变量设置（POSTGRES_ADDR
  ，MYSQL_ADDR
  ，MARIADB_ADDR
  ，ORACLE_ADDR
  ）。

不推荐使用如果无法检测到数据库，它将默认使用嵌入式H2数据库。

通用变量名可用于配置任何数据库类型，默认值可能因数据库而异。

• DB_ADDR
  ：指定数据库的主机名（可选）。仅对于postgres，您可以提供以逗号分隔的主机名列表，以进行故障转移备用主机。主机名可以仅是主机，也可以是主机和端口对，例如host1，host2或host1：5421，host2：5436或host1，host2：5000。并且keycloak将DB_PORT（如果指定）附加到不带端口的主机，否则它将默认端口5432再次附加到不带端口的地址。

• DB_PORT
  ：指定数据库的端口（可选，默认为数据库供应商默认端口）

• DB_DATABASE
  ：指定要使用的数据库的名称（可选，默认为keycloak
  ）。

• DB_SCHEMA
  ：指定用于支持模式的数据库的模式名称（可选，默认在Postgres上为public）。

• DB_USER
  ：指定用于认证数据库的用户（可选，默认为``）。

• DB_USER_FILE
  ：指定用户通过文件输入（替代DB_USER
  ）向数据库进行身份验证。

• DB_PASSWORD
  ：指定用于验证数据库身份的用户密码（可选，默认为``）。

• DB_PASSWORD_FILE
  ：指定用于通过文件输入（替代DB_PASSWORD
  ）对数据库进行身份验证的用户密码。

docker network create keycloak-network

首先使用MySQL docker镜像启动一个MySQL实例：

docker run --name mysql -d --net keycloak-network -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=password -e MYSQL_ROOT_PASSWORD=root_password mysql

启动Keycloak实例并连接到MySQL实例：

docker run --name keycloak --net keycloak-network jboss/keycloak

如果为MySQL实例使用了其他名称，则mysql
需要指定DB_ADDR
环境变量。

docker network create keycloak-network

首先使用PostgreSQL docker镜像启动一个PostgreSQL实例：

docker run -d --name postgres --net keycloak-network -e POSTGRES_DB=keycloak -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=password postgres

启动一个Keycloak实例并连接到PostgreSQL实例：

docker run --name keycloak --net keycloak-network jboss/keycloak -e DB_USER=keycloak -e DB_PASSWORD=password

如果对PostgreSQL实例使用了不同的名称，则postgres
需要指定DB_ADDR
环境变量。

docker network create keycloak-network

首先使用MariaDB docker映像启动MariaDB实例：

docker run -d --name mariadb --net keycloak-network -e MYSQL_ROOT_PASSWORD=password -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=password mariadb

启动Keycloak实例并连接到MariaDB实例：

docker run --name keycloak --net keycloak-network jboss/keycloak

如果为MariaDB实例使用了不同的名称，则mariadb
需要指定DB_ADDR
环境变量。

将Keycloak与Oracle数据库一起使用需要向Docker映像提供JDBC驱动程序。

1. 为您的Oracle版本下载所需的JDBC驱动程序。

2. 重要：将文件重命名为ojdbc.jar
   

docker network create keycloak-network

如果您已经有运行此步骤的Oracle数据库，则可以跳过此步骤，否则，我们将在Docker Hub上使用carloscastillo / rgt-oracle-xe-11g映像启动一个新的Docker容器：

docker run -d --name oracle --net keycloak-network -p 1521:1521 carloscastillo/rgt-oracle-xe-11g

启动Keycloak实例并连接到Oracle实例：

docker run -d --name keycloak --net keycloak-network -p 8080:8080 -v /path/to/jdbc/driver:/opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main/driver jboss/keycloak

这里的关键之一是我们要从JDBC驱动程序的位置装入卷，因此请确保路径正确。安装的卷应包含名为的文件ojdbc.jar
。

或者，可以使用以下docker cp
命令将JDBC文件复制到容器中：

docker cp ojdbc.jar jboss/keycloak:/opt/jboss/keycloak/modules/system/layers/base/com/oracle/jdbc/main/driver/ojdbc.jar

如果您为Oracle实例使用了其他名称，则oracle
无需指定DB_ADDR
环境变量。

默认环境设置：

• DB_ADDR
  ： oracle
  

• DB_PORT
  ： 1521
  

• DB_DATABASE
  ： XE
  

• DB_USER
  ： SYSTEM
  

• DB_PASSWORD
  ： oracle
  

docker network create keycloak-network

首先使用Microsoft SQL Server docker映像启动Microsoft SQL Server实例：

docker run -e 'ACCEPT_EULA=Y' -e 'SA_PASSWORD=Password!23' -d --name mssql --net keycloak-network mcr.microsoft.com/mssql/server

与其他一些受支持的数据库（如PostgreSQL，MySQL或MariaDB）不同，SQL Server不支持通过环境变量创建初始数据库。因此，必须以其他方式为Keycloak创建数据库。原则上，这可以通过创建一个一直运行到可以创建数据库的映像来完成。

docker run -d --name mssql-scripts --net keycloak-network mcr.microsoft.com/mssql-tools /bin/bash -c 'until /opt/mssql-tools/bin/sqlcmd -S mssql -U sa -P "Password!23" -Q "create database Keycloak"; do sleep 5; done'

该映像将反复尝试创建数据库，并在数据库就位后终止。

启动Keycloak实例并连接到Microsoft SQL Server实例：

docker run --name keycloak --net keycloak-network -p 8080:8080 -e DB_VENDOR=mssql -e DB_USER=sa -e DB_PASSWORD=Password!23 -e DB_ADDR=mssql -e DB_DATABASE=Keycloak -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin jboss/keycloak

如果您为Microsoft SQL Server实例使用了不同的名称，则mssql
需要指定DB_ADDR
环境变量。

请参阅docker-compose-examples/keycloak-mssql.yml
完整的示例。

将Keycloak实例连接到数据库时，可以指定JDBC参数。JDBC参数的详细信息可以在这里找到：

• PostgreSQL的

• 的MySQL

• 玛丽亚数据库

• 甲骨文

• Microsoft SQL服务器

docker run --name keycloak -e DB_VENDOR=postgres -e JDBC_PARAMS='connectTimeout=30' jboss/keycloak

要添加自定义主题，请扩展Keycloak图像，将主题添加到/opt/jboss/keycloak/themes
目录中。

要设置欢迎主题，请使用以下环境值：

• KEYCLOAK_WELCOME_THEME
  ：指定用于欢迎页面的主题（必须为非空，并且必须与现有主题名称匹配）

要将自定义主题设置为默认的全局主题，请使用以下环境值：

• KEYCLOAK_DEFAULT_THEME
  ：指定要用作默认全局主题的主题（必须与现有主题名称匹配，如果为空则将使用keycloak）

控制台地址：http://localhost:8080/auth/

Keycloak中的领域等同于租户。它允许创建隔离的应用程序和用户组。默认情况下，Keycloak中有一个名为master的领域。这专用于管理Keycloak，不应将其用于自己的应用程序。

让我们创建第一个领域。

1.打开Keycloak管理控制台

2.将鼠标悬停在显示左上角的下拉菜单上Master，然后单击Add realm

3.用以下值填写表格：

- 名称：myrealm

请点击 Create

最初在新领域中没有用户，因此让我们创建一个：

1.打开Keycloak管理控制台

2.单击Users（左侧菜单）

- 单击Add user（表格的右上角）

3.用以下值填写表格：

• 用户名：myuser

• 名：您的名字

• 姓氏：您的姓氏

4.请点击 Save

用户将需要设置初始密码才能登录。去做这个：

• 单击Credentials（页面顶部）

• Set Password用密码填写表格

• Temporary: 单击ON,防止在首次登录时更新密码

现在，让我们尝试登录到帐户控制台以验证用户配置是否正确。

1.打开Keycloak帐户控制台 http://localhost:8080/auth/realms/myrealm/account

2.登录myuser和您之前创建的密码

现在，您应该登录到帐户控制台，用户可以在其中管理其帐户。

让我们尝试保护我们的第一个应用程序。第一步是向您的Keycloak实例注册此应用程序：

1.打开Keycloak管理控制台

2.点击“Clients”

3.用以下值填写表格：

• 客户编号：myclient

• 客户端协议：openid-connect

• 根网址：https://www.keycloak.org/app/

  4.请点击 Save

Tip: 为了方便您，我们在Keycloak网站上提供了SPA测试应用程序。

打开https://www.keycloak.org/app/并单击Save以使用默认配置。

现在，您可以单击Sign in以使用之前启动的Keycloak服务器对此应用程序进行身份验证。

在生产环境中运行Keycloak之前，您还要做几件事，包括：

• 切换到生产就绪数据库，例如PostgreSQL

• 使用您自己的证书配置SSL

• 
  

• 将管理员密码切换为更安全的密码

有关更多信息，请查阅Keycloak文档。