概述

本指南帮助您开始使用Keycloak。 它涵盖服务器配置和默认数据库的使用。 高级部署选项不包括在内。 有关功能或配置选项的更深入描述,请参阅其他参考指南。

安装和启动

本节介绍如何在独立模式下启动Keycloak服务器、设置初始管理员用户以及登录Keycloak管理控制台。

安装分发文件

下载Keycloak服务器:

  • keycloak-9.0.3。[zip | tar.gz]

该文件可以从Keycloak下载

keycloak-9.0.3。[zip | tar.gz]文件是仅服务器发行版。 它只包含运行Keycloak服务器的脚本和二进制文件。

将文件放在您选择的目录中,然后使用解压缩或者焦油提取它的效用。

Linux/Unix
$ 解压缩keycloak-9.0.3.zip

或者

$ tar -xvzf keycloak-9.0.3.tar.gz
窗户
> 解压缩keycloak-9.0.3.zip

引导服务器

要启动Keycloak服务器,请转到bin服务器分发的目录,并运行独立引导脚本:

Linux/Unix
$ cd bin
$。/独立。sh
窗户
>。.. \ bin \ 独立.bat

创建管理员帐户

服务器启动后,打开http:// localhost:8080/auth在您的网络浏览器中。 欢迎页面将指示服务器正在运行。

输入用户名和密码以创建初始管理员用户。

该帐户将被允许登录到大师realm的管理控制台,您将从中创建领域和用户,并注册应用程序以由Keycloak保护。

如果您使用连接,则只能在欢迎页面上创建一个初始管理员用户本地主机。 这是一种安全措施 预防措施。 您可以在命令行使用add-user-keycloak.sh脚本。 有关更多信息,请参见 服务器安装和配置指南服务器管理指南

登录管理控制台

创建初始管理员帐户后,请执行以下步骤登录管理控制台:

  1. 单击管理控制台上的链接欢迎页面或直接转到控制台URLhttp:// localhost:8080/auth/admin/

  2. 键入您在欢迎页面打开Keycloak管理控制台

    管理控制台

    管理控制台

创建境界和用户

在本节中,您将在Keycloak管理控制台中创建一个新域,并向该域添加一个新用户。 您将使用该新用户登录到您的新境界,并访问所有用户都可以访问的内置用户帐户服务。

在你开始之前

在创建第一个领域之前,请完成Keycloak的安装并创建初始管理员用户,如所示安装和启动

开创新境界

要创建一个新的境界,请完成以下步骤:

  1. http:// localhost:8080/auth/admin/并使用您在其中创建的帐户登录到Keycloak管理控制台安装并启动

  2. 大师下拉菜单,单击添加领域。 当您登录到主领域时,此下拉菜单将列出所有现有领域。

  3. 类型演示名称字段并单击创建

创建领域后,将打开主管理控制台页面。 请注意,当前领域现在设置为演示。 在管理大师境界和您刚刚通过单击中的条目创建的境界选择领域下拉菜单。

创建新用户

要在演示realm以及该新用户的临时密码,请完成以下步骤:

  1. 从菜单中,单击用户打开用户列表页面。

  2. 在空用户列表的右侧,单击添加用户打开添加用户页面。

  3. 用户名字段; 这是唯一的必填字段。 翻转已验证电子邮件并点击保存保存数据并为新用户打开管理页面。

  4. 单击凭据选项卡为新用户设置临时密码。

  5. 键入新密码并确认。 点击重置密码将用户密码设置为您指定的新密码。

此密码是临时的,用户在第一次登录后将被要求更改。 要创建持久的密码,请翻转临时点击前重置密码

用户帐户服务

  1. 创建新用户后,通过打开用户下拉菜单并选择退出

  2. http:// localhost:8080/auth/realms/demo/account并登录您的用户帐户服务演示与您刚刚创建的用户的境界。

  3. 键入您创建的用户名和密码。 成功登录后,您将需要创建一个永久密码,除非您更改了临时设置为当您创建密码时。

用户帐户服务页面将打开。 默认情况下,领域中的每个用户都可以访问此帐户服务。 在此页面中,您可以更新配置文件信息以及更改或添加其他凭据。 有关此服务的更多信息,请参见服务器管理指南

保护JBoss Servlet应用程序

本节介绍如何通过以下方式保护WildFly应用程序服务器上的Java servlet应用程序:

  • 在WildFly应用程序服务器发行版上安装Keycloak客户端适配器

  • 在Keycloak管理控制台中创建和注册客户端应用程序

  • 将应用程序配置为通过Keycloak进行安全保护

在你开始之前

在保护Java servlet应用程序之前,必须完成Keycloak的安装并创建初始管理员用户,如所示安装和启动

有一个警告: 即使WildFly与Keycloak捆绑在一起,您也不能将其用作应用程序容器。 相反,您必须在与Keycloak服务器相同的机器上运行单独的WildFly实例才能运行您的Java servlet应用程序。 使用与WildFly不同的端口运行Keycloak,以避免端口冲突。

