OAuth2 Developers Guide (Spring 공식 홈페이지)

소개

 이 가이드는 OAuth 2.0을 지원하며 OAuth1.0과는 완전히 다르다

이 가이드는 총 2 파트(OAuth 2.0 provider/OAuth 2.0 client)로 나눠진다. 이 두 파트를 위해 다음과 같은 샘플이 준비되어있다. (integration tests, sample apps -> 깃헙에 있다)

https://github.com/spring-projects/spring-security-oauth/tree/master/tests/annotation

spring-projects/spring-security-oauth

https://github.com/spring-projects/spring-security-oauth/tree/master/samples/oauth2

spring-projects/spring-security-oauth

---

OAuth 2.0 Provider

 OAuth 2.0 provider 메커니즘은 OAuth 2.0 보호된 자원의 노출을 담당한다. 이 구성은 사용자를 대신하여 보호된 자원에 접근할 수 있는 OAuth 2.0 client를 설정하는 것을 포함한다. OAuth 2.0 provider는 보호된 리소스에 접근하는 데 사용되는 OAuth 2.0 토큰을 관리하고 확인함으로써 이를 수행한다. 해당되는 경우, provider는 client가 보호된 자원(즉, 확인 페이지)에 대한 접근을 허가할 수 있는지 확인하기 위한 인터페이스를 제공해야 한다.

 

---

OAuth 2.0 Provider Implementation(구현)

 OAuth 2.0의 provider 역할은 실제로 Authorization Service와 Resource Service로 분할되며, 이러한 역할들이 동일한 애플리케이션에 상주하는 경우도 있지만, Spring Security OAuth를 사용하면 두 애플리케이션으로 분할할 수 있으며, 또한 인증 서비스를 공유하는 여러 개의 리소스 서비스를 가질 수 있다.

 토큰에 대한 요청은 스프링 MVC 컨트롤러 엔드포인트에서 처리되며, 보호된 리소스에 대한 접근은 표준 스프링 보안 요청 필터로 처리된다. OAuth 2.0 Authorization Server를 구현하려면 Spring Security 필터 체인에 다음과 같은 엔드포인트가 필요하다

 

• AuthorizationEndpoint는 승인 요청을 처리하는 데 사용된다. 기본 URL: /oauth/authorization

• TokenEndpoint는 액세스 토큰 요청을 처리하는 데 사용된다. 기본 URL: /oauth/token

 

OAuth 2.0 Resource Service를 구현하려면 다음과 같은 필터가 필요하다.

 

• OAuth2AuthenticationProcessingFilter는 인증된 액세스 토큰이 주어진 요청에 대한 인증을 로드하는데 사용된다.

모든 OAuth 2.0 provider 기능에 대해 특수 Spring OAuth @Configuration 어댑터를 사용하여 구성을 단순화한다.

 

---

Authorization Server Configuration (인증 서버 구성)

 Authorization Server를 구성할 때 Client가 최종 사용자로부터 액세스 토큰(예: authorization code, user credentials, refresh token)을 가져오는 데 사용할 권한 유형을 고려해야 한다. 서버의 구성은 클라이언트 상세 서비스(client detail service) 및 토큰 서비스(token service)의 구현을 제공하고 메커니즘의 특정 측면을 전체적으로 활성화 또는 비활성화하는 데 사용된다.

 그러나 각 클라이언트는 특정 승인 메커니즘과 액세스 권한을 사용할 수 있는 사용 권한을 가지고 구체적으로 구성할 수 있다는 점에 유의하십시오. 즉, 공급자가 "클라이언트 자격 증명" 부여 유형을 지원하도록 구성되어 있다고 해서, 특정 클라이언트가 해당 허가 유형을 사용하도록 허가받았다는 것을 의미하지는 않는다.

 

 @EnableAuthorizationServer 주석을 사용하여 AuthorizationServerConfigurer을 구현하는 @Beans와 함께 OAuth 2.0 Authorization Server 메커니즘을 구성한다(빈 메소드로 편리한 어댑터 구현이 있음). 다음 기능은 스프링에 의해 생성되어 AuthorizationServerConfigurer에 전달되는 별도의 구성자에게 위임된다.

 

• ClientDetailsServiceConfigurer: 클라이언트 상세 내역 서비스를 정의하는 구성자. 클라이언트 세부 정보를 초기화하거나 기존 스토어를 참조할 수 있다.
• AuthorizationServerSecurityConfigurer: 토큰 엔드포인트의 보안 제약 조건을 정의하십시오.
• AuthorizationServerEndpointsConfigurer: 권한 및 토큰 끝점 및 토큰 서비스를 정의하십시오.

 제공자 구성의 중요한 측면은 인증 코드(authorization code)가 OAuth 클라이언트에 공급되는 방법이다(authorization code grant 방식일 때). OAuth 클라이언트가 최종 사용자(user)를 인증 페이지(인증서버의 로그인 페이지)로 안내하여 인증 코드(authorization code)를 획득하고, 최종 사용자(user)가 인증 정보를 입력할 수 있는 권한 부여 페이지로 이동함으로써, 공급자 인증 서버에서 인증 코드를 가진 OAuth 클라이언트로 다시 리디렉션하게 된다.

 (요약 - user를 통해서 Client가 Authorization Server로부터 Authorizatino code를 발급받았다는 뜻)

 

