Spring Boot+Keycloak从零到壹

作者： Michael Good

译者： helloworldtang

1. 概览

在本文中，我们将介绍安装、配置Keycloak服务器的基础知识，如何将Spring Boot应用程序**和Keycloak服务器连接起来，以及在Spring Security下如何使用它。

2. Keycloak是什么?

Keycloak是一种面向现代应用程序和服务的开源的IAM(身份识别与访问管理)解决方案。

Keycloak提供了单点登录（SSO）、Identity Brokering和社交账号登录、User Federation、客户端适配器、管理控制台和帐户管理控制台等特性。想了解更多关于Keycloak的信息，请访问官方页面 。

在本教程中，我们将使用Keycloak的管理控制台进行配置，然后在Spring Boot应用程序中使用Keycloak Client Adapter和Keycloak服务器连接起来。

3. 安装并配置Keycloak服务器

3.1. 下载并安装Keycloak

Keycloak提供了多个发行版可供选择。 但是，在本教程中，我们将使用独立版本。

从官方来源下载Keycloak-3.3.0.Final独立服务器发行版 。

下载独立的服务器发行版后，我们在本地终端解压并启动Keycloak：

unzip keycloak-3.3.0.Final.zip
cd keycloak-3.3.0.Final/bin
./standalone.sh -Djboss.socket.binding.port-offset=100

执行./standalone.sh后，Keycloak将开始提供服务。当看到控制台输出中包含Keycloak 3.3.0.Final (WildFly Core 3.0.1.Final)字样的信息，我们就知道Keycloak已经启动成功了。

打开浏览器并访问http://localhost:8180. 我们将被重定向到http://localhost:8180/auth 去创建一个初始的admin用户：

让我们创建一个名为“initial1”的用户，密码“zaq1!QAZ“。 我们现在看到了“Welcome to Keycloak”页面：

现在我们可以继续在管理控制台上进行操作。

3.2. 创建一个Realm

让我们将鼠标导航到左上角，找到“Add Realm”按钮：

我们把它命名为“SpringBootKeycloak“：

3.3. 创建一个客户端

现在我们将导航到Clients页面。正如我们在下图中所看到的，Keycloak已经整合了已经内置的客户端：

我们需要在应用程序中添加一个客户端，所以我们点击“Create”。我们配置新的Client ID为“login-app“：

在下一个页面中，对于本教程而言，除了“Valid Redirect URIs 字段”之外，我们将保留所有缺省值。配置完成后，将被重定向到端口8081：

3.4. 创建一个角色和用户

Keycloak使用Role-Based Access。因此，每个用户都必须有一个角色。 我们需要导航到“Role”页面：

然后，我们添加 “user”角色：

现在我们已经有了一个可以分配给用户的角色，但是还没有一个用户。因此，让我们去“Users”页面新增一个：

我们创建用户“user1”:

如果用户被创建，用户信息将展示在这里：

我们现在可以进入“Credentials”选项卡，并将把密码设置为“xsw2@WSX”：

我们导航到“Role Mappings”选项卡，并分配用户角色：

4. 创建Spring Boot应用程序

4.1. 依赖

在 Maven Central找到最新的Spring Boot Keycloak Starter依赖。

Keycloak Spring Boot 适配器是基于 Spring Boot的自动配置，因此我们所需要做的就是将Keycloak Spring Boot starter添加到我们的项目中。

如果要在Spring Boot项目中使用Keycloak，我们需要在pom.xml文件中添加以下依赖：

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-spring-boot-starter</artifactId>
</dependency>

除此之外，我们还需要指定Keycloak的dependencyManagement ：

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.keycloak.bom</groupId>
            <artifactId>keycloak-adapter-bom</artifactId>
            <version>3.3.0.Final</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

如果使用Spring Boot Keycloak Starter，我们不需要任何额外的依赖就可以支持以下嵌入式Web容器:

• Tomcat
• Undertow
• Jetty

4.2. Thymeleaf Web页面

我们使用Thymeleaf来实现web页面。 我们已经创建了以下三个页面：

• external.html – 不需要身份认证的web页面
• customers.html– 需要通过认证并且具有“user”角色的用户才能访问的web页面。
• layout.html– 一个由两个fragment组成的简单布局,用于external.html 和 customers.html 页面

与Thymeleaf模板相关的代码已经放在Github上了。

4.3. 控制器

Web控制器将内部和外部的URL映射到对应的Thymeleaf模板：

@GetMapping(path = "/")
public String index() {
    return "external";
}

@GetMapping(path = "/customers")
public String customers(Model model) {
    addCustomers();
    model.addAttribute("customers", customerDAO.findAll());
    return "customers";
}

