인증

개요

Contexa Identity는 4가지 인증 방법을 제공합니다. 각 방법은 독립적인 SecurityFilterChain을 생성하며, 우선순위는 order()를 통해 제어됩니다.

모든 인증 방법은 rawHttp()를 통해 전체 Spring Security API에 접근할 수 있으며, 공통 옵션(order, CSRF, CORS, 헤더, 로그아웃 등)을 지원합니다.

Form Login

기존 웹 폼 기반 로그인입니다. DSL을 통해 Spring Security의 formLogin()을 설정합니다. 기본 order는 100입니다.

전체 옵션

기본 설정

registry
    .form(form -> form
        .loginPage("/login")
        .defaultSuccessUrl("/home")
        .failureUrl("/login?error")
        .permitAll()
    )
    .session(Customizer.withDefaults())
    .build();

커스텀 핸들러

registry
    .form(form -> form
        .loginPage("/login")
        .usernameParameter("email")
        .passwordParameter("passwd")
        .successHandler(customSuccessHandler)
        .failureHandler(customFailureHandler)
    )
    .session(Customizer.withDefaults())
    .build();

고급 설정 (rawHttp + rawFormLogin)

registry
    .form(form -> form
        .order(20)
        .loginPage("/admin/login")
        .rawFormLogin(formLogin -> formLogin
            .usernameParameter("admin_user")
            .passwordParameter("admin_pass"))
        .rawHttp(http -> http
            .securityMatcher("/admin/**")
            .sessionManagement(session -> session
                .maximumSessions(1)
                .maxSessionsPreventsLogin(true)))
    )
    .session(Customizer.withDefaults())
    .build();

REST API 인증

JSON 기반 REST API 인증입니다. SPA와 모바일 앱 같은 프론트엔드 클라이언트에서 JSON 페이로드로 인증합니다. 기본 order는 200입니다.

전체 옵션

기본 설정

registry
    .rest(rest -> rest
        .loginProcessingUrl("/api/auth/login")
    )
    .oauth2(Customizer.withDefaults())
    .build();

Stateless API 설정 (rawHttp)

registry
    .rest(rest -> rest
        .order(50)
        .loginProcessingUrl("/api/auth")
        .rawHttp(http -> http
            .securityMatcher("/api/**")
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)))
    )
    .oauth2(Customizer.withDefaults())
    .build();

One-Time Token (매직 링크)

이메일 또는 SMS로 전송되는 일회용 토큰을 통한 인증입니다. 매직 링크 방식의 비밀번호 없는 인증입니다. 기본 order는 300입니다.

전체 옵션

기본 설정

registry
    .ott(ott -> ott
        .tokenService(customTokenService)
        .tokenGenerationSuccessHandler(emailSendingHandler)
    )
    .session(Customizer.withDefaults())
    .build();

커스텀 페이지 + 이메일 발송 핸들러

registry
    .ott(ott -> ott
        .tokenGeneratingUrl("/auth/magic-link/request")
        .defaultSubmitPageUrl("/auth/magic-link/verify")
        // 현재 공개 OTT DSL은 기본 token 파라미터 이름("token")을 사용합니다.
        .showDefaultSubmitPage(false)
        .tokenService(jpaOneTimeTokenService)
        .tokenGenerationSuccessHandler((request, response, token) -> {
            String email = request.getParameter("username");
            emailService.sendMagicLink(email, token.getTokenValue());
            response.sendRedirect("/auth/magic-link/sent");
        })
    )
    .session(Customizer.withDefaults())
    .build();

WebAuthn / Passkey

FIDO2 WebAuthn 기반 생체 인증 및 하드웨어 보안 키 인증입니다. 가장 안전한 비밀번호 없는 인증 방식입니다. 기본 order는 400입니다.

전체 옵션

기본 설정

registry
    .passkey(passkey -> passkey
        .rpName("My Application")
        .rpId("example.com")
        .allowedOrigins("https://example.com")
    )
    .session(Customizer.withDefaults())
    .build();

Passkey 등록 플로우

Passkey 등록은 3단계로 진행됩니다. 서버는 Spring Security의 UserCredentialRepository를 통해 자격 증명을 저장합니다.

  Client                         Server
    |                               |
    |  1. POST /webauthn/register   |
    |        /options               |
    |  ---------------------------> |
    |                               | PublicKeyCredentialCreationOptions
    |  <--------------------------- | (rpId, rpName, userId, challenge)
    |                               |
    |  2. navigator.credentials     |
    |        .create(options)       |
    |  [Browser WebAuthn API]       |
    |                               |
    |  3. POST /webauthn/register   |
    |  ---------------------------> |
    |  (AuthenticatorAttestation    | Verify + Store in
    |   Response)                   | UserCredentialRepository
    |                               |
    |  <--- 201 Created ----------- |

Passkey 관리 REST API

단일 인증 vs MFA 2차 요소

Passkey는 단일 인증과 MFA 2차 요소 인증에서 완전히 다른 URL, 어댑터 및 상태 관리를 사용합니다.

자동 핸들러 선택

인증 방법에 커스텀 핸들러가 지정되지 않으면, 인증 플로우와 상태 유형에 따라 적절한 핸들러가 자동으로 선택됩니다.

성공 / 실패 핸들러 선택 규칙

SecurityContextRepository 선택 규칙

커스텀 핸들러 구현에 대해서는 적응형 MFA 문서의 확장 포인트 섹션을 참조하세요.