적응형 MFA

개요

Contexa MFA는 1차 인증 + 2차 요소로 구성됩니다. 정책 엔진이 MFA 필요 여부를 결정하고, 상태 머신이 인증 플로우를 관리합니다.

기본 MFA order는 200입니다. .mfa()에서 직접 .form()이나 .rest()를 호출하면 UnsupportedOperationException이 발생합니다. 반드시 .primaryAuthentication()을 사용해야 합니다.

빠른 시작

Form 1차 인증 + Passkey 2차 인증의 가장 간단한 MFA 설정입니다.

registry
    .mfa(mfa -> mfa
        .primaryAuthentication(primary -> primary
            .formLogin(form -> form.loginPage("/login")))
        .passkey(Customizer.withDefaults())
    )
    .session(Customizer.withDefaults())
    .build();

1차 인증

primaryAuthentication()을 통해 1차 인증 방법을 설정합니다. formLogin()과 restLogin() 중 하나만 선택 가능합니다 (상호 배타적).

Form 1차 인증

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form
            .loginPage("/login")
            .usernameParameter("email")
            .failureUrl("/login?error")))
    .ott(Customizer.withDefaults())
)

REST 1차 인증

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .restLogin(rest -> rest
            .loginProcessingUrl("/api/auth/login")))
    .passkey(Customizer.withDefaults())
)

MFA 요소 (2차 인증)

2차 인증 요소를 추가합니다. 최소 하나의 2차 요소가 필요하며, 여러 요소를 결합할 수 있습니다.

사용 가능한 2차 요소

다중 요소 결합

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .ott(ott -> ott
        .tokenService(emailTokenService))
    .passkey(passkey -> passkey
        .rpName("My App")
        .rpId("example.com"))
)

각 요소는 currentStepOrderCounter를 통해 순차적 order(1, 2, 3...)가 자동 할당됩니다. 사용자는 요소 선택 페이지에서 원하는 요소를 선택합니다.

requiredFactors() - 필수 인증 요소 수

MFA 성공을 위해 완료해야 하는 2차 인증 요소의 수를 제어합니다. 기본값은 등록된 모든 요소를 완료해야 합니다.

// 2개 요소를 등록하되, 1개만 완료하면 MFA 성공
.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(Customizer.withDefaults()))
    .passkey(Customizer.withDefaults())
    .ott(Customizer.withDefaults())
    .requiredFactors(1)
)

사용 사례: 유연한 대체 수단

여러 요소를 등록하되 하나만 요구하여 대체 수단을 제공합니다. Passkey를 사용할 수 없는 사용자(예: 생체 인증 하드웨어 없음)는 OTT 이메일 인증으로 대체할 수 있습니다.

// 관리자 포털: Passkey 우선, OTT 대체 수단
.mfa(mfa -> mfa
    .urlPrefix("/admin")
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.defaultSuccessUrl("/admin")))
    .passkey(Customizer.withDefaults())   // 첫 번째로 자동 시작
    .ott(Customizer.withDefaults())       // 대체 수단으로 사용 가능
    .requiredFactors(1)                   // 1개만 필요
)

MFA 페이지

mfaPage()를 통해 MFA 플로우의 각 단계에 대한 페이지 URL을 커스터마이즈합니다.

.mfa(mfa -> mfa
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .ott(Customizer.withDefaults())
    .mfaPage(page -> page
        .selectFactorPage("/mfa/select")
        .ottPages("/mfa/ott/request", "/mfa/ott/verify")
        .failurePageUrl("/mfa/failed"))
)

커스텀 MFA 페이지 만들기

MFA 페이지의 CSS와 레이아웃은 자유롭게 수정할 수 있습니다. 다만 다음 요소는 반드시 유지해야 합니다.

수정 불가

• CSRF meta 태그: <meta name="_csrf" th:content="${csrfToken}">
• id="contexa-page-config" div와 data-* 속성
• Input name 속성: username, password, token, _csrf, mfaSessionId
• Form id, method, th:action
• button id: loginButton, sendCodeButton, verifyButton, resendButton, authButton
• th:utext="${hiddenInputsHtml}" -- CSRF + mfaSessionId hidden input을 자동 생성