이에 대한 예는 OAuth 2 규격에 자세히 설명되어 있다.
XML에는 OAuth 2.0 Authorization Server를 구성하는 것과 유사한 방법으로 사용되는 <auth-server/> 요소가 있다.

 

---

 

Configuring Client Details

 ClientDetailsServiceConfigurer (AuthorizationServerConfigurer의 콜백)을 사용하여 클라이언트 세부 정보 서비스의 메모리 내 또는 JDBC 구현을 정의할 수 있다. 클라이언트의 중요한 속성은 다음과 같다.

 

• clientId: (필수) 클라이언트 ID.

• secret: (신뢰할 수 있는 클라이언트에 필요한) 클라이언트 secret (있는 경우)

• scope: 클라이언트가 제한된 범위. scope가 정의되지 않았거나 비어 있는 경우(기본값) 클라이언트는 스코프에 의해 제한되지 않는다.

• authorizedGrantTypes: 클라이언트가 사용하도록 승인된 유형. 기본값이 비어 있음

• authorities: client에게 부여된 authorities

 실행 중인 애플리케이션에서 기본 스토어에 직접 액세스(예: JdbcClientDetailsService의 경우 데이터베이스 테이블)하거나 ClientDetailsManager 인터페이스를 통해 클라이언트 세부 정보를 업데이트할 수 있다.

 참고: JDBC 서비스의 스키마는 라이브러리와 함께 패키징되지 않지만(실제로 사용하고 싶은 변형이 너무 많기 때문), github의 테스트 코드에서 시작할 수 있는 예가 있다.

https://github.com/spring-projects/spring-security-oauth/blob/master/spring-security-oauth2/src/test/resources/schema.sql

spring-projects/spring-security-oauth

---

Managing Tokens

 AuthorizationServerTokenServices 인터페이스는 OAuth 2.0 토큰 관리에 필요한 작업을 정의한다. 

 

• 액세스 토큰이 생성되면 액세스 토큰을 수락하는 리소스가 나중에 참조할 수 있도록 인증이 저장돼야 한다.
• 액세스 토큰은 생성 권한을 부여하기 위해 사용된 인증을 로드하는 데 사용된다.

 AuthorizationServerTokenServices 구현을 생성할 때 액세스 토큰의 형식과 저장을 변경하기 위해 연결할 수 있는 많은 전략을 가진 DefaultTokenServices을 고려해 보십시오.

 기본적으로 임의의 값을 통해 토큰을 생성하고 토큰을 TokenStore에 위임하는 토큰의 지속성을 제외한 모든 것을 처리한다. 기본적인 저장방법은 메모리 내 구현이지만 다른 구현도 있다. 여기 각각에 대한 설명이 있다.

 

• 기본 InMemoryTokenStore는 단일 서버(즉, 트래픽이 적으며 장애 발생 시 백업 서버로 핫 스왑 없음)에 대해 완벽하게 괜찮다. 대부분의 프로젝트는 여기서 시작할 수 있고, 어쩌면 이런 식으로 개발 모드로 운영되어 종속성이 없는 서버를 쉽게 시작할 수 있다.

 

• JdbcTokenStore는 동일한 것의 JDBC 버전으로, 관계형 데이터베이스에 토큰 데이터를 저장한다. 서버 간에 데이터베이스를 공유할 수 있는 경우 JDBC 버전을 사용하거나, 하나만 있는 경우 동일한 서버의 인스턴스를 확장하거나, 여러 구성 요소가 있는 경우 인증 및 리소스 서버를 사용하십시오. JdbcTokenStore를 사용하려면 클래스 경로에 "spring-jdbc"가 필요하다.

 

• JSON Web Token(JWT) 버전은 승인에 대한 모든 데이터를 토큰 자체로 인코딩한다(따라서 백엔드 서버가 전혀 필요없고 이것이 바로 가장 큰 장점이다). 한 가지 단점은 액세스 토큰을 쉽게 해지할 수 없기 때문에 일반적으로 짧은 기간 동안 부여되며 해지 처리 시 새로 고침 토큰으로 처리된다. 또 다른 단점은 토큰에 사용자 자격 증명 정보를 많이 저장할 경우 토큰이 상당히 커질 수 있다는 것이다. JwtTokenStore는 데이터를 유지하지 않는다는 점에서 실제로 "스토어"는 아니지만, DefaultTokenService에서 토큰 값과 인증 정보를 변환하는 것과 같은 동일한 역할을 한다

