Identity 구성

OSS Identity 런타임 구성을 설명합니다. 이 페이지는 현재 Contexa 코드베이스가 실제로 사용하는 spring.auth.*, contexa.identity.statemachine.* 속성과, AuthUrlProvider, MfaFlowUrlRegistry, IdentityDslRegistry, MfaDslConfigurerImpl, SessionStateConfigurer 같은 런타임 클래스가 이 설정을 어디에서 소비하는지를 함께 정리합니다.

Auth Context 속성

AuthContextPropertiesspring.auth prefix에 바인딩됩니다. 인증 상태 모드, 토큰 전송 방식, 토큰 발급자 모드, URL 그룹, MFA 기본값, 토큰 수명 주기를 제어합니다.

핵심 인증 설정

속성타입기본값설명
spring.auth.state-typeStateTypeOAUTH2기본 상태 모드를 선택합니다. 현재 enum 값은 OAUTH2, SESSION입니다.
spring.auth.token-transport-typeTokenTransportTypeHEADER토큰 전송 방식을 제어합니다. 현재 enum 값은 COOKIE, HEADER, HEADER_COOKIE입니다.
spring.auth.token-issuerTokenIssuerINTERNALContexa가 직접 토큰을 발급할지, 외부 Authorization Server를 사용할지 선택합니다. 현재 enum 값은 INTERNAL, AUTHORIZATION_SERVER입니다.
spring.auth.factor-selection-typeFactorSelectionTypeSELECTMFA 팩터를 사용자가 명시적으로 선택할지, 자동 선택할지 결정합니다. 현재 enum 값은 AUTO, SELECT입니다.
spring.auth.access-token-validitylong3600000액세스 토큰 유효 기간(밀리초)입니다.
spring.auth.refresh-token-validitylong604800000리프레시 토큰 유효 기간(밀리초)입니다.
spring.auth.refresh-rotate-thresholdlong43200000리프레시 토큰 사용 시 회전을 트리거하는 임계값입니다.
spring.auth.enable-refresh-tokenbooleantrue리프레시 토큰 발급을 활성화합니다.
spring.auth.allow-multiple-loginsbooleanfalse동일 principal의 동시 활성 로그인을 허용합니다.
spring.auth.max-concurrent-loginsint3다중 로그인을 허용할 때의 동시 로그인 상한입니다.
spring.auth.cookie-securebooleantrue인증 쿠키를 기본적으로 secure로 표시합니다.
spring.auth.token-persistenceStringmemory로그인/MFA 페이지에 전달되는 프런트엔드 토큰 저장 방식입니다. 현재 OSS 클라이언트 모드는 memory, localstorage, sessionstorage입니다.
spring.auth.token-prefixStringBearer Authorization 헤더 prefix입니다.
spring.auth.roles-claimStringroles역할을 읽어오는 JWT claim 이름입니다.
spring.auth.scopes-claimStringscopes스코프를 읽어오는 JWT claim 이름입니다.
spring.auth.oauth2-csrfbooleanfalseOAuth2 성격의 엔드포인트에 대한 CSRF 보호를 토글합니다.
YAML
spring:
  auth:
    state-type: oauth2
    token-transport-type: header
    token-issuer: internal
    factor-selection-type: select
    access-token-validity: 3600000
    refresh-token-validity: 604800000
    refresh-rotate-threshold: 43200000
    enable-refresh-token: true
    allow-multiple-logins: false
    max-concurrent-logins: 3
    cookie-secure: true
    token-persistence: memory
    token-prefix: "Bearer "
    roles-claim: roles
    scopes-claim: scopes
    oauth2-csrf: false

관련 런타임 문서: Authentication, Adaptive MFA, State Management.

URL 구성 그룹

spring.auth.urlsAuthUrlProvider가 소비합니다. MFA 흐름에서는 MfaFlowUrlRegistry가 플로우별 provider를 생성해, 이름 있는 MFA 플로우가 전역 상태를 건드리지 않고 prefix를 안전하게 분리해서 쓸 수 있게 합니다.

단일 인증 URL

