Keycloak安装与配置

• 安装 Keycloak
• 配置 Keycloak 对接 SuperMap iServer/iPortal/iEdge
• 配置 Keycloak 对接 SuperMap iDesktop
• 添加角色
• 添加用户

安装 Keycloak

下载安装 Keycloak，这里以 win64 系统为例，Keycloak 官网下载地址：https://www.keycloak.org/downloads

本示例下载 keycloak-4.0.0.Final.zip，需求的 Java 版本为 JDK 1.8及以上。下载完成后，解压缩文件，双击运行 keycloak-4.0.0.Final/bin 目录下的 standalone.bat 文件，启动 Keycloak。

Keycloak 的本地访问地址为：http://localhost:8080/auth/，访问该地址，点击页面中的“Administration Console“，创建 Keycloak 的管理员账户，该账户用于在 Keycloak 中进行配置，管理用户、角色等。

您可以通过以下方式配置使用 IP并更改 Keycloak 的端口：

在 keycloak-4.0.0.Final/bin 目录下，执行以下 DOS 命令：

standalone.bat -Djboss.socket.binding.port-offset=100 -Djboss.bind.address=192.168.112.172

• -Djboss.socket.binding.port-offset：设置端口偏移量，100表示默认端口号+100，此时 Keycloak 端口号更改为：8180
• -Djboss.bind.address：设置 Keycloak 所在机器的 IP 地址

配置 Keycloak 对接 SuperMap iServer/iPortal/iEdge

访问 Keycloak 服务地址：http://localhost:8080/auth/，点击页面中的“Administration Console“，进入 Keycloak 登录页面，输入创建好的 Keycloak 的管理员账户，登录 Keycloak。您可以通过以下方式切换 Keycloak 的语言环境，默认为英文，该示例中，将语言切换至中文：

点击左侧导航栏中的“Realm Settings”,在右侧页面选择“Themes”选项卡，其中，“Login Theme”项、“Account Theme”项、“Admin Console Theme”项、“Email Theme”项全部选择“keycloak”，“Internationalization Enabled”项选择“ON”，开启国际化，“Default Locale”选择“zh-CN”,最后点击“Save”按钮。

此时，管理员登出，在 Keycloak 的登录页面会显示语言切换项，选择“中文简体”，登录 Keycloak。

接下来您需要在 Keycloak 中进行以下配置：

1. 添加域

Keycloak 默认的域为 Master，您可以使用默认的 Master 域，也可以新添加一个域。鼠标移动到左侧导航栏 Master 域名上，在下拉按钮中点击“添加域”，输入域名称，例如：ispeco，点击“创建”按钮，此时，进入到新创建的 ispeco，进行以下配置。需要注意的是，域和域之间的资源（包括用户、角色、客户端等一切信息）是相互隔离的。

2. 创建一个客户端

左侧导航栏选择“客户端”，在右侧页面点击“创建”按钮，添加客户端：

• “客户端 ID”：输入“客户端 ID”，这个“客户端 ID"您可以随意命名，例如：ispeco-oidc。需要注意的是，这个"客户端 ID”与在 SuperMap iServer/iPortal/iEdge 中的“Keycloak 登录配置”的“客户端 ID”一致。
• “客户端协议”：选择默认的 openid-connect。

• 点击“保存”按钮，进入客户端配置详情页面，选择“设置”选项卡，按照下图所示继续配置：

最后点击“保存”按钮。