要调整所使用的端口,请更改jboss.套接字.绑定.端口偏移从命令行启动服务器时的系统属性。 此属性的值是一个数字,该数字将添加到Keycloak服务器打开的每个端口的基本值中。

要在调整端口的同时启动Keycloak服务器:

Linux/Unix
$ cd bin
$。/standalone.sh -Djboss.socket.binding.port-offset = 100
窗户
>。.. \ bin \ standalone.bat -Djboss.套接字.绑定.端口偏移 = 100

启动Keycloak后,转到http:// localhost:8180/auth/admin/访问管理控制台。

安装客户端适配器

下载WildFly发行版,并将其从压缩文件中提取到计算机上的目录中。

从下载WildFly OpenID连接适配器发行版keycloak.org

将此文件的内容提取到WildFly发行版的根目录中。

为您的平台运行相应的脚本:

WildFly 10和Linux/Unix
$ cd bin
$。/jboss-cli.sh-file = adapter-install-offline.cli
野蝇10和窗户
> 光盘箱
> jboss-cli.bat -- file = adapter-install-offline.cli
Wildfly 11 + 和Linux/Unix
$ cd bin
$。/jboss-cli.sh-file = adapter-elytron-install-offline.cli
野蝇11 + 和窗户
> 光盘箱
> jboss-cli.bat -- file = adapter-elytron-install-offline.cli
此脚本将对…/独立/配置/独立.xml您的应用程序服务器分发的文件,可能需要一些时间才能完成。

启动应用程序服务器。

Linux/Unix
$ cd bin
$。/独立。sh
窗户
>。.. \ bin \ 独立.bat

配置子系统

要配置部署应用程序的WildFly实例,以便此应用程序由Keycloak保护,请完成以下步骤。

  1. 打开独立/配置/独立.xml在应用程序部署的WildFly实例中的文件,并搜索以下文本:

    <子系统 xmlns=urn:jboss: 域: keycloak:1.1/>
  2. 修改此文本以准备文件以粘贴到Keycloak OIDC JBoss子系统XML模板我们获得了Keycloak管理控制台安装通过将XML条目从自动关闭更改为使用一对打开和关闭标签的选项卡:

    <子系统 xmlns=urn:jboss: 域: keycloak:1.1>
    </子系统>
  3. 将模板的内容粘贴到<子系统>元素,如该示例所示:

    <子系统 xmlns=urn:jboss: 域: keycloak:1.1>
      <安全部署 名称=战争模块名称。战争>
        <境界>演示</领域>
        <身份验证-服务器-网址>http:// localhost:8180/auth</身份验证-服务器-网址>
        <公共客户端></公共客户端>
        <ssl-必需>外部</ssl-必需>
        <资源>香草</资源>
      </安全部署>
    </子系统>
  4. 更改名称香草。战争:

    <子系统 xmlns=urn:jboss: 域: keycloak:1.1>
      <安全部署 名称=香草。战争>
      ...
    </子系统>
  5. 重新启动应用程序服务器。

  6. http:// localhost:8080/vanilla并点击登录。 当Keycloak登录页面打开时,使用您在创建新用户

下载、构建和部署应用程序代码

在继续之前,您必须在您的计算机上安装以下内容,并且在您的路径中可用:

  • Java JDK 8

  • Apache Maven 3.1.1或更高版本

  • Git

您可以通过在以下位置克隆Keycloak Quickstarts存储库来获取代码https://github.com/keycloak/ Keycloak-快速入门。 快速入门旨在与最新的Keycloak版本一起使用。

在继续之前,请确保您的WildFly应用程序服务器已启动。

要下载、构建和部署代码,请完成以下步骤。

克隆项目
$ git克隆https://github.com/keycloak/ keycloak-快速入门
$ cdKeycloak-快速入门/应用-简介-jee-香草
$ mvn清洁野蝇: 部署

在安装过程中,您将在应用程序服务器控制台窗口中看到一些文本滚动。

要确认应用程序已成功部署,请转到http:// localhost:8180/vanilla并且应该出现一个登录页面。

如果你点击登录,浏览器会弹出一个基本的身份验证登录对话框。 但是,该应用程序尚未受到任何身份提供者的保护,因此您在对话框中输入的任何内容都将导致禁止服务器发回的消息。 您可以通过以下方式确认应用程序当前是安全的基本通过在应用程序的web.xml文件。

创建和注册客户端

要在Keycloak管理控制台中定义和注册客户端,请完成以下步骤:

  1. 使用您的管理员帐户登录到管理控制台。

  2. 在左上角的下拉菜单中,选择并管理演示境界。 点击客户在左侧菜单中打开 “客户端” 页面。

    客户

    客户

  3. 在右侧,单击创建

  4. 完成如下所示的字段:

    添加客户端

    添加客户端

  5. 点击保存创建客户端应用程序条目。

  6. 单击安装在Keycloak管理控制台中的选项卡,以获取配置模板。

  7. 选择Keycloak OIDC JBoss子系统XML生成XML模板。 复制内容以在下一节中使用。

    模板XML

    选择客户端安装