속성기본값설명
spring.auth.urls.single.form-login-processing/login단일 팩터 폼 로그인 처리 엔드포인트입니다.
spring.auth.urls.single.form-login-page/login단일 팩터 폼 로그인 페이지입니다.
spring.auth.urls.single.rest-login-processing/api/login단일 팩터 REST 로그인 처리 엔드포인트입니다.
spring.auth.urls.single.login-failure/login?error단일 팩터 로그인 실패 리다이렉트입니다.
spring.auth.urls.single.login-success/단일 팩터 로그인 성공 리다이렉트입니다.
spring.auth.urls.single.logout-page/logout단일 팩터 로그아웃 페이지입니다.
spring.auth.urls.single.ott.request-email/login/ott단일 팩터 OTT 요청 페이지입니다.
spring.auth.urls.single.ott.code-generation/ott/generate단일 팩터 OTT 코드 생성 엔드포인트입니다.
spring.auth.urls.single.ott.code-sent/login/ott/sent단일 팩터 OTT 전송 완료 페이지입니다.
spring.auth.urls.single.ott.challenge/login/ott/verify단일 팩터 OTT 검증 페이지입니다.
spring.auth.urls.single.ott.login-processing/login/ott단일 팩터 OTT 검증 엔드포인트입니다.
spring.auth.urls.single.ott.login-failure/login/ott?error단일 팩터 OTT 실패 페이지입니다.
spring.auth.urls.single.passkey.login-page/login/webauthn단일 팩터 패스키 로그인 페이지입니다.
spring.auth.urls.single.passkey.login-processing/login/webauthn단일 팩터 패스키 검증 엔드포인트입니다.
spring.auth.urls.single.passkey.login-failure/login/webauthn?error단일 팩터 패스키 실패 페이지입니다.
spring.auth.urls.single.passkey.assertion-options/webauthn/authenticate/options패스키 assertion options 엔드포인트입니다.
spring.auth.urls.single.passkey.registration-options/webauthn/register/options패스키 등록 options 엔드포인트입니다.
spring.auth.urls.single.passkey.registration-processing/webauthn/register패스키 등록 처리 엔드포인트입니다.

MFA URL 그룹

