📒OAuth2 로그인

Google의 OAuth 2.0 인증 시스템을 로그인에 사용하려면 Google API 콘솔에서 프로젝트를 설정하여 OAuth 2.0 credentials(클라이언트 ID와 Secret)을 얻어야 함

Google OAuth 2.0은 OIDC 스펙을 준수하고 있으며, Open ID 인증을 받음

Redirect URI는 기본적으로 {baseUrl}/login/oauth2/code/{registrationId} 로 정해져있음

인증 흐름에 생성한 OAuth 클라이언트를 사용하기 위해 application.yml 파일에 프로퍼티 설정을 해줘야 함

사용자가 Google 인증을 완료하면 사용자는 Oauth 클라이언트에 접근 권한을 부여하고, OAuth 클라이언트는 UserInfo Endpoint에서 이메일 주소와 기본 프로필 정보 등을 가져와 인증된 세션을 설정함

✔️CommonOAuth2Provider

CommonOAuth2Provider는 Google, GitHub, Facebook, Okta와 같은 잘 알려진 제공자들에 대한 기본 클라이언트 속성을 미리 정의해 놓았음.

예를 들어, 제공자의 authorization-uri, token-uri, user-info-uri는 자주 변경되지 않기 때문에 기본 값을 제공하여 필요한 설정을 줄일 수 있음.

이로 인해, Google 클라이언트를 설정할 때, client-id와 client-secret 속성만 가지고 Google OAuth 클라이언트를 사용할 수 있음.

spring:
  security:
    oauth2:
      client:
        registration:
          google:
            client-id: google-client-id
            client-secret: google-client-secret

OAuth 클라이언트 속성의 자동 기본값 설정은 registrationId(google)가 CommonOAuth2Provider에서 GOOGLE 열거형(대소문자 구분 없음)과 일치하기 때문에 잘 동작한다.

registrationId를 다르게 지정하고 싶은 경우에도, provider 속성에 어떤 제공자의 설정을 참조하도록 할지 설정하여, OAuth 클라이언트 속성의 자동 기본값 설정을 그대로 사용할 수 있도록 할 수 있다.

spring:
  security:
    oauth2:
      client:
        registration:
          google-login:	
            provider: google	
            client-id: google-client-id
            client-secret: google-client-secret

registrationId는 google-login으로 설정되어 있다.

provider 속성은 google로 설정되어 있으며, 이를 통해 CommonOAuth2Provider.GOOGLE.getBuilder()에서 설정된 클라이언트 속성의 자동 기본값을 사용할 수 있다.

✔️Configuring Custom Provider Properties

OAuth 클라이언트 자동 구성 클래스는 OAuth2ClientAutoConfiguration이다.

자동 구성 클래스에서 하는 일은

1. 구성된 OAuth 클라이언트 속성에서 ClientRegistration(들)을 구성하여 ClientRegistrationRepository를 @Bean으로 등록
2. SecurityFilterChain을 @Bean으로 등록하고, httpSecurity.oauth2Login()을 통해 OAuth 2.0 로그인을 활성화합니다.

자동 구성을 재정의 하려면

1. ClientRegistrationRepository를 @Bean으로 등록
2. SecurityFilterChain을 @Bean으로 등록
3. 자동 구성을 완전히 재정의

위 방법으로 재정의가 가능하다.

보통은 2번 방법을 사용해서 인증 로직을 커스텀하는 것 같다.

✔️HttpSecurity.oauth2Login()

HttpSecurity.oauth2Login()은 OAuth2 로그인을 커스텀하기 위한 다양한 구성 옵션을 제공한다.

주요 구성 옵션은 프로토콜 엔드포인트에 해당하는 그룹으로 나뉜다.

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Login(oauth2 -> oauth2
                .authorizationEndpoint(authorization -> authorization
                        ...
                )
                .redirectionEndpoint(redirection -> redirection
                        ...
                )
                .tokenEndpoint(token -> token
                        ...
                )
                .userInfoEndpoint(userInfo -> userInfo
                        ...
                )
            );
        return http.build();
    }
}

📌엔드포인트

👉Authorization EndPoint

OAuth 클라이언트가 사용자를 로그인 페이지로 보내서 권한을 부여받는 데 사용하는 엔드포인트다.