---

JWT Tokens

 JWT 토큰을 사용하려면 권한 부여 서버에 JwtTokenStore가 필요하다. 또한 JwtTokenStore가 JwtAccessTokenConverter에 의존할 수 있도록 리소스 서버도 토큰을 디코딩할 수 있어야한다. 그리고 인증 서버와 리소스 서버 둘 다에서 동일한 구현이 필요하다. 토큰은 기본적으로 서명되며, 리소스 서버도 서명을 확인할 수 있어야 하므로 인증 서버(공유 비밀 또는 대칭 키)와 같은 대칭(수명 키) 키가 필요하거나, 인증 서버(공인 또는 개인 키)의 개인 키(수명 키)와 일치하는 공용 키(수명 키)가 필요하다. 비대칭 키).

 공용 키(사용 가능한 경우)는 권한 부여 서버에 의해 /oauth/token_key endpoint에 노출되며, 기본적으로 액세스 규칙 "denyAll()"로 보안된다. 표준 SpEL 식을 AuthorizationServerSecurityConfigurer에 주입하면 열 수 있다(예: 공용 키이므로 "permitAll()"이 적합할 수 있음).

 JwtTokenStore를 사용하려면 클래스 경로에 "spring-security-jwt"가 있어야 한다(Spring OAuth와 동일한 gitub 저장소에서 찾을 수 있지만 릴리즈 주기는 다름).

 

---

Grant Types

 AuthorizationEndpoint에서 지원하는t승인 유형은 AuthorizationServerEndpointsConfigurer을 통해 구성할 수 있다. 기본적으로 암호를 제외한 모든 승인 유형이 지원된다(아래에서 암호를 설정하는 방법에 대한 자세한 내용은 참조). 다음 속성은 승인 유형에 영향을 미친다.

 

• AuthenticationManager: 비밀번호 부여는 AuthenticationManager를 주입하여 켜진다.

• userDetailsService: UserDetailsService를 주입하거나 UserDetailsService를 전체적으로 구성한 경우(예: GlobalAuthenticationManagerConfigr) 새로 고침 토큰 부여에 사용자 세부 정보에 대한 검사가 포함되어 계정이 여전히 활성 상태인지 확인

• authorizationCodeServices: 인증 코드 부여에 대한 인증 코드 서비스(AuthorizationCodeServices의 인스턴스)를 정의한다.

• implictGrantService: Implicit 부여 기간 동안 상태 관리

• TokenGranter: TokenGranter(위의 다른 속성을 무시하고 부여를 완전히 제어)

XML에서 부여 유형은 권한 부여 서버의 하위 요소로 포함된다.

 

---

Configuring the Endpoint URLS
 AuthorizationServerEndpointsConfigurer에는 pathMapping() 메서드가 있다. 두 가지 주장이 필요하다.

• The default (framework implementation) URL path for the endpoint

• The custom path required (starting with a "/")

프레임워크가 제공하는 URL 경로는

• /oauth/authorize (the authorization endpoint), 
• /oauth/token (the token endpoint), 
• /oauth/confirm_access (user posts approval for grants here),
• /oauth/error (used to render errors in the authorization server), 
• /oauth/check_token (used by Resource Servers to decode access tokens)
• /oauth/token_key (exposes public key for token verification if using JWT tokens).

 Authorization endpoint /oauth/authorize는 인증된 사용자에게만 접근 가능하도록 Spring Security를 이용해 보호되어야 한다. 다음 예시는 표준 Spring Security WebSecurityConfigurer을 이용하고 있다

@Override
    protected void configure(HttpSecurity http) throws Exception {
        http
            .authorizeRequests().antMatchers("/login").permitAll().and()
        // default protection for all resources (including /oauth/authorize)
            .authorizeRequests()
                .anyRequest().hasRole("USER")
        // ... more configuration, e.g. for form login
    }

참고: 인증 서버가 리소스 서버인 경우 API 리소스를 제어하는 우선 순위가 낮은 다른 보안 필터 체인이 있을 수 있다. 액세스 토큰에 의해 보호되어야 하는 요청을 주 사용자 대면 필터 체인의 경로와 일치시키지 않도록 하십시오. 위의 WebSecurityConfigurer에서 비API 리소스만 선택하는 요청 matcher를 포함하십시오.

Token Endpoint은 기본적으로 클라이언트 비밀의 HTTP Basic 인증을 사용하는 @Configuration 지원에서 Spring OAuth에 의해 보호된다. XML의 경우는 그렇지 않으므로 명시적으로 보호해야 한다.

XML에서 <authorization-server/> 요소는 유사한 방법으로 기본 엔드포인트 URL을 변경하는 데 사용할 수 있는 몇 가지 속성을 가지고 있다. /check_token endpoint을 명시적으로 사용하도록 설정해야 함(check-token 사용 속성 포함).

 

---