수정 가능

• CSS 색상, 레이아웃, 배경
• 로고, 아이콘
• 텍스트 콘텐츠
• 폼 필드 스타일

필수 JavaScript 파일

MFA 데이터 플로우

MFA 정책 커스터마이제이션

MfaPolicyProvider를 구현하여 MFA 요구 결정을 커스터마이즈합니다. @ConditionalOnMissingBean으로 등록되므로, 동일한 타입의 빈을 정의하면 자동으로 오버라이드됩니다.

내장 구현체

커스텀 정책 구현 예제

@Bean
public MfaPolicyProvider mfaPolicyProvider() {
    return new MfaPolicyProvider() {
        @Override
        public MfaDecision evaluateInitialMfaRequirement(FactorContext ctx) {
            String ip = ctx.getRequest().getRemoteAddr();
            if (trustedIpRanges.contains(ip)) {
                return MfaDecision.noMfaRequired();
            }
            return MfaDecision.challenged("Untrusted IP");
        }
        // ... other methods
    };
}

MfaDecision 유형

DSL을 통한 정책 주입

.mfa(mfa -> mfa
    .policyProvider(customMfaPolicyProvider)
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .passkey(Customizer.withDefaults())
)

Step-up 인증

이미 인증된 사용자가 민감한 리소스에 접근할 때 추가 인증을 요구합니다.

ContexaMFA SDK Global Interceptor는 모든 HTTP 요청에서 401/403/423 응답을 자동 감지하고 MFA 챌린지로 리다이렉트합니다. 인증이 완료되면 원래 요청이 자동으로 재시도됩니다.

MFA 상태 머신 이벤트

@EventListener를 사용하여 MFA 상태 변경 이벤트를 수신하고 감사 로그, 알림 등을 구현할 수 있습니다.

이벤트 유형

종료 상태

감사 로그 구현 예제

@EventListener
public void onMfaStateChange(MfaStateMachineEvents.StateChangeEvent event) {
    auditService.log(
        event.getUserId(),
        event.getFromState(),
        event.getToState()
    );
}

@EventListener
public void onMfaError(MfaStateMachineEvents.ErrorEvent event) {
    alertService.notify(
        event.getErrorType(),
        event.getMessage()
    );
}

Multi MFA

여러 개의 독립적인 MFA Flow를 동시에 운영할 수 있습니다. 각 Flow는 자체 SecurityFilterChain, 자체 2차 인증 요소, 자체 URL 네임스페이스를 가집니다.

requiredFactors() — 다중 요소 수 설정

기본적으로 MFA는 설정된 모든 2차 요소를 완료해야 합니다. 예를 들어 .ott()와 .passkey()를 모두 구성하면, 사용자는 두 가지 모두 완료해야 MFA가 성공합니다. requiredFactors(int count)를 사용하면 설정된 요소 수보다 적은 수만 요구하도록 재정의할 수 있습니다.

// 기본: OTT와 Passkey 모두 필요 (2개 요소 등록 = 2개 필요)
registry
    .mfa(mfa -> mfa
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .passkey(Customizer.withDefaults())
    ).session(Customizer.withDefaults())

// 재정의: 2개 중 1개만 완료하면 됨
registry
    .mfa(mfa -> mfa
        .requiredFactors(1)
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .passkey(Customizer.withDefaults())
    ).session(Customizer.withDefaults())

기본 설정

여러 .mfa()를 등록하면 자동으로 고유한 typeName이 부여됩니다.

registry
    .mfa(mfa -> mfa
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .passkey(Customizer.withDefaults())
        .order(60)
    ).session(Customizer.withDefaults())   // typeName = "mfa" (자동)

    .mfa(mfa -> mfa
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .order(70)
    ).session(Customizer.withDefaults())   // typeName = "mfa_2" (자동)

    .build();

name() - 명시적 Flow 이름 지정

name()으로 의미 있는 Flow 이름을 지정할 수 있습니다. 자동 번호 대신 사용됩니다.

.mfa(mfa -> mfa
    .name("admin")     // typeName = "mfa_admin"
    .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
    .passkey(Customizer.withDefaults())
    .order(60)
).session(Customizer.withDefaults())