사용자는 여기서 로그인하고, 클라이언트가 요청한 접근 권한을 승인한다. 그런 다음, 인증이 완료되면 Redirection URL로 이동하게 된다.

authorizationEndpoint의 baseUri() 메소드로 authorization endpoint의 기본 경로를 바꿀 수 있다.

기본 경로는 OAuth2AuthorizationRequestRedirectFilter.DEFAULT_AUTHORIZATION_REQUEST_BASE_URI + "/{registrationId}" 로 지정되어 있다.

이 값의 기본값은 /oauth2/authorization이고,

{registrationId}는 등록한 각 OAuth 클라이언트(예: google, github 등)의 고유 식별자를 말한다.

예를 들어, Google OAuth 클라이언트를 등록했으면 이 값은 "google"이 된다.

👉Token Endpoint:

클라이언트가 권한 부여 코드를 액세스 토큰으로 교환하기 위해, 일반적으로 클라이언트 인증을 통해 사용하는 엔드포인트다.

👉Redirection Endpoint:

인증 서버가 리소스 소유자(사용자) 사용자 에이전트(브라우저)를 통해 클라이언트에게 인증 자격을 포함한 응답을 반환하는 데 사용하는 엔드포인트다.

OAuth 2.0 로그인은 Authorization Code Grant 방식을 활용하므로, 인증 자격 증명은 Authorization Code다.

기본적으로 Authorization Response의 baseUri(리디렉션 엔드포인트)는 /login/oauth2/code/{registrationId}이며, 이는 OAuth2LoginAuthenticationFilter.DEFAULT_FILTER_PROCESSES_URI에 정의되어 있다.

Authorization Response baseUri를 커스터마이징하려면 다음과 같이 설정할 수 있다.

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Login(oauth2 -> oauth2
                .redirectionEndpoint(redirection -> redirection
                    .baseUri("/login/oauth2/callback/*")  // 커스텀 엔드포인트 설정
                    ...
                )
            );
        return http.build();
    }
}

Authorization Respoinse BaseUri를 커스텀 했다면, ClientRegistration.redirectUri가 커스터마이징된 Authorization Response baseUri와 일치하는지도 확인해야 한다.

👉UserInfo Endpoint:

OpenID Connect Core 1.0 사양에서 UserInfo Endpoint를 다음과 같이 정의하고 있다

UserInfo 엔드포인트는 인증된 최종 사용자에 대한 클레임(Claims)을 반환하는 OAuth 2.0 보호 리소스로,

인증된 최종 사용자에 대한 클레임을 반환하는 OAuth 2.0 보호 리소스로, 클라이언트는 OpenID Connect 인증을 통해 얻은 액세스 토큰을 사용하여 UserInfo Endpoint에 요청을 보낸다.

이 클레임은 일반적으로 클레임에 대한 이름-값 쌍 컬렉션을 포함하는 JSON 객체로 표현된다.

UserInfo 엔드포인트와의 통신은 반드시 TLS를 사용해야 한다.(섹션 16.17을 참조)

UserInfo 엔드포인트는 반드시 RFC 7231 [RFC7231]에 정의된 HTTP GET 및 HTTP POST 메서드를 지원해야 합니다.
UserInfo 엔드포인트는 반드시 OAuth 2.0 베어러 토큰 사용법 [RFC6750]에 따라 액세스 토큰을 받아들여야 합니다.
UserInfo 엔드포인트는 자바스크립트 클라이언트와 기타 브라우저 기반 클라이언트가 접근할 수 있도록 CORS [CORS] 또는 기타 적절한 방법을 지원하는 것이 좋습니다.

UserInfo 엔드포인트는 다음 하위 섹션에서 설명된 여러 구성 옵션을 포함하고 있다.

• 사용자 권한 매핑 (Mapping User Authorities)
• OAuth 2.0 UserService
• OpenID Connect 1.0 UserService

✔️OAuth 2.0 UserService

DefaultOAuth2UserService는 표준 OAuth 2.0 제공자(Provider)를 지원하는 OAuth2UserService의 구현체다.

OAuth2UserService는 UserInfo 엔드포인트에서 최종 사용자(리소스 소유자)의 속성을 받아온다.(이때 클라이언트가 인증 흐름 중에 부여받은 액세스 토큰을 사용한다.) 그리고 그 결과로 OAuth2User 형태의 AuthenticatedPrincipal을 반환한다.

