OpenID Connect（OIDC）认证--keycloak与springboot项目的整合

OpenID Connect认证–keycloak与springboot项目的整合

前言

在现代应用程序中，安全性是至关重要的。为了简化认证和授权流程，许多开发人员选择使用 Keycloak 作为统一的身份和访问管理解决方案。Spring Boot 是一个流行的 Java 框架，通过与 Keycloak 整合，可以轻松实现 OAuth2 和 **OpenID Connect （OIDC）**的身份认证和授权功能。本篇博客将详细介绍如何在 Spring Boot 项目中集成 Keycloak，帮助你快速搭建一个安全的 Web 应用。

什么是 Keycloak？

Keycloak 是一个开源的身份和访问管理工具，支持标准协议如 OAuth2 和 OpenID Connect。它允许开发人员轻松地将身份验证、授权和单点登录（SSO）功能集成到应用程序中。通过 Keycloak，可以管理用户、角色、权限，并将这些管理功能集中化。

关于keycloak的配置我就不在这里赘述，具体请参考博文：什么是Keycloak？怎么样使用Keycloak实现登录和权限验证？

项目配置

我将通过一个 Spring Boot 项目来演示如何集成 Keycloak。

1. 创建 Spring Boot 项目

创建一个springboot项目，并引入下面的依赖：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
    <dependency>
        <groupId>org.keycloak</groupId>
        <artifactId>keycloak-spring-boot-starter</artifactId>
        <version>22.0.1</version> <!-- 根据需要选择合适的版本 -->
    </dependency>
</dependencies>

如果你使用的gradle，也大差不差：

dependencies {
   
  implementation(libs.spring.boot.starter.security)
  implementation(libs.spring.boot.starter.oauth2.client)
  implementation(libs.spring.boot.starter.oauth2.resource.server)
  implementation(libs.keycloak.spring.boot.starter)
}

主要就是上述的几个依赖，我使用的gradle来构建项目。

2. 设置 Keycloak 服务器

在整合之前，你需要设置一个 Keycloak 服务器。你可以通过 Docker 快速启动一个 Keycloak 实例：

docker run -d --name keycloak -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev

根据上述的docker容器配置，可以自己设置用户名和密码（均为admin），或者设置成你自己喜欢的方式，具体请参考博文：什么是Keycloak？怎么样使用Keycloak实现登录和权限验证？，或是查看官方文档：keycloak操作手册

由于生产需要我是将keycloak部署在公网上的，大概就是：https://keycloak.xxx.cn/，后面的链接我都用这个来替代。

3. 在 Keycloak 中创建 Realm 和 Client

登录到 Keycloak 管理控制台后：

1. 创建 Realm: 在左侧菜单中选择 “Add realm”，输入一个名称，例如 myrealm，然后点击 “Create”。

2. 创建 Client

   在创建好的 Realm 中，导航到 “Clients” 部分，点击 “Create” 创建一个新客户端。

   • Client ID: 输入一个客户端 ID，例如 spring-boot-client。
   • Client Protocol: 选择 openid-connect。
   • Root URL: 输入 Spring Boot 应用的根 URL，例如 http://localhost:8081。
   • Save: 点击 “Save” 保存配置。

在客户端的配置页面，确保 “Access Type” 设置为 confidential 并保存，然后生成并复制客户端的 Secret。

上述的信息在后续在配置springboot后端的时候会用到。这部分在这篇博文上也有提到：什么是Keycloak？怎么样使用Keycloak实现登录和权限验证？

4. 配置 Spring Boot 应用

在 application.yml 或 application.properties 中，添加 Keycloak 配置信息：

spring:
  application:
    name: customer_management
  security:
    oauth2:
      client:
        registration:
          keycloak:
            client-id: web_app
            authorization-grant-type: implicit
            scope:
              - openid
        provider:
          keycloak:
            issuer-uri: https://keycloak.scysn.cn/realms/test
            user-name-attribute: preferred_username
      resource server:
        jwt:
          issuer-uri: https://keycloak.scysn.cn/realms/test