说明：“有效的重定向 URL”是填写 Keycloak 所允许的哪些应用（业务）系统（URL）能够使用 Keycloak 的认证授权服务，支持填写多个，填写格式建议为：服务根地址后面加上/*号。

• 选择“凭据”选项卡，如下图所示：

说明：“秘密”即客户端密钥，与在 SuperMap iServer/iPortal/iEdge 中的“Keycloak 登录配置”的“客户端密钥”一致。

• 选择“Mappers”选项卡，配置角色映射，点击“创建”按钮，创建协议映射器，配置如下图所示：

说明：

• “名称”：映射器的名称，可随意填写，例如：roles，建议与下面的“Token申请名”保持一致。
• “Realm角色前缀”：Keycloak 将用户的角色信息返回给客户端时，自动将每个角色带上的一个前缀。可随意填写，例如：KC_。如果不填，代表原样传给客户端。（该值对应 SuperMap iServer/iPortal/iEdge 中的“Keycloak登录配置”中的“属性角色关联信息配置”添加角色映射时的“属性值”的前缀）
• “Token申请名”：建议与上面的“名称”保持一致，例如：roles。Keycloak 将用户的角色信息返回给客户端时，客户端可以从哪个属性中获取角色信息（该值对应于 SuperMap iServer/iPortal/iEdge 中的“Keycloak登录配置”中的“角色属性标识”）

至此，完成了 Keycloak 客户端与 SuperMap iServer/iPortal/iEdge 的对接。之后，您还需要在创建的客户端中进行添加角色、添加用户等操作。

配置 Keycloak 对接 SuperMap iDesktop

这里以创建好的 ispeco 域为例，创建一个客户端，客户端 ID 命名为：iDesktop，这个是 SuperMap 约定的一个客户端 ID 名称，如下图所示：

点击“保存”按钮，进入如下图所示的详细配置页面：

说明：“有效的重定向 URL”填写 urn:ietf:wg:oauth:2.0:oob。

至此，对接桌面 SuperMap iDesktop 的 Keycloak 配置完成。打开 SuperMap iDesktop 时，可以直接使用 Keycloak 中的账户登录 SuperMap iServer/iPortal/iEdge。

添加角色

接下来，您可以点击导航栏中的“角色”，开始添加角色，您可以根据使用需求，创建多个角色，角色名称建议与 SuperMap iServer/iPortal/iEdge 中的角色名称保持一致，例如：DATA_CENTER，该角色在 SuperMap iServer/iPortal/iEdge 中的“Keycloak登录配置”中的“属性角色关联信息配置”中会加上前缀 KC_进行显示，例如：KC_DATA_CENTER。

添加用户

添加完角色后，您就可以进行创建用户操作。Keycloak 允许直接由管理员添加用户与开放用户注册两种方式进行用户的添加。

• 管理员添加用户

1. 管理员在 Keycloak 管理页面中点击左侧导航栏中的“用户”，进行添加用户操作。点击“添加用户”按钮，进行用户信息的填写，其中用户名为必填项，其余可按需求进行填写，完成后点击“保存”按钮。

2. 选择“凭据”选项卡，填写并确认密码，并关闭“临时”选项。

    

3. 选择“角色映射”选项卡，选中要分配给用户的角色，点击“添加选择”按钮，完成角色的分配。至此，完成管理员添加用户流程。

 

• 开放用户注册

1. 在 Keycloak 登录页面中可以开放用户的注册功能，管理员需要在 Keycloak 管理页面中进行配置。选择左侧导航栏“领域设置”，点击“登录”选项卡，启用“用户注册”选项，其余设置可按需求进行选择性启用，完毕后点击“保存”按钮。

2. 启用注册后还需要进行默认的角色分配，否则注册用户将因为没有分配的角色而无法登录 SuperMap iServer/iPortal/iEdge 。选择左侧导航栏“角色”选项，点击“默认角色”，选中所要分配给注册用户的默认角色，点击“添加选择”按钮，即完成了默认角色的分配，推荐赋予用户默认 PORTAL_USER 角色，具体的角色信息请参见角色和权限。

3. 完成注册功能开启和默认角色分配后，需要在 SuperMap iServer/iPortal/iEdge 中进行 Keycloak 的对接，具体方法参见：配置使用Keycloak进行认证授权。对接完成后在 SuperMap iServer/iPortal/iEdge 中点击“登录”按钮，即跳转到 Keycloak 登录页面，可在页面右侧找到用户注册入口。至此，完成用户注册功能的启用。

以上，完成了 Keycloak 的安装与配置过程。