keycloak

使用 Keycloak 为 Spring Cloud Gateway 和 Spring Boot 微服务启用 OAuth2

本文将带你了解如何使用 Keycloak 为 Spring Cloud Gateway 和 Spring Boot 微服务启用 OAuth2。本文是 上一篇文章 的扩展,并分析了 Spring Security 项目中提供的一些最新功能。 我们的架构由两个 Spring Boot 微服务组成、一个基于 Spring Cloud Gateway 的 API 网关和一个 Keycloak 授权服务器。Spring Cloud Gateway 在此充当 OAuth2 客户端和 OAuth2 资源服务器。对于任何传入请求,它都会在将流量转发到下游服务之前验证 Access Token。对于任何未经验证的请求,它都会使用 Keycloak 初始化一个授权码授权的流程。我们的方案需要包括内部微服务之间的通信。它们都隐藏在 API 网关后面。caller 应用调用 callme 应用暴露的端点。通信中使用的 HTTP 客户端必须使用网关发送的 Access Token。 源码 本文中的代码托管在 Github,你可以克隆这个 Repository,进入到 oauth 目录,其中包含了两个 Spring Boot 微服务:callme 和 caller。当然,还有构建在 Spring Cloud Gateway 之上的 gateway 应用。之后,只需按照说明操作即可。 运行并配置 Keycloak 我们以 Docker 容器的形式运行 Keycloak。默认情况下,Keycloak 在 8080 端口上公开 API 和 Web 控制台。还需要通过环境变量设置管理员用户名和密码。下面是运行 Keycloak 容器的命令:

启用 Spring Cloud Gateway 的 OAuth2 支持,并将其与 Keycloak 集成