속성기본값설명
spring.auth.urls.primary.form-login-processing/mfa/loginMFA 플로우 내부의 1차 폼 로그인 처리 경로입니다.
spring.auth.urls.primary.form-login-page/mfa/loginMFA 플로우 내부의 1차 폼 로그인 페이지입니다.
spring.auth.urls.primary.rest-login-processing/api/mfa/loginMFA 플로우 내부의 1차 REST 로그인 엔드포인트입니다.
spring.auth.urls.primary.login-failure/login?error1차 인증 실패 리다이렉트입니다.
spring.auth.urls.primary.login-success/1차 인증 성공 리다이렉트입니다.
spring.auth.urls.primary.logout-page/logout1차 인증 로그아웃 페이지입니다.
spring.auth.urls.mfa.select-factor/mfa/select-factorMFA 팩터 선택 페이지입니다.
spring.auth.urls.mfa.success/mfa/successMFA 성공 페이지입니다.
spring.auth.urls.mfa.failure/mfa/failureMFA 실패 페이지입니다.
spring.auth.urls.mfa.cancel/mfa/cancelMFA 취소 엔드포인트/페이지입니다.
spring.auth.urls.mfa.status/mfa/statusMFA 상태 조회 엔드포인트입니다.
spring.auth.urls.mfa.request-ott-code/mfa/request-ott-codeOTT 코드 요청 엔드포인트입니다.
spring.auth.urls.mfa.config/api/mfa/config페이지 생성기와 클라이언트 코드가 사용하는 MFA 구성 엔드포인트입니다.
spring.auth.urls.factors.ott.request-code-ui/mfa/ott/request-code-uiOTT 요청 페이지입니다.
spring.auth.urls.factors.ott.code-generation/mfa/ott/generate-codeOTT 코드 생성 엔드포인트입니다.
spring.auth.urls.factors.ott.code-sent/mfa/ott/code-sentOTT 코드 전송 완료 페이지입니다.
spring.auth.urls.factors.ott.challenge-ui/mfa/challenge/ottOTT 챌린지 페이지입니다.
spring.auth.urls.factors.ott.login-processing/login/mfa-ottOTT 로그인 처리 엔드포인트입니다.
spring.auth.urls.factors.ott.default-failure/mfa/challenge/ott?error=true기본 OTT 실패 리다이렉트입니다.
spring.auth.urls.factors.ott.single-ott-request-email/loginOttOttUrls가 유지하는 레거시 단일 OTT 요청 페이지 경로입니다.
spring.auth.urls.factors.ott.single-ott-code-generation/login/ott/generateOttUrls가 유지하는 레거시 단일 OTT 생성 경로입니다.
spring.auth.urls.factors.ott.single-ott-challenge/loginOttVerifyCodeOttUrls가 유지하는 레거시 단일 OTT 챌린지 경로입니다.
spring.auth.urls.factors.ott.single-ott-sent/ott/sentOttUrls가 유지하는 레거시 단일 OTT 전송 완료 페이지 경로입니다.
spring.auth.urls.factors.passkey.rp-idlocalhost기본 패스키 relying-party ID입니다.
spring.auth.urls.factors.passkey.rp-namecontexa-identity기본 패스키 relying-party 이름입니다.
spring.auth.urls.factors.passkey.allowed-originsnull허용 origin 목록입니다. 값이 없으면 패스키 빌더가 http://localhost:{server.port}를 fallback으로 사용합니다.
spring.auth.urls.factors.passkey.login-processing/login/mfa-webauthnMFA 모드 패스키 인증 엔드포인트입니다.
spring.auth.urls.factors.passkey.challenge-ui/mfa/challenge/passkey패스키 챌린지 페이지입니다.
spring.auth.urls.factors.passkey.registration-processing/webauthn/register패스키 등록 엔드포인트입니다.
spring.auth.urls.factors.passkey.assertion-options/webauthn/authenticate/options패스키 assertion options 엔드포인트입니다.
spring.auth.urls.factors.passkey.registration-options/webauthn/register/options패스키 등록 options 엔드포인트입니다.
spring.auth.urls.factors.recovery-code-login-processing/login/recovery/verify복구 코드 검증 엔드포인트입니다.
spring.auth.urls.factors.recovery-code-challenge-ui/mfa/challenge/recovery복구 코드 챌린지 페이지입니다.

런타임 소비 지점: AuthUrlProvider가 이 경로들을 해석하고, MfaFlowUrlRegistry가 이름 있는 MFA 플로우마다 별도 provider를 만들어 prefix를 안전하게 격리합니다.

토큰 발급자 설정

spring.auth.internalspring.auth.oauth2spring.auth.token-issuer 선택값에 따라 사용되는 두 가지 토큰 발급 설정입니다.

내부 JWT 엔드포인트

속성기본값설명
spring.auth.internal.login-uri/api/login내부 JWT 로그인 엔드포인트입니다.
spring.auth.internal.logout-uri/logout내부 로그아웃 엔드포인트입니다.
spring.auth.internal.refresh-uri/api/refresh내부 리프레시 엔드포인트입니다.

OAuth2 / Authorization Server 설정

