Keycloak安装与配置

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

安装 Keycloak

下载安装 Keycloak，建议安装 keycloak 4.8.3 及以上版本，Keycloak 官网下载地址：https://www.keycloak.org/downloads

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

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

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

在 keycloak-4.8.3.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，下载完成后，解压缩文件，在 keycloak-x.x.x/bin 目录下，执行以下 DOS 命令，启动 Keycloak。

kc.bat start-dev

配置 Keycloak 对接 SuperMap iServer/iPortal/iEdge

1.低版本 Keycloak

访问 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。

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

最后点击“保存”按钮。

说明：

• “访问类型”：选择 confidential，即访问该客户端时需携带“秘密”（客户端密钥）。
• “有效的重定向 URL”（必填）：填写 Keycloak 所允许的哪些应用（业务）系统（URL）能够使用 Keycloak 的认证授权服务，支持填写多个，填写格式建议为：服务根地址后面加上/*号。
• “Web 起源”（必填）：填写允许跨域请求的站点，填写格式建议为：服务根地址后面加上/*号。如果只填入“*”，则表示允许所有跨域访问，需谨慎使用。注意：在4.8.3版本的Keycloak中，此处填写允许跨域请求的站点，指定格式为：http://172.16.120.212:8090，且只填入“*”是不允许所有跨域访问的。

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

说明：“秘密”即客户端密钥，与在 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/iEdge 的对接。之后，您还需要在客户端所在域中进行添加角色、添加用户等操作。

2.高版本 Keycloak

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

点击左侧导航栏中的“Realm settings”，在右侧页面选择“Themes”选项卡，其中，“Login theme”项、“Account theme”项、“Admin theme”项、“Email theme”项全部选择“keycloak”，选择“Localization”选项卡，“Internationalization ”项选择“Enabled”，开启国际化，“Supported locales”项选择“中文（中国）”“Default Locale”项选择“中文（中国）”，最后点击“Save”按钮。

此时，管理员登出， Keycloak 的登录页面切换为中文，登录 Keycloak。

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

1. 创建领域

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

2. 创建一个客户端

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

• “客户端类型”：选择默认的 OpenID Connect。

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

• 点击“下一步”按钮，进入客户端功能配置页面，按照下图所示继续配置：

• 点击“下一步”按钮，进入客户端登录设置页面，按照下图所示继续配置：

最后点击“保存”按钮。

说明：

• “有效的重定向 URL”（必填）：填写 Keycloak 所允许的哪些应用（业务）系统（URL）能够使用 Keycloak 的认证授权服务，支持填写多个，填写格式建议为：服务根地址后面加上/*号。
• “网络根源”（必填）：允许的 CORS 来源。要允许有效重定向 URL 的所有来源，请添加“+”，不过这不包括“*”通配符。要允许所有来源，请明确添加“*”。

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

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

3. 创建协议映射器

• 左侧导航栏选择“客户端范围”，在客户端范围列表中点击“roles”，进入客户端作用域详细信息页面，选择“映射”选项卡，点击“realm roles”，配置角色映射，配置如下图所示：

最后点击“保存”按钮。

说明：

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

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

配置 Keycloak 对接 SuperMap iPortal 的后续步骤

1.低版本 Keycloak

配置 Keycloak 对接 SuperMap iPortal 的前序步骤与 SuperMap iServer/iEdge 一致，除了完成以上配置外，还需开启上述客户端的 token-exchange 权限，并以 "Client" 作为关联策略，为其关联一个访问类型为 public 的客户端。这里以在 ispeco 域下创建好的 ispeco-oidc 客户端为基础， 为您介绍对接 iPortal 的后续步骤：

1. 创建一个访问类型为 public 的客户端

在完成  ispeco-oidc 客户端创建后，您还需要创建一个访问类型为 public 的客户端。左侧导航栏选择“客户端”，在右侧页面点击“创建”按钮，添加客户端：

• “客户端 ID”：输入“客户端 ID”，该“客户端 ID”您可以随意命名，例如：ispeco-kh。该“客户端 ID”对应 SuperMap iPortal 中的“Keycloak 登录配置”中“关联的 public 客户端 ID”。
• “客户端协议”：选择默认的 openid-connect。

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

说明：

• “访问类型”：选择 public，即访问该客户端时无需携带“秘密”（客户端密钥）。
• “有效的重定向 URL”（必填）：填写 Keycloak 所允许的哪些应用（业务）系统（URL）能够使用 Keycloak 的认证授权服务，支持填写多个，填写格式建议为：服务根地址后面加上/*号。
• “Web 起源”（必填）：填写允许跨域请求的站点，填写格式建议为：服务根地址后面加上/*号。如果只填入“*”，则表示允许所有跨域访问，需谨慎使用。注意：在4.8.3版本的Keycloak中，此处填写允许跨域请求的站点，指定格式为：http://172.16.120.212:8090，且只填入“*”是不允许所有跨域访问的。

2. 开启客户端的 token-exchange 权限

您需要开启前序步骤所创建的客户端 ispeco-oidc 的 token-exchange 权限，并以 "Client" 作为关联策略，为其关联步骤一中创建的客户端  ispeco-kh。左侧导航栏选择“客户端”，在客户端列表中点击“ ispeco-oidc”，进入客户端配置页面：

• 选择“权限”选项卡，开启权限开关，如下图所示：

注意：如果您的客户端配置页面没有“权限”选项卡，您需要先停止 Keycloak 的运行，然后在 keycloak-4.8.3.Final/bin 目录下，执行以下 DOS 命令，开启细粒度授权功能并重启 Keycloak：

standalone.bat -Dkeycloak.profile.feature.admin_fine_grained_authz=enabled -Dkeycloak.profile.feature.token_exchange=enabled

• 点击 token-exchange，进入 token-exchange 权限设置页面，如下图所示：

• 点击创建策略，在下拉菜单中选择 "Client"，为 token-exchange 权限创建一个  "Client"（客户端）应用策略，如下图所示：

说明：

• “名称”：策略名称，可随意填写，例如：client。
• “客户端”：选择与当前客户端进行权限关联的客户端，此处应选择步骤一中创建的客户端 ispeco-kh 进行关联。

最后，点击“保存”按钮即可。

注意：Keycloak 的默认安全策略只允许同源的网站以 iframe 的形式加载 Keycloak 登录页面，这种限制是为了防止点击劫持攻击。

如果您的 iPortal 和 Keycloak 不同源，并且希望 iPortal 以 iframe 的形式加载 Keycloak 的登录页面，那么需要在【SuperMap iPortal 安装目录】\webapps\iportal\WEB-INF）文件夹下的 iportal.xml配置文件中将<iframeable>参数设置为true（默认为false，具体请参见：iPortal 配置文件说明）, 还需要在 Keycloak 的领域设置中按需修改相关的安全策略配置。

左侧导航栏选择“领域设置”，右侧页面选择“安全防护”选项卡，更改内容安全策略：

“内容安全策略”：在 frame-ancestors 'self' 后输入 iPortal 所在站点。例如：http://192.168.120.154:8889，若配置多个站点，用空格分隔即可。

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

2.高版本 Keycloak

配置 Keycloak 对接 SuperMap iPortal 的前序步骤与 SuperMap iServer/iEdge 一致，除了完成以上配置外，还需开启上述客户端的 token-exchange 权限，并以 "Client" 作为关联策略，为其关联一个访问类型为 public 的客户端。这里以在 ispeco 域下创建好的 ispeco-oidc 客户端为基础， 为您介绍对接 iPortal 的后续步骤：

1. 创建一个访问类型为 public 的客户端

在完成  ispeco-oidc 客户端创建后，您还需要创建一个访问类型为 public 的客户端。左侧导航栏选择“客户端”，在右侧页面点击“创建客户端”按钮，添加客户端：

• “客户端类型”：选择默认的 OpenID Connect。

• “客户端 ID”：输入“客户端 ID”，该“客户端 ID”您可以随意命名，例如：ispeco-kh。该“客户端 ID”对应 SuperMap iPortal 中的“Keycloak 登录配置”中“关联的 public 客户端 ID”。

• 点击“下一步”按钮，进入客户端功能配置页面，按照下图所示继续配置：

• 点击“下一步”按钮，进入客户端登录设置页面，按照下图所示继续配置：

最后点击“保存”按钮。

说明：

• “有效的重定向 URL”（必填）：填写 Keycloak 所允许的哪些应用（业务）系统（URL）能够使用 Keycloak 的认证授权服务，支持填写多个，填写格式建议为：服务根地址后面加上/*号。
• “网络根源”（必填）：允许的 CORS 来源。要允许有效重定向 URL 的所有来源，请添加“+”，不过这不包括“*”通配符。要允许所有来源，请明确添加“*”。

2. 开启客户端的 token-exchange 权限

您需要开启前序步骤所创建的客户端 ispeco-oidc 的 token-exchange 权限，并以 "Client" 作为关联策略，为其关联步骤一中创建的客户端  ispeco-kh。左侧导航栏选择“客户端”，在客户端列表中点击“ ispeco-oidc”，进入客户端配置页面：

• 选择“权限”选项卡，开启权限开关，如下图所示：

注意：如果您的客户端配置页面没有“权限”选项卡，您需要先停止 Keycloak 的运行，然后在 keycloak-x.x.x/bin 目录下，执行以下 DOS 命令，开启细粒度授权功能并重启 Keycloak：

kc.bat start-dev --features="admin-fine-grained-authz,token-exchange"

• 点击 token-exchange，进入 token-exchange 权限设置页面，如下图所示：

• 点击策略，在下拉菜单中选择 "创建客户端策略"，选择 "Client"，为 token-exchange 权限创建一个  "Client"（客户端）应用策略，如下图所示：

说明：

• “名称”：策略名称，可随意填写，例如：client。
• “客户端”：选择与当前客户端进行权限关联的客户端，此处应选择步骤一中创建的客户端 ispeco-kh 进行关联。

最后，点击“保存”按钮即可。

注意：Keycloak 的默认安全策略只允许同源的网站以 iframe 的形式加载 Keycloak 登录页面，这种限制是为了防止点击劫持攻击。

如果您的 iPortal 和 Keycloak 不同源，并且希望 iPortal 以 iframe 的形式加载 Keycloak 的登录页面，那么需要在【SuperMap iPortal 安装目录】\webapps\iportal\WEB-INF）文件夹下的 iportal.xml配置文件中将<iframeable>参数设置为true（默认为false，具体请参见：iPortal 配置文件说明）, 还需要在 Keycloak 的领域设置中按需修改相关的安全策略配置。

左侧导航栏选择“领域设置”，右侧页面选择“安全防御”选项卡，更改内容安全策略：

“内容安全策略”：在 frame-ancestors 'self' 后输入 iPortal 所在站点。例如：http://192.168.13.60:8190，若配置多个站点，用空格分隔即可。

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

注意：如果您配置了19及以上版本的Keycloak，登出时需要配置参数。

左侧导航栏选择“领域角色”，右侧页面选择创建角色，添加view-users角色，如下图所示：

左侧导航栏选择“客户端”，在客户端列表中点击“ ispeco-oidc”，进入客户端详情页面：

• 选择“服务账户角色”选项卡，点击“分配角色”，如下图所示：

• 在分配角色页面，筛选器选择“按客户端筛选”，搜索框中输入 view-users，勾选 view-users，点击赋予，分配角色成功：

配置 Keycloak 对接 SuperMap iDesktop

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

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

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

至此，对接桌面 SuperMap iDesktop 的 Keycloak 配置完成。在 SuperMap iDesktop “云服务设置”页面添加 SuperMap iServer/iPortal/iEdge 地址后，可以直接使用 Keycloak 中的账户登录 SuperMap iServer/iPortal/iEdge。

添加角色

接下来，您可以点击导航栏中的“角色”，开始添加角色，您可以根据使用需求，创建多个角色，角色名称建议与 SuperMap iServer/iPortal/iEdge 中的角色名称保持一致，例如：DATA_CENTER。

需要注意的是，如果您在 Keycloak 中设置了角色前缀名，如：KC_，则在 SuperMap iServer/iPortal/iEdge 中的“Keycloak登录配置”>“属性角色关联信息配置”中添加的角色都需加上前缀，例如，添加的角色名为：DATA_CENTER，则此处应填写：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 的安装与配置过程。