SpringBoot+SpringSecurity+JWT實現系統認證與授權範例

2022-08-07 14:02:14

1. Spring Security簡介

Spring Security是Spring的一個核心專案，它是一個功能強大且高度可客製化的認證和存取控制框架。它提供了認證和授權功能以及抵禦常見的攻擊，它已經成為保護基於spring的應用程式的事實標準。

Spring Boot提供了自動設定，引入starter依賴即可使用。
Spring Security特性總結：

使用簡單，提供Spring Boot starter依賴，極易與Spring Boot專案整合。
專業，提供CSRF防護、點選劫持防護、XSS防護等，並提供各種安全頭整合（X-XSS-Protection，X-Frame-Options等）。
密碼加密儲存，支援多種加密演演算法
擴充套件性和可客製化性極強
OAuth2 JWT認證支援
… …

2. JWT簡介

JWT(Json web token),是為了在網路應用環境間傳遞宣告而執行的一種基於JSON的開放標準(RFC 7519).該token被設計為緊湊且安全的，特別適用於分散式站點的單點登入（SSO）場景。JWT的宣告一般被用來在身份提供者和服務提供者間傳遞被認證的使用者身份資訊，以便於從資源伺服器獲取資源，也可以增加一些額外的其它業務邏輯所必須的宣告資訊(例如，許可權資訊)。一旦使用者被授予token，使用者即可通過該token存取伺服器上的資源。

https://jwt.io/，該網站提供了一個debuggr，便於初學者學習理解JWT。

3. Spring Boot整合Spring Security

注意本篇文章演示使用JDK和Spring Boot的版本如下：
Spring Boot：2.7.2
JDK：11
不同的Spring Boot版本設定不同，但是原理相同。

在Spring Boot專案的pom.xml檔案中加入下面的依賴：

<!-- Spring Security的Spring boot starter,引入後將自動啟動Spring Security的自動設定 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-security</artifactId>
</dependency>
<!-- 下面的依賴包含了OAuth2 JWT認證實現 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>

以上兩個依賴即可。

4. 設定Spring Security使用JWT認證

注意： 不同的Spring Boot版本設定不同，但是原理相同,本文使用的是Spring Boot：2.7.2。

主要是設定HttpSecurity Bean生成SecurityFilterBean，設定如下：

import com.nimbusds.jose.jwk.JWK;
import com.nimbusds.jose.jwk.JWKSet;
import com.nimbusds.jose.jwk.RSAKey;
import com.nimbusds.jose.jwk.source.ImmutableJWKSet;
import com.nimbusds.jose.jwk.source.JWKSource;
import com.nimbusds.jose.proc.SecurityContext;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.oauth2.jwt.JwtDecoder;
import org.springframework.security.oauth2.jwt.JwtEncoder;
import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
import org.springframework.security.oauth2.jwt.NimbusJwtEncoder;
import org.springframework.security.oauth2.server.resource.authentication.JwtAuthenticationConverter;
import org.springframework.security.oauth2.server.resource.authentication.JwtGrantedAuthoritiesConverter;
import org.springframework.security.oauth2.server.resource.web.BearerTokenAuthenticationEntryPoint;
import org.springframework.security.oauth2.server.resource.web.access.BearerTokenAccessDeniedHandler;
import org.springframework.security.web.SecurityFilterChain;

import java.security.interfaces.RSAPrivateKey;
import java.security.interfaces.RSAPublicKey;

/**
 * Spring Security 設定
 *
 * @author cloudgyb
 * @since 2022/7/30 18:31
 */
@Configuration(proxyBeanMethods = false)
@EnableMethodSecurity
public class WebSecurityConfigurer {
    //使用RSA對JWT做簽名，所以這裡需要一對祕鑰。
    //祕鑰檔案的路徑在application.yml檔案中做了設定(具體設定在下面)。
    @Value("${jwt.public.key}")
    private RSAPublicKey key; 
    @Value("${jwt.private.key}")
    private RSAPrivateKey priv;

