Keycloak 简介

Keycloak 是为现代应用系统和服务提供开源的鉴权和授权访问控制管理。Keycloak 实现了 OpenID、OAuth2.0、SAML 单点登录协议，同时提供 LDAP 和 Active Directory 以及 OpenID Connect、SAML2.0 IdPs、Github、Google 等第三方登录适配功能，能够做到非常简单的开箱即用。

为什么使用 Keycloak？

SuperMap iServer、SuperMap iPortal、SuperMap iEdge 分别对接 Keycloak 后，可实现以下能力：

  • 使用 Keycloak 对 SuperMap iServer/iPortal/iEdge 进行统一的账户管理，包括用户管理和角色管理
  • SuperMap iServer/iPortal/iEdge 可以使用 Keycloak 统一的账号进行登录，还可实现它们之间的单点登录、登出
  • 基于 OAuth2.0 协议，实现授权第三方应用（如：SuperMap iDesktop） 登录 SuperMap iServer/iPortal/iEdge 访问资源，而无需将 SuperMap iServer/iPortal/iEdge 的账号和密码提供给第三方应用。
  • 支持直接对接用户已有的账户系统，包括：LDAP、Kerberos
  • 支持通过对 Keycloak 进行扩展开发的方式，对接用户已有的单点登录系统

配置使用 Keycloak

关于 Keycloak 的安装与配置请参见：Keycloak 安装与配置。下面具体为您介绍如何在 SuperMap iServer/iPortal/iEdge 中对接 Keycloak，以 SuperMap iPortal 为例：

以 iPortal 管理员的身份登录 iPortal 门户首页，依次点击“管理”> "安全" > "登录配置" > "Keycloak" ，选择“Keycloak 登录配置”选项卡”：

步骤一：Keycloak 登录配置

  • 是否启用：勾选，启用 Keycloak。
  • Keycloak根地址：输入 Keycloak 地址，例如：http://192.168.120.40:8180/auth。
  • Keycloak域：输入在 Keycloak 中使用的域名称，默认域名为 master，如果您在 Keycloak 中添加了新域，填写新域名即可，例如：ispeco。
  • 客户端ID：输入在 Keycloak 中创建客户端时添加的客户端ID，例如：ispeco-oidc。
  • 客户端密钥：输入在 Keycloak 中创建客户端时生成的客户端密钥，例如：334322d9-45d2-45e9-8e49-156f188ef0f4。
  • 角色属性标识：输入在 Keycloak 中创建协议映射器时填写的 Token 申请名，例如：roles。
  • 系统时钟最大容差：如果 Keycloak 服务器和 GIS 服务器不在同一台机器上，由于两台机器的系统时间差，可能导致登录验证不成功，所以您可以根据需要输入系统最大容错时间差，默认值180000，单位：秒。
  • 关联的 public 客户端 ID（iServer/iEdge 暂无此配置）：在 iPortal 中，除了完成以上配置，您还需在 Keycloak 中创建一个访问类型为 public 的客户端，并与之前创建的客户端进行关联，具体请参见：配置_Keycloak_对接_SuperMap_iPortal_的后续步骤。此处应输入访问类型为 public 的客户端 ID，例如：ispeco-kh。

点击“保存配置”按钮，完成 Keycloak 登录配置。

步骤二：属性角色关联信息配置

接下来，还需进行“属性角色关联信息配置”，即 iPortal 中的角色与 Keycloak 中的角色映射关系。系统内置了一些角色映射，您只需在 Keycloak 中添加与属性值相对应的角色名（不带 KC_ 前缀名），就可以直接使用内置的角色映射，添加角色的具体操作请参见：添加角色。您也可以添加新的角色映射，点击“添加角色映射”按钮：

  • 属性值：填写 Keycloak 中添加的角色名称，带上配置的前缀名，例如，在 Keycloak 中配置的前缀名为： KC_，添加的角色名为：DATA_CENTER，则此处填写：KC_DATA_CENTER。
  • 供选择的角色：左侧供选择的角色中列出了当前 iPortal 中的角色，右侧是要与 Keycloak 进行关联的 iPortal 角色。

点击“确定”按钮，完成角色映射。

 

以上配置完成后，在 iPortal 门户首页点击“登录”按钮，即可跳转至 Keycloak 登录页面，使用 Keycloak 账户登录。但此时 iPortal 内置 WebApps 的登录页面还不支持使用 Keycloak 账户登录，您还需要通过统一登录方式的配置，实现 iPortal 各页面登录方式的统一。

统一登录方式配置（iServer/iEdge 暂无此配置）

在【SuperMap iPortal 安装目录】\webapps\iportal\WEB-INF 文件夹下的 iportal.xml 配置文件中，通过 <authenticationDelegation> 节点的<enable>子节点元素来开启身份验证委托机制，实现 iPortal 各页面登录方式的统一。 编辑完 iportal.xml 文件后无需重启 iPortal，刷新页面即可生效。

其他可选配置

如果您在使用 Keycloak 登录时，期望使用真实的 IP 地址登录并访问 iPortal。在以上配置的基础上，可以通过编辑 shiro.ini 文件（位于【SuperMap iPortal 安装目录】\webapps\iportal\WEB-INF 下），修改 clients.callbackUrl 参数的变量值来配置 Kyecloak 登录后的跳转地址。跳转地址的格式如下粗体部分所示，将 {realIP}:{port} 修改为您实际使用 IP 和端口号即可 ：

clients.callbackUrl = http://{realIP}:{port}/iportal/callback

注意：

  • shiro.ini 文件在首次启动 iPortal 服务之前是不存在的，请在 iPortal 服务首次启动之后，再对该文件进行编辑。

单点登出

在配置使用 Keycloak 后，除可以单点登录外，也可实现单点登出。如当在同一浏览器上登录了多个 iServer 、iEdge 节点时，可在 iServer 或 iEdge 服务器首页点击“退出” 按钮进行单点登出，即可一次退出在该浏览器上登录的所有 iServer、iEdge 节点。