.mfa(mfa -> mfa
    .name("user")      // typeName = "mfa_user"
    .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
    .ott(Customizer.withDefaults())
    .order(70)
).session(Customizer.withDefaults())

urlPrefix() - URL 격리

urlPrefix()는 해당 Flow의 모든 MFA URL에 접두사를 자동 적용하고, securityMatcher도 자동으로 설정합니다. Multi MFA에서 각 Flow가 서로 다른 URL 네임스페이스를 갖도록 보장합니다.

registry
    // Admin: Passkey MFA
    .mfa(mfa -> mfa
        .urlPrefix("/admin")
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .passkey(Customizer.withDefaults())
        .order(60)
    ).session(Customizer.withDefaults())

    // User: OTT MFA
    .mfa(mfa -> mfa
        .urlPrefix("/user")
        .primaryAuthentication(auth -> auth.formLogin(Customizer.withDefaults()))
        .ott(Customizer.withDefaults())
        .order(70)
    ).session(Customizer.withDefaults())

    .build();

urlPrefix("/admin") 설정 시 URL 변환:

defaultLoginUrl() - 개별 URL 변경

urlPrefix() 대신 개별 URL만 변경하고 싶을 때 사용합니다. 자동 생성 로그인 폼의 URL을 변경하되, Spring Security 표준의 커스텀 페이지 동작은 유지합니다.

.mfa(mfa -> mfa
    .primaryAuthentication(auth -> auth.formLogin(form -> form
        .defaultLoginUrl("/admin/mfa/login")
        .defaultSuccessUrl("/admin/dashboard")))
    .passkey(Customizer.withDefaults())
    .order(60)
).session(Customizer.withDefaults())

Multi MFA DSL API 요약

주의사항

MFA + 단일 인증 동시 설정

MFA와 단일 인증을 함께 등록하여 서로 다른 요청 경로에 서로 다른 인증 수준을 적용합니다.

registry
    // 관리자: Form + OAuth2 (단일 인증)
    .form(f -> f.order(20).loginPage("/admin/login")
        .rawHttp(http -> http.securityMatcher("/admin/**")))
    .oauth2(Customizer.withDefaults())

    // 사용자: MFA (Form 1차 + Passkey) + Session
    .mfa(m -> m.order(100)
        .primaryAuthentication(auth -> auth
            .formLogin(form -> form.loginPage("/login")))
        .passkey(Customizer.withDefaults()))
    .session(Customizer.withDefaults())

    .build();

order()를 사용하여 Filter Chain 우선순위를 제어하고, rawHttp()의 securityMatcher()로 어떤 체인이 어떤 요청을 처리할지 결정합니다. 각 인증 방법에 대해 서로 다른 상태 관리(session/oauth2)를 설정할 수 있습니다.

MFA 핸들러

MFA 성공 및 실패에 대한 커스텀 핸들러를 지정할 수 있습니다.

.mfa(mfa -> mfa
    .mfaSuccessHandler(customSuccessHandler)
    .mfaFailureHandler(customFailureHandler)
    .primaryAuthentication(primary -> primary
        .formLogin(form -> form.loginPage("/login")))
    .passkey(Customizer.withDefaults())
)

핸들러 인터페이스 및 구현 가이드는 인증 문서의 핸들러 자동 선택 섹션을 참조하세요.

MFA REST API

응답 형식

ContexaMFA JavaScript SDK

브라우저에서 MFA 플로우를 제어하는 JavaScript SDK (v2.1.0)입니다.

빠른 시작

<script src="/ko/js/contexa-mfa-sdk.js?v=1776136758910"></script>
<script>
const mfa = new ContexaMFA.Client({
    autoInit: true,
    tokenPersistence: 'localStorage'
});
mfa.loginForm('username', 'password')
    .then(result => { /* handle result */ });
</script>

Client API

생성자 옵션

Global Interceptor

모든 fetch/XMLHttpRequest 호출에서 401/403/423 응답을 자동 감지하고 Step-up 인증 페이지로 리다이렉트합니다. 인증이 완료되면 원래 요청이 자동으로 재시도됩니다.