     /**
      * 構建SecurityFilterChain bean
      */
    @Bean
    SecurityFilterChain defaultSecurityFilterChain(HttpSecurity http) throws Exception {
        //"/login"是系統的登入介面，所以需要匿名可存取
        http.authorizeRequests().antMatchers("/login").anonymous();
        //其他請求都需認證後才能存取
        http.authorizeRequests().anyRequest().authenticated()
                .and()
                
                //採用JWT認證無需session保持，所以禁用掉session管理器
                .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS).and()
                //login介面可能來自其他站點，所以對login不做csrf防護
                .csrf((csrf) -> csrf.ignoringAntMatchers("/login"))
                //設定認證方式為JWT，並且設定了一個JWT認證裝換器，用於去掉解析許可權時的SCOOP_字首
                .oauth2ResourceServer().jwt().jwtAuthenticationConverter(
                        JwtAuthenticationConverter()
                );
        //設定認證失敗或者無許可權時的處理器
        http.exceptionHandling((exceptions) -> exceptions
                .authenticationEntryPoint(new BearerTokenAuthenticationEntryPoint())
                .accessDeniedHandler(new BearerTokenAccessDeniedHandler())
        );
         //根據設定生成SecurityFilterChain物件
        return http.build();
    }


    /**
     * JWT解碼器，用於認證時的JWT解碼 
     */
    @Bean
    JwtDecoder jwtDecoder() {
        return NimbusJwtDecoder.withPublicKey(this.key).build();
    }
    /**
     * JWT編碼器，生成JWT
     */
    @Bean
    JwtEncoder jwtEncoder() {
        JWK jwk = new RSAKey.Builder(this.key).privateKey(this.priv).build();
        JWKSource<SecurityContext> jwks = new ImmutableJWKSet<>(new JWKSet(jwk));
        return new NimbusJwtEncoder(jwks);
    }
    
    /**
     * JWT認證解碼時，去掉Spring Security對許可權附帶的預設字首SCOOP_
     */
    @Bean
    JwtAuthenticationConverter JwtAuthenticationConverter() {
        final JwtGrantedAuthoritiesConverter jwtGrantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
        jwtGrantedAuthoritiesConverter.setAuthorityPrefix("");
        final JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
        jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(jwtGrantedAuthoritiesConverter);
        return jwtAuthenticationConverter;
    }
}

application.yml

jwt:
  private.key: classpath:app.key
  public.key: classpath:app.pub

上邊的設定需要在Spring Boot專案的Resource目錄下生成一對RSA祕鑰。
可以使用下面的網站進行生成：http://tools.jb51.net/password/rsa_encode/，注意：金鑰格式使用 PKCS#8，私鑰密碼為空。

還有一點需要說明，我在程式碼中使用了Spring Boot的值注入：

@Value("${jwt.public.key}")
 private RSAPublicKey key; 
@Value("${jwt.private.key}")
private RSAPrivateKey priv;

有沒有很好奇Spring Boot是如何將yaml檔案中的字串對應的檔案轉換為RSAPublicKey和RSAPrivateKey ？
其實是Spring Security幫我們做了處理，在Spring Security中幫我們實現了一個轉換器ResourceKeyConverterAdapter，具體可以閱讀相關原始碼來更深入的瞭解。

至此我們的專案已經支援JWT認證了。
但是使用者需要在請求頭Authorization中攜帶合法的JWT才能通過認證，進而存取伺服器資源，那麼如何給使用者頒發一個合法的JWT呢？
很簡單，可以提供一個登入介面，讓使用者輸入使用者名稱和密碼，匹配成功後頒發令牌即可。

其實並不是必須這樣做，還有其他方式，比如我們呼叫第三方介面，我們經常的做法是先去第三方申請，申請通過後我們就可以得到一個令牌。這個過程和上面的登入通過後頒發一個令牌是一樣的，都是通過合法的途徑獲得一個令牌！