속성기본값설명
spring.auth.oauth2.client-iddefault-clientOAuth2 client identifier입니다.
spring.auth.oauth2.client-secret173f8245-5f7d-4623-a612-aa0c68f6da4aOAuth2TokenSettings가 선언하는 기본 client secret입니다. 실제 배포에서는 반드시 override해야 합니다.
spring.auth.oauth2.issuer-urihttp://localhost:9000Issuer base URI입니다.
spring.auth.oauth2.token-endpoint/oauth2/token토큰 엔드포인트 경로입니다.
spring.auth.oauth2.scoperead기본 요청 scope입니다.
spring.auth.oauth2.redirect-urihttp://localhost:8080인증 후 redirect URI입니다.
spring.auth.oauth2.authorized-urinull선택적인 post-authorization redirect override입니다.
spring.auth.oauth2.jwk-key-store-pathnullJWK keystore 경로입니다.
spring.auth.oauth2.jwk-key-store-passwordnullKeystore 비밀번호입니다.
spring.auth.oauth2.jwk-key-aliasnullKeystore 내부 키 alias입니다.
spring.auth.oauth2.jwk-key-passwordnull키별 비밀번호 override입니다.
YAML
spring:
  auth:
    oauth2:
      client-id: my-client-app
      client-secret: ${OAUTH2_CLIENT_SECRET}
      issuer-uri: https://auth.example.com
      token-endpoint: /oauth2/token
      scope: read
      redirect-uri: https://app.example.com/callback
      authorized-uri: https://app.example.com/dashboard
      jwk-key-store-path: /etc/contexa/keys/jwk-keystore.p12
      jwk-key-store-password: ${JWK_STORE_PASSWORD}
      jwk-key-alias: contexa-signing-key
      jwk-key-password: ${JWK_KEY_PASSWORD}

MFA 설정

MfaSettingsspring.auth.mfa 아래에 중첩되며, MFA 세션 저장소, 팩터별 URL, 타임아웃, 모니터링 플래그, state-machine 연동 타이밍을 함께 제어합니다.

MFA 타임아웃과 기본 동작

아래 설정은 MfaSettings와 이를 사용하는 state-machine/MFA request 처리 코드가 함께 소비합니다.

속성타입기본값설명
spring.auth.mfa.session-timeout-mslong600000전체 MFA 세션 타임아웃입니다.
spring.auth.mfa.challenge-timeout-mslong300000개별 챌린지 타임아웃입니다.
spring.auth.mfa.inactivity-timeoutlong900000MFA 상태 idle timeout입니다.
spring.auth.mfa.cache-ttllong300000MFA 런타임 캐시 TTL입니다.
spring.auth.mfa.session-refresh-interval-mslong30000활성 MFA 세션 refresh 주기입니다.
spring.auth.mfa.state-machine-timeout-mslong10000state-machine 연동 MFA 핸들러의 timeout budget입니다.
spring.auth.mfa.max-retry-attemptsint5잠금 로직이 적용되기 전까지 허용되는 최대 검증 재시도 횟수입니다.
spring.auth.mfa.account-lockout-duration-mslong900000재시도 초과 후 MFA 잠금 지속 시간입니다.
spring.auth.mfa.minimum-delay-mslong500응답 시간 편차를 줄이기 위한 최소 지연값입니다.
spring.auth.mfa.device-remember-duration-mslong2592000000기기 기억 기간입니다.
spring.auth.mfa.otp-token-validity-secondsint300OTP 유효 기간입니다.
spring.auth.mfa.otp-token-lengthint6OTP 코드 길이입니다.
spring.auth.mfa.sms-resend-interval-secondsint60SMS 재전송 throttle입니다.
spring.auth.mfa.email-resend-interval-secondsint120이메일 재전송 throttle입니다.
spring.auth.mfa.state-machine-pool-sizeint100MfaSettings가 유지하는 legacy state-machine pool size 설정입니다.
spring.auth.mfa.state-machine-cache-ttl-mslong300000MfaSettings가 유지하는 legacy state-machine cache TTL 설정입니다.
spring.auth.mfa.circuit-breaker-failure-thresholdint5MFA circuit breaker open 전 실패 임계값입니다.
spring.auth.mfa.circuit-breaker-timeout-secondsint30MFA circuit breaker open-state timeout입니다.
spring.auth.mfa.detailed-logging-enabledbooleanfalse상세 MFA 진단 로그를 활성화합니다.
spring.auth.mfa.metrics-enabledbooleantrueMFA 메트릭 수집을 활성화합니다.
spring.auth.mfa.audit-logging-enabledbooleantrueMFA 감사 로그를 활성화합니다.
spring.auth.mfa.session-storage-typeStringhttp-session기본 MFA 세션 저장소 라벨입니다.
spring.auth.mfa.auto-select-repositorybooleanfalse저장소 자동 선택을 활성화합니다.
spring.auth.mfa.repository-priorityStringredis,memory,http-session저장소 우선순위 문자열입니다.
spring.auth.mfa.fallback-repository-typeStringhttp-sessionfallback 저장소 라벨입니다.