server:
  port: 8081
application:
  security:
    oauth2:
      audience: account,api://default
  oauth2:
    # authorization-url: http://localhost:9080/realms/ysn/protocol/openid-connect/auth
    authorization-url: https://keycloak.scysn.cn/realms/test/protocol/openid-connect/auth

在上述的配置文件中，主要需要配置的就是下面这几个参数：

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

5. 配置 Spring Security

在 Spring Boot 项目中，通过创建一个 SecurityConfig 类来配置安全性:

在这个配置类中主要是配置以下这个bean对象：

@Bean
public SecurityFilterChain resourceServerFilterChain(HttpSecurity http) throws Exception {
   
    http.authorizeHttpRequests(auth -> auth
       .requestMatchers(new AntPathRequestMatcher("/customers*", HttpMethod.OPTIONS.name()))
       .permitAll()
       .requestMatchers(new AntPathRequestMatcher("/customers*"))
       .hasRole("user")
       .requestMatchers(new AntPathRequestMatcher("/"))
       .permitAll()
       .anyRequest()
       .authenticated());
    http.oauth2ResourceServer((oauth2) -> oauth2
       .jwt(Customizer.withDefaults()));
    http.oauth2Login(Customizer.withDefaults())
       .logout(logout -> logout.addLogoutHandler(keycloakLogoutHandler).logoutSuccessUrl("/"));
    return http.build();
}

在上面的代码中，oauth2Login *()方法将**OAuth2LoginAuthenticationFilter*添加到过滤器链中。该过滤器拦截请求并应用 OAuth 2 身份验证所需的逻辑。oauth2ResourceServer方法验证 JWT 令牌与 Keycloak 服务器的绑定。它还强制执行前面讨论的约束。

Keycloak 返回一个包含所有相关信息的令牌。为了使 Spring Security 能够根据用户分配的角色做出决策，我们必须解析令牌并提取相关详细信息。但是 Spring Security 通常在每个角色名称中添加*“ROLES_”前缀，而 Keycloak 则发送纯角色名称。为了解决这个问题，我们创建了一个辅助方法，它为从 Keycloak 检索到的每个角色添加“ROLE_”前缀。*

@Bean
Collection generateAuthoritiesFromClaim(Collection roles) {
   
    return roles.stream().map(role -> new SimpleGrantedAuthority("ROLE_" + role)).collect(
           Collectors.toList());
}

现在我们可以继续解析令牌了。首先，我们必须检查令牌是否是 OidcUserAuthority 或 OAuth2UserAuthority 的实例。由于 Keycloak 令牌可以是任何一种类型，因此我们需要实现解析逻辑。下面的代码检查令牌的类型并决定解析机制。

boolean isOidc = authority instanceof OidcUserAuthority;
    if (isOidc) {
    
       /// Parsing code here
    }

默认情况下，令牌是 OidcUserAuthority 的一个实例。

如果令牌是 OidcUserAuthority 实例，则可以将其配置为包含两个组或领域访问下的角色。因此，我们必须检查两者以提取角色，如下面的代码所示，

if (userInfo.hasClaim(REALM_ACCESS_CLAIM)) {
   
    var realmAccess = userInfo.getClaimAsMap(REALM_ACCESS_CLAIM);
    var roles = (Collection) realmAccess.get(ROLES_CLAIM);
    mappedAuthorities.addAll(generateAuthoritiesFromClaim(roles));
} else if (userInfo.hasClaim(GROUPS)) {
   
    Collection roles = (Collection) userInfo.getClaim(GROUPS);
    mappedAuthorities.addAll(generateAuthoritiesFromClaim(roles));
}

但是，如果令牌是 OAuth2UserAuthority 实例，我们需要按如下方式解析它：

var oauth2UserAuthority = (OAuth2UserAuthority) authority;
Map<String, Object> userAttributes