5. 實現登入介面

登入介面只有一個目的，就是給合法使用者頒發令牌！
登入API介面：

@RestController
public class SysLoginController {
    private final SysLoginService sysLoginService;

    public SysLoginController(SysLoginService sysLoginService) {
        this.sysLoginService = sysLoginService;
    }

    @PostMapping("/login")
    public String login(@RequestBody LoginInfo loginInfo) {
        return sysLoginService.login(loginInfo);
    }
}

登入邏輯實現：

@Service
public class SysLoginService {
    private final JwtEncoder jwtEncoder;
    private final SpringSecurityUserDetailsService springSecurityUserDetailsService;

    public SysLoginService(JwtEncoder jwtEncoder, SpringSecurityUserDetailsService springSecurityUserDetailsService) {
        this.jwtEncoder = jwtEncoder;
        this.springSecurityUserDetailsService = springSecurityUserDetailsService;
    }

    public String login(LoginInfo loginInfo) {
        //從使用者資訊儲存庫中獲取使用者資訊
        final UserDetails userDetails = springSecurityUserDetailsService.loadUserByUsername(loginInfo.getUsername());
        final String password = userDetails.getPassword();
        //匹配密碼，匹配成功生成JWT令牌
        if (password.equals(loginInfo.getPassword())) {
            return generateToken(userDetails);
        }
        //密碼不匹配，丟擲異常，Spring Security發現丟擲該異常後會將http響應狀態碼設定為401 unauthorized
        throw new BadCredentialsException("密碼錯誤！");
    }

    private String generateToken(UserDetails userDetails) {
        Instant now = Instant.now();
        //JWT過期時間為36000秒，也就是600分鐘，10小時
        long expiry = 36000L;
        String scope = userDetails.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority)
                .collect(Collectors.joining(" "));
         //將使用者許可權資訊使用空格分割拼為字串，放到JWT的payload的scope欄位中，注意不要改變scope這個屬性，這是Spring Security OAuth2 JWT預設處理方式，在JWT解碼時需要讀取該欄位，轉為使用者的許可權資訊！
        JwtClaimsSet claims = JwtClaimsSet.builder()
                .issuer("self")
                .issuedAt(now)
                .expiresAt(now.plusSeconds(expiry))
                .subject(userDetails.getUsername())
                .claim("scope", scope)
                .build();
        return this.jwtEncoder.encode(JwtEncoderParameters.from(claims)).getTokenValue();
    }
}

其他非核心程式碼這裡就不貼出來了，我將程式碼放到github上了，具體可以轉到https://github.com/cloudgyb/spring-security-study-jwt。

6. 測試

使用postman測試一下：
使用錯誤的密碼，會返回401 Unauthorized的狀態碼，表示我們認證失敗!

使用正確的使用者名稱和密碼：

返回了JWT令牌。

此時使用者端拿到了合法的令牌，接下來就可以存取伺服器上有權存取的資源了。
我寫了一個測試介面：

@RestController
public class HelloController {

    @GetMapping("/")
    @PreAuthorize("hasAuthority('test')")
    public String hello(Authentication authentication) {
        return "Hello, " + authentication.getName() + "!";
    }
}

該介面需要使用者擁有"test"的許可權，但是登入使用者沒有該許可權（只有一個app的許可權），此時呼叫該介面：
首先將上一步登入獲得的令牌貼上到token中：

我們傳送請求得到了403 Forbidden的響應，意思就是我們沒有存取許可權，此時我們將介面許可權改為“app”:

@RestController
public class HelloController {

    @GetMapping("/")
    @PreAuthorize("hasAuthority('app')")
    public String hello(Authentication authentication) {
        return "Hello, " + authentication.getName() + "!";
    }
}

重啟專案。再次發起請求：