MFA 저장소 설정

속성기본값설명
spring.auth.mfa.http-session.enabledtrueHTTP-session 기반 MFA 저장소를 활성화합니다.
spring.auth.mfa.http-session.create-session-if-not-existstrue필요 시 HTTP 세션을 생성합니다.
spring.auth.mfa.http-session.session-attribute-nameMFA_SESSION_IDMFA 세션 식별자를 저장하는 attribute 이름입니다.
spring.auth.mfa.redis.enabledtrueRedis 기반 MFA 저장소를 활성화합니다.
spring.auth.mfa.redis.key-prefixmfa:session:Redis key prefix입니다.
spring.auth.mfa.redis.cookie-nameMFA_SIDRedis 기반 MFA 세션 식별자를 담는 cookie 이름입니다.
spring.auth.mfa.redis.secure-cookietrueMFA 세션 cookie를 secure로 표시합니다.
spring.auth.mfa.redis.http-only-cookietrueMFA 세션 cookie를 HTTP-only로 표시합니다.
spring.auth.mfa.redis.same-siteStrictSameSite cookie 속성입니다.
spring.auth.mfa.redis.connection-timeout3000Redis connection timeout입니다.
spring.auth.mfa.redis.max-retries3Redis retry limit입니다.
spring.auth.mfa.memory.enabledtrue메모리 기반 MFA 저장소를 활성화합니다.
spring.auth.mfa.memory.cleanup-interval-minutes5메모리 MFA 세션 정리 주기입니다.
spring.auth.mfa.memory.max-sessions10000메모리 MFA 세션 최대 개수입니다.
spring.auth.mfa.memory.enable-metricstrue메모리 저장소 메트릭을 활성화합니다.

MFA 팩터 설정

속성기본값설명
spring.auth.mfa.sms-factor.providerdefaultSMS provider 식별자입니다.
spring.auth.mfa.sms-factor.template-idmfa_sms_templateSMS template 식별자입니다.
spring.auth.mfa.sms-factor.max-daily-attempts10일일 SMS 전송 상한입니다.
spring.auth.mfa.sms-factor.enabledtrueSMS MFA 팩터를 활성화합니다.
spring.auth.mfa.email-factor.from-addressnoreply@company.com이메일 OTP 발신 주소입니다.
spring.auth.mfa.email-factor.template-idmfa_email_template이메일 template 식별자입니다.
spring.auth.mfa.email-factor.max-daily-attempts5일일 이메일 전송 상한입니다.
spring.auth.mfa.email-factor.enabledtrue이메일 MFA 팩터를 활성화합니다.
YAML
spring:
  auth:
    mfa:
      session-timeout-ms: 600000
      challenge-timeout-ms: 300000
      max-retry-attempts: 5
      repository-priority: redis,memory,http-session
      redis:
        enabled: true
        key-prefix: mfa:session:
        cookie-name: MFA_SID
      memory:
        enabled: true
        max-sessions: 10000
      sms-factor:
        enabled: true
        provider: default
      email-factor:
        enabled: true
        from-address: noreply@company.com

상태 머신 속성

StateMachinePropertiescontexa.identity.statemachine에 바인딩됩니다. Identity 모듈과 관련 필터/핸들러가 사용하는 MFA 상태 머신 런타임을 제어합니다.

핵심 상태 머신 설정

속성타입기본값설명
contexa.identity.statemachine.enabledbooleantrueMFA 상태 머신 런타임 전체를 켜고 끄는 master switch입니다.
contexa.identity.statemachine.operation-timeout-secondsint10상태 머신 연산 timeout budget입니다.
contexa.identity.statemachine.circuit-breaker.failure-thresholdint5circuit breaker open 전 실패 임계값입니다.
contexa.identity.statemachine.circuit-breaker.timeout-secondsint30circuit breaker open-state timeout입니다.
contexa.identity.statemachine.circuit-breaker.half-open-requestsint3half-open 상태에서 허용되는 요청 수입니다.