DefaultOAuth2UserService는 UserInfo 엔드포인트에 요청할 때 RestOperations(인터페이스) 인스턴스를 사용한다.

DefaultOAuth2UserService를 커스터마이징하거나 OAuth2UserService의 자체 구현을 제공하는 경우, 다음과 같이 구성해야 한다.

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Login(oauth2 -> oauth2
                .userInfoEndpoint(userInfo -> userInfo
                    .userService(this.oauth2UserService())
                    ...
                )
            );
        return http.build();
    }

    private OAuth2UserService<OAuth2UserRequest, OAuth2User> oauth2UserService() {
        ...
    }
}

OidcUserService 자체 구현을 제공하려면 다음과 같이 구성해야 한다.

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Login(oauth2 -> oauth2
                .userInfoEndpoint(userInfo -> userInfo
                    .oidcUserService(this.oidcUserService())
                    ...
                )
            );
        return http.build();
    }

    private OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
        ...
    }
}

📌OAuth2 로그인 구성 옵션

다음 코드는 oauth2Login() DSL에서 사용할 수 있는 전체 구성 옵션이다. 참고만 하면 될 것 같다. 물론 DSL외에도 xml 설정으로도 가능하다. 굳이 살펴보진 않았다.

@Configuration
@EnableWebSecurity
public class OAuth2LoginSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .oauth2Login(oauth2 -> oauth2
                .clientRegistrationRepository(this.clientRegistrationRepository())
                .authorizedClientRepository(this.authorizedClientRepository())
                .authorizedClientService(this.authorizedClientService())
                .loginPage("/login")
                .authorizationEndpoint(authorization -> authorization
                    .baseUri(this.authorizationRequestBaseUri())
                    .authorizationRequestRepository(this.authorizationRequestRepository())
                    .authorizationRequestResolver(this.authorizationRequestResolver())
                )
                .redirectionEndpoint(redirection -> redirection
                    .baseUri(this.authorizationResponseBaseUri())
                )
                .tokenEndpoint(token -> token
                    .accessTokenResponseClient(this.accessTokenResponseClient())
                )
                .userInfoEndpoint(userInfo -> userInfo
                    .userAuthoritiesMapper(this.userAuthoritiesMapper())
                    .userService(this.oauth2UserService())
                    .oidcUserService(this.oidcUserService())
                )
            );
        return http.build();
    }
}

📌OAuth 2.0 Login Page

Spring Security는 OAuth2 인증을 위한 기본페이지를 구성하고 있다. loginPage() api를 통해 로그인 페이지 경로 설정이 가능하다.

OAuth2 로그인 페이지는 DefaultLoginPageGeneratingFilter에 의해 자동으로 생성된다.

프론트가 따로 구성되어 있다면, 로그인 페이지 설정은 빼도 된다.

로그인 페이지 설정을 빼도 기본 로그인 페이지는 제공되며 기본 경로는 "/login" 경로가 된다. 프론트가 따로 구성되어 있다면, 해당 경로에 접근하지 못하도록 설정할 필요도 있을 것 같다.

📒핵심 인터페이스와 클래스들

✔️ClientRegistration

ClientRegistration은 OAuth 2.0 또는 OpenID Connect 1.0 공급자와 등록된 클라이언트를 나타낸다.

ClientRegistration 객체는 클라이언트 ID, 클라이언트 secret, 인증 부여 방식, 리디렉션 URI, 스코프(scope), 인증 URI, 토큰 URI 및 기타 세부 정보를 포함하는 정보를 가지고 있다.

ClientRegistration 및 그 속성들은 다음과 같이 정의되어 있다.

public final class ClientRegistration {
	private String registrationId;	
	private String clientId;	
	private String clientSecret;	
	private ClientAuthenticationMethod clientAuthenticationMethod;	
	private AuthorizationGrantType authorizationGrantType;	
	private String redirectUri;	
	private Set<String> scopes;	
	private ProviderDetails providerDetails;
	private String clientName;	

	public class ProviderDetails {
		private String authorizationUri;	
		private String tokenUri;	
		private UserInfoEndpoint userInfoEndpoint;
		private String jwkSetUri;	
		private String issuerUri;	
        private Map<String, Object> configurationMetadata;  