Spring Cloud Gateway 的 OAuth2 支持是微服务安全流程的关键部分。当然,使用 API 网关模式的主要原因是将服务隐藏起来,不对外部客户端可见。然而,在隐藏服务时,并没有对其进行安全保护。本文将带你了解如何使用 Spring Security 和 Keycloak 设置 Spring Cloud Gateway 的 OAuth2 功能。 源码 本文中的源码托管在 Github 上,你可以克隆 sample-spring-security-microservices 仓库,然后按照说明进行安装和部署即可。 在 Spring Cloud Gateway 中启用 OAuth2 要为 Spring Cloud Gateway 应用启用 OAuth2 支持,除了启用网关功能所必需的 spring-cloud-starter-gateway 依赖外,还需要添加 spring-boot-starter-oauth2-client 以启用 Spring Security 对 OAuth 2.0 授权框架和 OpenID Connect Core 1.0 的客户端支持,以及 spring-cloud-starter-security 来激活 TokenRelay Filter。 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-oauth2-client</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-gateway</artifactId> </dependency> <dependency> <groupId>org.springframework.cloud</groupId> <artifactId>spring-cloud-starter-security</artifactId> </dependency> 接下来为 OAuth2 客户端提供配置设置。因为要与 Keycloak 集成,所以应将 registrationId 的名称(spring.

使用 Spring Security OAuth2 实现 SSO 单点登录

1、概览 本文将带你了解如何使用 Spring Security OAuth 和 Spring Boot 以及 Keycloak 作为授权服务器来实现单点登录(SSO)。 我们会使用 4 个不同的应用: 授权服务器 - 中央认证机制 资源服务器 - Foo 资源的提供者 两个客户端应用 - 使用 SSO 的应用 简单地说,当用户试图通过一个客户端应用访问资源时,他们会被重定到授权服务器进行身份认证。Keycloak 会对用户进行登录,在登录第一个应用后,如果使用同一浏览器访问第二个客户端应用,用户无需再次输入凭据。 使用 OAuth2 的授权码(Authorization Code)模式。 Spring Security 将此功能称为 OAuth 2.0 登录,而 Spring Security OAuth 将其称为 SSO。 2、授权服务器 以前,通过 Spring Security OAuth 可以将授权服务器设置为 Spring 应用。 不过,Spring Security OAuth 已被 Spring 弃用,现在可以使用 Keycloak 作为授权服务器。 因此,这次我们在 Spring Boot 应用中把授权服务器设置为嵌入式 Keycloak 服务器。 在 预配置 中,我们将定义两个客户端,即 ssoClient-1 和 ssoClient-2,分别对应每个客户端应用。

自定义 Keycloak 的登录页面

1、概览 Keycloak 是第三方授权服务器,用于管理 Web 或移动应用的身份验证和授权。它为用户提供了一个默认的登录页面。 本文将带你了解如何自定义 Keycloak 服务器的登录页面。 本文在 《自定义 Keycloak 主题》 基础上进行实现。 2、独立 Keycloak 服务器 继续以 custom 主题为例,先看看独立服务器。 2.1、管理控制台设置 进入 Keycloak 目录,然后在 bin 文件夹中运行如下命令,启动服务器: kc.[sh|bat] start-dev --spi-theme-static-max-age=-1 --spi-theme-cache-themes=false --spi-theme-cache-templates=false 使用上述命令启动服务器后,只需刷新页面,就能看到更改。 现在,在 themes/custom 目录中新建一个名为 login 的文件夹。为了简单起见,先将 themes/keycloak/login 目录中的所有内容复制到这里。这是默认的登录页面主题。 然后,进入管理控制台(http://localhost:8080/admin/master/console),使用 initial1/zaq1!QAZ 凭证登录,并进入 Realm 的 “Themes” 选项卡: 为 Login Theme 选择 custom,然后保存更改。 现在就可以尝试一些自定义功能了。不过在此之前,先来看看默认登录页面: 2.2、添加自定义内容 现在,假设我们需要更改背景。 打开 login/resources/css/login.css 并更改 class 定义: .login-pf body { background: #39a5dc; background-size: cover; height: 100%; } 刷新页面即可看到效果: 接下来,尝试更改用户名和密码的标签。

自定义 Keycloak 主题

1、概览 Keycloak 是一个开源的身份和访问管理(Identity and Access Management,IAM)解决方案,可以作为第三方授权服务器来管理 Web 或移动应用的身份验证和授权。 本文将带你了解如何自定义 Keycloak 的主题,为终端用户的网页提供不同的外观。 本文以之前的文章为基础:《Keycloak 指南》和《在 Spring Boot 中嵌入 Keycloak》。因此,对于初学者来说,最好先阅读这两篇文章。 2、Keycloak 的主题 2.1、默认主题 Keycloak 中预置了几个主题,并与发行版绑定在一起。 对于单机版服务器,可在 ../lib/lib/main/org.keycloak.keycloak-themes-20.0.3.jar(可使用任何标准 ZIP 压缩工具打开)的主题目录下的不同文件夹中找到这些主题: base:包含 HTML 模板和 Message Bundle 的骨架主题;所有主题(包括自定义主题)一般都继承自 base 主题 keycloak:包含用于美化页面的图片和样式表;如果我们不提供自定义主题,则默认使用该主题 keycloak.v2:基于 React 的主题;新管理控制台的一部分;旧控制台已过时,将在 Keycloak 21 中移除。 不建议修改现有主题。相反,应该创建一个新主题,从上述两个主题中继承。 要创建一个新的自定义主题,需要在 themes 目录中添加一个新的文件夹,称之为 custom。如果想要完全重建,则建议从 base 文件夹中复制内容。 在本例中,我们并不打算替换所有内容,因此从 keycloak 目录中获取内容。 2.2、主题类型 Keycloak 支持五种主题: Welcome:用于欢迎页 Login:用于登录、OTP、授予、注册和忘记密码页面 Account:用于用户账户管理页面 Admin Console:用于管理控制台 Email:用于服务器发送的电子邮件 上述列表中的最后四个主题可以通过独立服务器的管理控制台进行设置。当我们在 themes 目录下创建一个新文件夹后,服务器重启后就可以选择该文件夹。 使用凭证 initial1 / zaq1!QAZ(在 上一文章 中设置的)登录管理控制台,并转到 Realm 的 “Themes” 选项卡:

Keycloak 自定义用户属性

1、概览 Keycloak 是第三方授权服务器,负责管理我们 Web 或移动应用的用户。 它提供了一些默认属性,例如名字、姓氏和电子邮件,用于存储任何给定用户的信息。但是很多时候,这些属性是不够的,我们可能需要添加一些特定于我们应用的额外用户属性。 本文将带你了解如何在 Keycloak 授权服务器中添加自定义用户属性,并在基于 Spring 的后端中访问它们。 2、独立服务器 2.1、添加自定义用户属性 基于上文 “Spring Boot 整合 Keycloak” 中的 Keycloak 服务器。 第一步是进入 Keycloak 的管理控制台。 在 Keycloak 发行版的 bin 文件夹中运行如下命令来启动服务器: kc.bat start-dev 然后,进入 Web 管理控制台 http://localhost:8180/auth/admin,输入凭证:initial1 / zaq1!QAZ 。 接下来,点击 “Manage” 选项卡下的 “Users”: 在这里,可以看到 之前(上一篇文章)添加的用户:user1。 点击 “ID”,然后转到 “Attributes” 选项卡,添加一个新的属性,即表示出生日期的 “DOB”: 点击 “Save” 后,自定义属性就会添加到用户信息中。 接下来,将此属性作为自定义 Claim 添加到映射中,以便它在用户 Token 的 JSON Payload 中可用。 为此,需要进入管理控制台的 “应用客户端”。回想一下 之前 创建的客户端 login-app: 点击它,然后选择 “Client scopes” 选项卡。在 “Client scopes” 页面点击 “login-app-dedicated” 链接,进入 “Mappers” 选项卡。点击 “Configure a new mapper”,选择 “User Attribute” 创建新 mapper:

Spring Boot 整合 Keycloak

1、概览 本文将带你了解如何设置 Keycloak 服务器,以及如何使用 Spring Security OAuth2.0 将 Spring Boot 应用连接到 Keycloak 服务器。 2、Keycloak 是什么? Keycloak 是针对现代应用和服务的开源身份和访问管理解决方案。 Keycloak 提供了诸如单点登录(SSO)、身份代理和社交登录、用户联盟、客户端适配器、管理控制台和账户管理等功能。 本文使用 Keycloak 的管理控制台,使用 Spring Security OAuth2.0 设置和连接 Spring Boot。 3、设置 Keycloak 服务器 设置和配置 Keycloak 服务器。 3.1、下载和安装 Keycloak 有多种发行版可供选择,本文使 Keycloak-22.0.3 独立服务器发行版。点击 这里 从官方下载。 下载完后,解压缩并从终端启动 Keycloak: unzip keycloak-22.0.3.zip cd keycloak-22.0.3 bin/kc.sh start-dev 运行这些命令后,Keycloak 会启动服务。如果你看到一行类似于 Keycloak 22.0.3 [...] started 的内容,就表示服务器启动成功。 打开浏览器,访问 http://localhost:8080,会被重定向到 http://localhost:8080/auth 以创建管理员进行登录: 创建一个名为 initial1 的初始管理员用户,密码为 zaq1!QAZ。点击 “Create”后,可以看到 “User Created” 的提示信息。 现在进入管理控制台。在登录页面,输入 initial 管理员用户凭证:

在 Spring Boot 中禁用 Keycloak Security

1、概览 Keycloak 是一个开源的身份和访问管理解决方案。在测试阶段,禁用 Keycloak 可能有助于专注于业务测试。而且在测试环境中可能没有 Keycloak 服务器。 本文将带你了解如何禁用 Keycloak starter 的配置,以及如何在项目中启用 Spring Security 后如何对其进行修改。 2、在非 Spring Security 环境下禁用 Keycloak 我们首先来看看如何在不使用 Spring Security 的应用中禁用 Keycloak。 2.1、应用设置 首先,添加 spring-boot-starter-oauth2-client 依赖。 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-oauth2-client</artifactId> </dependency> 此外,还需要添加 spring-boot-starter-oauth2-resource-server 依赖。它将允许我们使用 Keycloak 服务器验证 JWT Token: <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-oauth2-resource-server</artifactId> </dependency> 接下来,在 application.properties 中添加 Keycloak 服务器的配置: spring.security.oauth2.client.registration.keycloak.client-id=login-app spring.security.oauth2.client.registration.keycloak.authorization-grant-type=authorization_code spring.security.oauth2.client.registration.keycloak.scope=openid spring.security.oauth2.client.provider.keycloak.issuer-uri= http://localhost:8080/realms/SpringBootKeycloak spring.security.oauth2.client.provider.keycloak.user-name-attribute=preferred_username spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8080/realms/SpringBootKeycloak 最后,添加 UserController 来检索用户: @RestController @RequestMapping("/users") public class UserController { @GetMapping("/{userId}") public User getCustomer(@PathVariable Long userId) { return new User(userId, "John", "Doe"); } } 2.

使用 Testcontainers 对 Keycloak 进行集成测试

1、简介 通常我们会通过集成测试来验证应用功能是否正常。集成测试至关重要,特别是对于认证这种敏感且重要的功能。Testcontainers 允许在测试阶段启动 Docker 容器,以便对实际的技术栈运行测试。 本文将带你了解如何使用 Testcontainers 针对实际的 Keycloak 实例设置集成测试。 2、配置 Spring Security 和 Keycloak 我们需要配置 Spring Security、Keycloak 和 Testcontainers。 2.1、整合 Spring Boot 和 Spring Security 在 pom.xml 中添加 spring-boot-starter-security 依赖。 <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-security</artifactId> </dependency> 接着,创建一个示例 Controller,它返回一个 User。 @RestController @RequestMapping("/users") public class UserController { @GetMapping("me") public UserDto getMe() { return new UserDto(1L, "janedoe", "Doe", "Jane", "jane.doe@baeldung.com"); } } 至此,我们有了一个受保护的 Controller,用于处理对 /users/me 端点的请求。启动应用时,Spring Security 会为用户 user 生成一个密码,该密码在控制台输出的日志中。 2.配置 Keycloak 启动本地 Keycloak 的最简单方法是使用 Docker。