풀, 영속화, 캐시, 이벤트

속성기본값설명
contexa.identity.statemachine.pool.core-size10상태 머신 executor core size입니다.
contexa.identity.statemachine.pool.max-size50상태 머신 executor max size입니다.
contexa.identity.statemachine.pool.keep-alive-time10풀 worker keep-alive 시간입니다.
contexa.identity.statemachine.pool.expansion-threshold0.8worker 확장 임계값입니다.
contexa.identity.statemachine.pool.shrink-threshold0.2worker 축소 임계값입니다.
contexa.identity.statemachine.persistence.typememory영속화 backend label입니다.
contexa.identity.statemachine.persistence.enable-fallbacktruefallback 영속화를 활성화합니다.
contexa.identity.statemachine.persistence.ttl-minutes30영속화 TTL(분)입니다.
contexa.identity.statemachine.persistence.enable-compressiontrue영속화 payload 압축을 활성화합니다.
contexa.identity.statemachine.persistence.compression-threshold1024압축 임계값(바이트)입니다.
contexa.identity.statemachine.cache.max-size1000상태 머신 snapshot용 메모리 캐시 크기입니다.
contexa.identity.statemachine.cache.ttl-minutes5캐시 TTL(분)입니다.
contexa.identity.statemachine.cache.enable-warmupfalse시작 시 캐시 warmup을 활성화합니다.
contexa.identity.statemachine.events.enabledtrue상태 머신 이벤트 발행을 활성화합니다.
contexa.identity.statemachine.events.typelocal이벤트 전송 타입입니다.
contexa.identity.statemachine.events.batch-size100이벤트 배치 크기입니다.
contexa.identity.statemachine.events.batch-interval-ms100이벤트 배치 간격입니다.
contexa.identity.statemachine.events.backpressure-threshold1000백프레셔 임계값입니다.

MFA, Redis, Distributed Lock

속성기본값설명
contexa.identity.statemachine.mfa.enable-metricstrue상태 머신 MFA 메트릭을 활성화합니다.
contexa.identity.statemachine.mfa.max-retries3상태 머신이 사용하는 재시도 상한입니다.
contexa.identity.statemachine.mfa.session-timeout-minutes30세션 timeout(분)입니다.
contexa.identity.statemachine.mfa.max-concurrent-sessions1000동시 상태 머신 세션 상한입니다.
contexa.identity.statemachine.mfa.transition-timeout-seconds30상태 전이별 timeout입니다.
contexa.identity.statemachine.redis.enabledfalseRedis 기반 상태 머신 저장소를 활성화합니다.
contexa.identity.statemachine.redis.ttl-minutes30Redis TTL(분)입니다.
contexa.identity.statemachine.redis.key-prefixmfa:statemachine:상태 머신 엔트리용 Redis key prefix입니다.
contexa.identity.statemachine.redis.connection-timeout-ms2000Redis connection timeout입니다.
contexa.identity.statemachine.redis.command-timeout-ms1000Redis command timeout입니다.
contexa.identity.statemachine.distributed-lock.enabledtrue상태 전이 주변의 distributed lock을 활성화합니다.
contexa.identity.statemachine.distributed-lock.timeout-seconds10distributed lock timeout입니다.
contexa.identity.statemachine.distributed-lock.max-retry-attempts3lock 획득 재시도 상한입니다.
contexa.identity.statemachine.distributed-lock.retry-interval-ms100lock 획득 재시도 간격입니다.
contexa.identity.statemachine.distributed-lock.enable-deadlock-detectiontruedistributed lock deadlock detection을 활성화합니다.
YAML
contexa:
  identity:
    statemachine:
      enabled: true
      operation-timeout-seconds: 10
      pool:
        core-size: 10
        max-size: 50
      persistence:
        type: memory
        ttl-minutes: 30
      events:
        enabled: true
        type: local
      mfa:
        max-retries: 3
        session-timeout-minutes: 30
      distributed-lock:
        enabled: true
        timeout-seconds: 10

관련 런타임 문서: Identity DSL, Authentication, Adaptive MFA, State Management.