Keycloak安装与配置

发送反馈


安装 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

注意:如果您下载安装高版本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,进行以下配置。需要注意的是,域和域之间的资源(包括用户、角色、客户端等一切信息)是相互隔离的。

  1. 创建一个客户端

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

最后点击“保存”按钮。

说明:

说明:“秘密”即客户端密钥,与在 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,进行以下配置。需要注意的是,域和域之间的资源(包括用户、角色、客户端等一切信息)是相互隔离的。

  1. 创建一个客户端

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

最后点击“保存”按钮。

说明:

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

  1. 创建协议映射器

最后点击“保存”按钮。

说明:

至此,完成了 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 的客户端。左侧导航栏选择“客户端”,在右侧页面点击“创建”按钮,添加客户端:

说明:

  1. 开启客户端的 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

说明:

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

注意: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 的客户端。左侧导航栏选择“客户端”,在右侧页面点击“创建客户端”按钮,添加客户端:

 

最后点击“保存”按钮。

说明:

  1. 开启客户端的 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"

说明:

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

注意: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 的对接。之后,您还需要在客户端所在域中进行添加角色添加用户等操作。

配置 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 管理页面中点击左侧导航栏中的“用户”,进行添加用户操作。点击“添加用户”按钮,进行用户信息的填写,其中用户名为必填项,其余可按需求进行填写,完成后点击“保存”按钮。

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

   

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

 

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

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

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


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