Identity 구성

Auth Context 속성

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

핵심 인증 설정

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.urls는 AuthUrlProvider가 소비합니다. MFA 흐름에서는 MfaFlowUrlRegistry가 플로우별 provider를 생성해, 이름 있는 MFA 플로우가 전역 상태를 건드리지 않고 prefix를 안전하게 분리해서 쓸 수 있게 합니다.

단일 인증 URL

MFA URL 그룹

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

토큰 발급자 설정

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

내부 JWT 엔드포인트

OAuth2 / Authorization Server 설정

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 설정

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

MFA 타임아웃과 기본 동작

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

MFA 저장소 설정

MFA 팩터 설정

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

상태 머신 속성

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

핵심 상태 머신 설정

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

MFA, Redis, Distributed Lock

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.

Bridge 속성

BridgeProperties는 contexa.bridge에 바인딩됩니다. 외부(레거시) 인증 시스템과 Contexa 사이의 사용자/권한/위임/세션 정보를 양방향으로 매핑하는 브리지 계층을 제어합니다. SecurityContext 추출 키, 세션 attribute 후보, request attribute 키, HTTP 헤더 이름, 동기화 정책, 신뢰 프록시 목록을 정의합니다.

Bridge 핵심 토글

동기화 (Sync)

신뢰 프록시 (Network)

Authentication SecurityContext 키

contexa.bridge.authentication.security-context 아래의 속성으로, Authentication.SecurityContext 에 바인딩됩니다. 외부 인증 토큰의 claim/attribute 에서 표시 이름·principal 타입·인증 방식·assurance·MFA 상태·인증 시각·기타 추가 attribute 를 추출할 때 시도하는 키 목록을 정의합니다. 첫 번째 매칭 키의 값이 사용됩니다.

Authentication Session 키

contexa.bridge.authentication.session 아래의 속성으로, 공통 Bridge.Session 에 바인딩됩니다. 외부 시스템이 HTTP 세션의 attribute 로 인증된 사용자 객체를 보관할 때, Contexa 가 어떤 attribute 이름을 시도하고, 그 객체에서 어떤 키로 principal id, 표시 이름, 권한, 인증 방식, MFA 상태, 인증 시각, 추가 attribute 를 추출할지 정의합니다.

Authentication RequestAttributes 키

contexa.bridge.authentication.request-attributes 아래의 속성으로, 공통 Bridge.RequestAttributes 에 바인딩됩니다. 외부 필터가 사용자 객체를 HttpServletRequest attribute 로 보관할 때 어떤 attribute 후보를 시도할지, 그 객체에서 어떤 키로 정보를 읽을지, Contexa 가 다시 request attribute 로 노출할 때 어떤 평면 key 이름을 쓸지를 정의합니다.

탐색 / 추출 (공통 13)

평면 인증 attribute 키 (flat-*, 8)

Contexa 가 request attribute 로 다시 평탄화해서 노출할 때 사용하는 단일 키 이름입니다. 다운스트림 컴포넌트가 이 키로 직접 읽을 수 있습니다.

Authorization 매핑 키 (7)

Delegation 매핑 키 (11)

Authentication HTTP 헤더 이름

contexa.bridge.authentication.headers 아래의 속성으로, 공통 Bridge.Headers 에 바인딩됩니다. 외부 reverse proxy 또는 게이트웨이가 인증·인가·위임 정보를 HTTP 헤더로 전달할 때 Contexa 가 어떤 헤더 이름을 읽거나 발행할지 정의합니다. 모든 헤더 이름은 변경 가능합니다.

토글

인증 헤더 (8)

Authorization 헤더 (7)

Delegation 헤더 (11)

Authorization SecurityContext 키

contexa.bridge.authorization.security-context 아래의 속성으로, Authorization.SecurityContext 에 바인딩됩니다. 외부 시스템이 Spring SecurityContext 의 Authentication 객체에 인가 결정 결과(effect, 정책 ID, 권한 등)를 attribute 로 보관할 때, Contexa 가 어떤 키를 시도해서 그 정보를 읽을지 정의합니다. 첫 번째 매칭 키의 값이 사용됩니다.

Authorization Session 키

contexa.bridge.authorization.session 아래의 속성으로, Authorization.Session 에 바인딩됩니다. 외부 시스템이 HTTP 세션 attribute 의 사용자 객체에 인가 결정 정보를 담아 둘 때 어떤 attribute 후보를 시도하고, 그 객체에서 어떤 키로 effect/정책/스코프/역할/권한을 추출할지 정의합니다.

Authorization RequestAttributes / Headers

Authorization 도 동일한 공통 Bridge.RequestAttributes / Bridge.Headers 클래스를 재사용합니다. 키 구조와 기본값은 위 Authentication RequestAttributes 키 · Authentication HTTP 헤더 이름 표와 100% 동일하며, prefix 만 다음과 같이 다릅니다:

• contexa.bridge.authorization.request-attributes.* — 39 필드, 표 동일
• contexa.bridge.authorization.headers.* — 27 필드, 표 동일

같은 표를 다시 그리지 않고 prefix 만 안내하는 이유는 코드(BridgeProperties.java) 가 한 클래스를 3개 위치에서 참조하기 때문입니다 — 표 본문은 단일 진실의 출처를 유지합니다.

Delegation Session 키

contexa.bridge.delegation.session 아래의 속성으로, Delegation.Session 에 바인딩됩니다. 외부 시스템이 위임(agent delegation) 관련 정보 — agent ID, objective, 허용 operation/resource, 승인 필요, 만료 등 — 를 세션 attribute 의 사용자 객체에 담아둘 때 어떤 키를 시도할지 정의합니다.

Delegation RequestAttributes / Headers

Delegation 도 동일한 공통 Bridge.RequestAttributes / Bridge.Headers 클래스를 재사용합니다. 키 구조와 기본값은 Authentication RequestAttributes 키 · Authentication HTTP 헤더 이름 표와 100% 동일하며, prefix 만 다음과 같이 다릅니다:

• contexa.bridge.delegation.request-attributes.* — 39 필드, 표 동일
• contexa.bridge.delegation.headers.* — 27 필드, 표 동일