对于URL路径/customers，我们检索所有客户数据，并将结果作为属性添加到Model中。稍后，我们将在Thymeleaf中遍历这些客户数据。

4.4. Keycloak配置

下面是基础的，必须配置的属性：

keycloak.auth-server-url=http://localhost:8180/auth
keycloak.realm=SpringBootKeycloak
keycloak.resource=login-app
keycloak.public-client=true

正如我们所记得的，我们在8180端口上启动了Keycloak，因此配置keycloak.auth-server-url的值为验证服务器的URL，并且配置了在Keycloak管理控制台中创建的realm。 我们在keycloak.resource中指定的值与我们在管理控制台中命名的client相匹配。

下面是我们将要使用的安全约束：

keycloak.security-constraints[0].authRoles[0]=user
keycloak.security-constraints[0].securityCollections[0].patterns[0]=/customers/*

上面配置的安全约束可以确保只有通过认证，并且具有“user”角色的用户才能访问/customers/*。

4.5. 演示

现在，我们已经准备好测试我们的应用程序了。要运行Spring Boot应用程序，我们可以轻松地通过Spring Tool Suite（STS）之类的IDE启动它，或者在终端中运行命令：

mvn clean spring-boot:run

我们访问localhost:8080：

现在我们点击 “customers” 链接，查看存放敏感信息的内网。

可以看到,我们已经被重定向到Keycloak进行认证,并且要检查当前用户是否被授权查看这个内容:

如果通过认证，并且通过Keycloak的授权检查，我们就会被重定向到受限访问的customers页面：

现在，我们已经完成了将Spring Boot与Keycloak连接起来的配置，并演示了它是如何工作的。

现在，我们将讨论如何将Spring Security与现有的应用程序结合使用。

5. Spring Security

Spring Boot Keycloak Starter依赖中已经包含了一个Keycloak Spring Security适配器。现在我们来看看如何将Spring Security和Keycloak集成。

5.1. 依赖

如果要在Spring Boot中使用Spring Security，我们必须添加这个依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
    <version>1.5.3</version>
</dependency>

最新的Spring Boot Starter Security版本可以在 Maven Central找到。

5.2. 配置类

Keycloak提供了一个很方便的基类KeycloakWebSecurityConfigurerAdapter来创建WebSecurityConfigurer实例，因为任何由Spring Security保护的应用程序都需要一个配置类来扩展WebSecurityConfigurerAdapter：

@Configuration
@EnableWebSecurity
@ComponentScan(basePackageClasses = KeycloakSecurityComponents.class)
class SecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

    @Autowired
    public void configureGlobal(
      AuthenticationManagerBuilder auth) throws Exception {

        KeycloakAuthenticationProvider keycloakAuthenticationProvider
         = keycloakAuthenticationProvider();
        keycloakAuthenticationProvider.setGrantedAuthoritiesMapper(
          new SimpleAuthorityMapper());
        auth.authenticationProvider(keycloakAuthenticationProvider);
    }

    @Bean
    public KeycloakSpringBootConfigResolver KeycloakConfigResolver() {
        return new KeycloakSpringBootConfigResolver();
    }

    @Bean
    @Override
    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new RegisterSessionAuthenticationStrategy(
          new SessionRegistryImpl());
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.authorizeRequests()
          .antMatchers("/customers*")
          .hasRole("user")
          .anyRequest()
          .permitAll();
    }
}

请注意上面的代码：

• configureGlobal：任务SimpleAuthorityMapper，以确保角色不以ROLE_为前缀
• keycloakConfigResolver：定义了我们想要使用的Spring Boot 属性文件支持而不是默认的keycloak.json

5.3. application.properties

因为已经用Spring Security设置了安全约束，所以我们可以删除之前配置在application.properties中的相关配置。 现在我们将新增这个配置到application.properties中：

keycloak.principal-attribute=preferred_username

5.4. 控制器

为了获取到当前用户的用户名，我们需要在控制器注入Principal参数，修改后的代码如下所示：

@GetMapping(path = "/customers")
public String customers(Principal principal, Model model){
    addCustomers(); 
    model.addAttribute("customers", customerDAO.findAll());
    model.addAttribute("username", principal.getName());
    return "customers";
}

5.5. Thymeleaf

在div标签中，我们将添加一个问候语，如下所示：

<h1>Hello, <span th:text="${username}">--name--</span>.</h1>

5.6. Demo

现在，通过认证和授权检查后，页面将跳转到内部的customers页面之后，我们将看到：

6 总结

在本教程中，我们配置了一个Keycloak服务器，并在Spring Boot应用程序中使用这个服务器。

我们还看到了如何配置Spring Security，并将其与Keycloak服务器结合使用。本文中用到的代码可以在Github上找到。