		public class UserInfoEndpoint {
			private String uri;	
            private AuthenticationMethod authenticationMethod;  
			private String userNameAttributeName;	
		}
	}
}

공식문서 참조

✔️ClientRegistrationRepository

ClientRegistrationRepository는 OAuth 2.0 / OpenID Connect 1.0의 ClientRegistration 정보를 관리하는 저장소 역할을 한다.

클라이언트 등록 정보는 궁극적으로 관련된 인증 서버(Authorization Server)에 저장되고 소유됩니다. 이 저장소는 인증 서버에 저장된 기본 클라이언트 등록 정보 중 일부를 검색할 수 있는 기능을 제공합니다.

Spring Boot 자동 설정은 spring.security.oauth2.client.registration.[registrationId] 속성 아래에 있는 각각의 프로퍼티들을 ClientRegistration 인스턴스로 바인딩하고, 각각의 ClientRegistration 인스턴스를 ClientRegistrationRepository 내에 구성합니다.

ClientRegistrationRepository의 기본 구현체는 InMemoryClientRegistrationRepository입니다.

자동 설정은 또한 ClientRegistrationRepository를 @Bean으로 ApplicationContext에 등록하여 애플리케이션에서 필요 시 의존성 주입으로 사용할 수 있도록 합니다.

다음은 예시입니다:

@Controller
public class OAuth2ClientController {

	@Autowired
	private ClientRegistrationRepository clientRegistrationRepository;

	@GetMapping("/")
	public String index() {
		ClientRegistration oktaRegistration =
			this.clientRegistrationRepository.findByRegistrationId("okta");

		...

		return "index";
	}
}

✔️OAuth2AuthorizedClient

OAuth2AuthorizedClient는 승인된 클라이언트를 나타냅니다. 클라이언트가 승인되었다고 간주되는 경우는 최종 사용자(리소스 소유자)가 클라이언트에게 보호된 리소스에 접근할 수 있도록 권한을 부여했을 때입니다.

OAuth2AuthorizedClient는 OAuth2AccessToken(및 선택적으로 OAuth2RefreshToken)을 ClientRegistration(클라이언트)과 권한을 부여한 최종 사용자(Principal)에게 연결하는 역할을 합니다.

OAuth2AuthorizedClientRepository와 OAuth2AuthorizedClientService
OAuth2AuthorizedClientRepository는 웹 요청 간에 OAuth2AuthorizedClient를 저장하는 역할을 담당하며, OAuth2AuthorizedClientService는 애플리케이션 수준에서 OAuth2AuthorizedClient를 관리하는 주요 역할을 합니다.

개발자 관점에서 OAuth2AuthorizedClientRepository 또는 OAuth2AuthorizedClientService는 클라이언트와 연결된 OAuth2AccessToken을 조회하는 기능을 제공하여 보호된 리소스 요청을 시작할 수 있도록 합니다.

다음은 예시입니다:

@Controller
public class OAuth2ClientController {

    @Autowired
    private OAuth2AuthorizedClientService authorizedClientService;

    @GetMapping("/")
    public String index(Authentication authentication) {
        OAuth2AuthorizedClient authorizedClient =
            this.authorizedClientService.loadAuthorizedClient("okta", authentication.getName());

        OAuth2AccessToken accessToken = authorizedClient.getAccessToken();

        ...

        return "index";
    }
}

Spring Boot 자동 설정은 OAuth2AuthorizedClientRepository 또는 OAuth2AuthorizedClientService를 @Bean으로 ApplicationContext에 등록합니다. 하지만 애플리케이션은 필요에 따라 커스텀 OAuth2AuthorizedClientRepository 또는 OAuth2AuthorizedClientService를 @Bean으로 등록하여 기본 설정을 덮어쓸 수 있습니다.

OAuth2AuthorizedClientService의 기본 구현은 InMemoryOAuth2AuthorizedClientService이며, 이는 OAuth2AuthorizedClient 객체를 메모리에 저장합니다.

대안으로, JdbcOAuth2AuthorizedClientService를 설정하여 OAuth2AuthorizedClient 인스턴스를 데이터베이스에 저장할 수 있습니다.

JdbcOAuth2AuthorizedClientService는 OAuth 2.0 클라이언트 스키마에서 설명된 테이블 정의에 의존합니다.