contexa-common

기존 로그인과 연결하기(인증 브리지)

앱이 이미 가진 로그인 · 권한 · 위임 정보를 Contexa가 요청마다 읽어 판정의 사실로 쓰게 하는 방법입니다. 앱이 무엇을 해 두어야 하는지, Contexa가 어디서 어떤 순서로 읽는지, MFA를 어떻게 알려 주는지, 게이트웨이 헤더와 직접 넘기기, 확장점을 설명합니다.

한눈에 보기

Contexa를 기본 모드(@EnableAISecurity, 앱이 로그인을 소유하는 HOST_OWNED)로 켜면 로그인은 앱의 Spring Security가 그대로 맡습니다. Contexa는 요청마다 인증 브리지(BridgeResolutionFilter)로 그 결과를 읽어 세 장의 도장을 만들고, 이 도장이 판정 프롬프트의 사실이 됩니다.

로그인 정보가 판정 사실이 되기까지브리지는 읽기만 합니다. 앱의 로그인 · 세션 · 응답을 바꾸지 않습니다.
  1. 요청
  2. 앱Spring Security가 로그인 사용자를 SecurityContext에 둠앱이 원래 하던 인증
  3. Contexa인증 브리지가 도장 세 장을 만듦인증 도장 · 인가 도장 · 위임 도장 + 완성도 보고서. 요청 속성 ctxa.bridge.*에 둠
  4. 판정 프롬프트의 사실로그인 방식 · MFA 여부 · 권한 · 위임 범위 · 정보의 출처

앱이 해 두어야 할 일

  1. Spring Security와 자기 SecurityFilterChain을 둡니다. 앱의 체인이 없으면 Spring Boot 기본 보안(모든 요청 인증)이 걸리고, Contexa가 시작할 때 경고 로그로 알려 줍니다. 앱 사용자도 없으면 시작이 거부됩니다.
  2. 로그인한 사용자를 SecurityContext에 인증된 Authentication으로 넣습니다. 브리지는 인증된(익명이 아닌) Authentication이 있을 때만 도장을 만듭니다. 없으면 아무것도 만들지 않고, 보호 메서드(@Protectable)는 SHADOW · ENFORCE 모드(기본은 ENFORCE)에서 거부되며 DISABLED · OBSERVE에서는 거부되지 않습니다.
  3. MFA와 로그인 방식을 알려 줍니다. Authentication의 details나 principal에 mfaVerified 같은 값을 두거나, OAuth2 · OIDC라면 토큰의 amr 클레임으로 충분합니다(MFA 알려 주기).
  4. 세션 객체에 역할 · 위임 정보가 있으면 키 이름만 맞춥니다. 브리지가 세션 속성을 훑어 사용자 객체를 찾습니다(세션 · 요청 속성에서 사용자 찾기).
Spring Security가 없는 레거시 앱. Spring Security 의존성을 넣고, 기존 접근 규칙을 그대로 두는 체인(예: anyRequest().permitAll())을 선언한 뒤, 기존 로그인이 확인한 사용자를 그 체인 안의 필터에서 SecurityContext에 넣어 주면 됩니다. 직접 넘기기만 부르는 방법은 그 요청의 증거만 남기고 SecurityContext를 채우지 않으므로 @Protectable을 쓰려면 부족합니다.

브리지가 하지 않는 일

  • 앱이 로그인을 소유할 때(HOST_OWNED) 앱의 인증 · 인가 · 세션에 끼어들지 않습니다. 세션에 저장하지 않고, 헤더를 쓰지 않습니다.
  • 앱이 로그인을 소유할 때 브리지 필터는 앱의 Spring Security 체인 바로 뒤(체인 순서 + 1, Contexa 집행 필터보다 앞)의 서블릿 필터로 등록되어 앱의 Spring Security 체인이 끝난 뒤에 돕니다. 그래서 Contexa 집행 필터 · 컨트롤러 · @Protectable 메서드에서는 도장을 읽을 수 있지만, 앱 체인 안의 URL 인가 단계에서는 아직 도장이 없습니다(Spring Boot 필터 순서에 따른 동작). 로그인을 Contexa가 소유할 때(CONTEXA_OWNED)는 Contexa 체인 안(세션 흐름은 SecurityContextHolderFilter 다음, 토큰 흐름은 BearerTokenAuthenticationFilter 다음)에 들어갑니다.
  • 예외: 사용자 거울은 앱이 소유할 때도 Contexa DB에 사용자 행을 씁니다.

어디서 어떤 순서로 읽나

도장읽는 곳(순서)여러 곳에서 나오면
인증 도장
(누구인가, 어떻게 로그인했나)
SecurityContext → 세션 → 요청 속성 → 헤더사용자 ID가 있는 첫 결과를 씁니다.
인가 도장
(무엇을 할 수 있나)
SecurityContext · 세션 · 요청 속성 · 헤더 모두모두 모아 합칩니다. 허용(ALLOW)과 거부(DENY)가 함께 나오면 거부로 정합니다. 아무 데도 없으면 인증 도장의 권한에서 만듭니다.
위임 도장
(누가 무엇을 맡겼나)
접근 토큰 → 세션 → 요청 속성 → 헤더 → 에이전트 자기 계정첫 결과를 씁니다.

@EnableAISecurity(authObjectLocation = ...)는 인증 도장의 세션 · 요청 속성 · 헤더 시도 순서만 바꿉니다(다른 곳을 끄지 않습니다). 도장마다 출처(SECURITY_CONTEXT, SESSION, REQUEST_ATTRIBUTE, HEADER, EXPLICIT_HANDOFF 등)가 함께 기록되어, 프롬프트에 "이 사실은 어디서 왔는가"가 실립니다.

세션 · 요청 속성에서 사용자 찾기

SecurityContext에서 사용자를 찾지 못하면 브리지는 세션, 그다음 요청 속성에서 사용자 객체를 찾습니다. 찾는 순서는 셋입니다.

  1. 지정한 이름. contexa.bridge.authentication.session.attribute(요청 속성은 contexa.bridge.authentication.request-attributes.attribute)에 이름을 주면 그 속성을 먼저 봅니다. 사용자 ID가 있으면 바로 씁니다.
  2. 후보 이름. 세션은 currentUser · authenticatedUser · sessionUser · userSession · principal · user · securityUser · authenticatedPrincipal, 요청 속성은 currentUser · authenticatedUser · requestUser · principal · user · authenticatedPrincipal · authUser를 봅니다.
  3. 자동 탐색. auto-discover(기본 켬)이면 나머지 속성도 모두 훑습니다.

2 · 3단계에서는 사용자 ID(userId · username · id · loginId · email)가 있는 객체만 후보가 되고, 아래 점수가 가장 높은 객체를 씁니다. 세션에 사용자처럼 보이는 객체가 여럿이면 1단계 이름이나 object-type-name(클래스의 전체 이름 또는 짧은 이름)을 알려 주는 것이 안전합니다.

객체에 있는 것점수
사용자 ID10(없으면 후보가 아님)
object-type-name과 같은 클래스+8
권한(roles · authorities · permissions · scopes)+4
표시 이름, 로그인 방식각 +2
보증 수준, MFA 여부, 인증 시각, 추가 속성(department · tenantId 등)각 +1

요청 속성에 값을 하나씩 넣기

사용자 객체 대신 값을 하나씩 요청 속성에 넣어도 됩니다. 인증 도장은 요청 속성에서 사용자 객체를 찾지 못했을 때 이 이름을 읽고, 인가 · 위임 도장은 늘 이 이름으로 읽습니다. 앱의 필터에서 넣으면 됩니다.

request.setAttribute("ctxa.auth.principalId", user.getId());
request.setAttribute("ctxa.auth.authenticated", true);
request.setAttribute("ctxa.auth.authorities", "ROLE_USER,ROLE_FINANCE");
request.setAttribute("ctxa.auth.mfaCompleted", true);
도장요청 속성 이름
인증ctxa.auth.principalId(필수) · displayName · authenticated · authorities · tenantId · organizationId · orgId · type · assurance · mfaCompleted · time
인가ctxa.authz.effect · privileged · policyId · policyVersion · scopeTags · roles · authorities
위임ctxa.delegation.enabled · agentId · objectiveId · objectiveFamily · objectiveSummary · allowedOperations · allowedResources · approvalRequired · privilegedExportAllowed · containmentOnly · expiresAt
  • ctxa.auth.authenticated를 넣었는데 참이 아니면 사용자로 보지 않습니다.
  • 권한처럼 값이 여럿이면 쉼표로 이은 글로 넣습니다.
  • 이름은 설정으로 바꿀 수 있습니다(예: contexa.bridge.authentication.request-attributes.flat-principal-id). 전체는 설정 색인에 있습니다.

MFA와 로그인 방식 알려 주기

SecurityContext의 Authentication에서는 details를 먼저, 다음에 principal을 봅니다. 객체에 claims · attributes 맵이 있으면(JWT 클레임, OAuth2 사용자 속성) 그 맵에서 찾습니다.

  1. 앱이 직접 준 값이 먼저입니다. MFA 완료는 mfa · mfaVerified · mfaCompleted · secondFactorVerified, 로그인 방식은 authenticationType · authMethod · loginMethod 등에서 읽습니다.
  2. 없으면 amr 클레임(RFC 8176)에서 계산합니다. 출처는 DERIVED_FROM_AMR로 표시됩니다.
amr 값로그인 방식
pwdPASSWORD
otp, sms, telONE_TIME_CODE
pop, hwk, swkPASSKEY
face, fpt, iris, retina, vbmBIOMETRIC
  • MFA 완료 규칙: amr에 mfa가 있거나, 서로 다른 방식이 2개 이상이면 완료입니다. 예: ["pwd","otp"] → MFA 완료, 방식 PASSWORD+ONE_TIME_CODE. ["otp","sms"] → 같은 방식 하나라 MFA 아님.
  • 인증 시각은 authenticationTime · authenticatedAt · loginTime · auth_time에서 읽습니다. 토큰 발급 시각(iat)은 다시 발급될 때 바뀌므로 일부러 쓰지 않습니다.
  • 보증 수준은 authenticationAssurance · authLevel · loa · acr에 값이 있을 때만 씁니다(amr로 계산하지 않음).
  • 세션 · 요청 속성 · 헤더에서는 amr을 해석하지 않고 MFA 플래그(mfaVerified, ctxa.auth.mfaCompleted, X-Contexa-Mfa-Completed)만 읽습니다.

게이트웨이 헤더로 넘기기

API 게이트웨이가 사용자 정보를 X-Contexa-* 헤더로 붙여 주는 구성이라면 헤더 읽기를 켭니다. 위조를 막기 위해 기본으로 꺼져 있고, 켜도 아래 조건을 모두 만족할 때만 믿습니다.

  • 요청이 신뢰 프록시(contexa.bridge.network.trusted-proxies, IP · CIDR)에서 왔다. 목록이 비거나 신뢰 프록시 검사(contexa.bridge.network.trusted-proxy-validation-enabled)를 끄면 헤더는 늘 거부됩니다.
  • 헤더의 사용자 ID가 앱이 인증한 사용자(SecurityContext)와 같고, 테넌트 · 조직 값도 맞다.
contexa:
  bridge:
    network:
      trusted-proxies: [10.0.0.0/8]
    authentication:
      headers:
        enabled: true      # X-Contexa-Principal-Id, X-Contexa-Mfa-Completed, ...
    authorization:
      headers:
        enabled: true      # X-Contexa-Authz-Effect, X-Contexa-Authz-Roles, ...
    delegation:
      headers:
        enabled: true      # X-Contexa-Delegated, X-Contexa-Agent-Id, ...

Contexa는 이 헤더를 읽기만 하고 응답에 쓰지 않습니다.

직접 넘기기(handoff)

앱의 로그인 코드에서 Contexa에 사용자를 직접 알려 줄 수 있습니다.

ContexaAuthBridge.handoff(request, response,
        ContexaAuthHandoff.of(user, authorities, Map.of("department", "R&D"))
                .withAuthenticationType("PASSWORD+ONE_TIME_CODE")
                .withMfaVerified(true));
  • 그 요청의 인증 증거를 기록합니다(출처 EXPLICIT_HANDOFF). 같은 요청에서 브리지 필터가 다른 사용자를 찾으면 충돌로 표시합니다.
  • 앱이 로그인을 소유할 때(HOST_OWNED)는 SecurityContext를 채우지 않습니다. Contexa가 소유할 때(CONTEXA_OWNED)만 SecurityContext를 채우고 세션에 저장합니다.
  • @EnableAISecurity가 켜져 있지 않으면 IllegalStateException, 사용자 ID를 정할 수 없으면 IllegalArgumentException이 납니다.

완성도: 브리지가 얼마나 알았나

브리지는 요청마다 얻은 정보의 완성도를 계산해 프롬프트에 함께 실습니다(bridge <수준>). 모델은 이것으로 "모르는 것"을 알고 판단합니다.

수준점수뜻
NONE0인증된 사용자를 찾지 못함
AUTHENTICATION_ONLY40누구인지만 앎
AUTHORIZATION_CONTEXT75(빠진 것마다 감점)권한 · 인가 결과까지 앎
DELEGATION_CONTEXT90위임 정보까지 앎

사용자 거울

브리지는 외부에서 로그인한 사용자를 Contexa DB의 사용자 표에 거울 행으로 남깁니다(관리 콘솔 · 정책에서 그 사용자를 다루기 위해). 키는 brg_ + SHA-256(인증 출처 · 조직 · 사용자 ID)이고, 무작위 비밀번호로 만들어져 직접 로그인에 쓸 수 없습니다. 같은 사용자가 60초(contexa.bridge.sync.min-refresh-interval-seconds) 안에 다시 오고 정보가 바뀌지 않았으면 다시 쓰지 않습니다. 같은 값은 그 확인의 결과를 기억하는 유효 시간으로도 쓰입니다. 앱이 로그인을 맡으면(HOST_OWNED) 같은 사용자의 요청이 같은 정보(인증 출처 · 이름 · 권한 · 속성 · 클라이언트 IP 등 확인이 비교하는 값)로 오면, 그 시간이 지나기 전까지 Contexa DB를 읽지 않고 기억한 결과로 답합니다. 0 이하면 기억하지 않습니다. 이메일은 인증 속성의 email · mail · userEmail에서 읽고, 없으면 <키>@shadow.contexa.local(contexa.bridge.sync.synthetic-email-domain)을 씁니다. 끄려면 contexa.bridge.sync.enabled=false.

앱에서 온 값이 열 길이보다 길면(긴 조직 경로 형태의 부서, 내선이 붙은 전화번호, 긴 프로필 이미지 주소) 열 길이로 잘라 담으므로, 값 하나가 길다고 거울이 실패하지 않습니다. 255자를 넘는 이메일은 만든 주소로 대신합니다. 255자를 넘는 사용자 ID는 거울 행을 만들지 않고(경고 한 번), 그 사용자도 판정과 집행은 받지만 추가 확인에 쓸 자기 요인은 없습니다.

자주 바꾸는 설정

설정기본값뜻언제 바꾸나
contexa.bridge.enabledtrue브리지 필터 켜기(끄면 직접 넘기기만 동작)브리지를 끌 때(판정 사실이 줄어듦)
contexa.bridge.ownershipHOST_OWNED(mode=FULL이면 CONTEXA_OWNED)로그인을 누가 소유하나. 이 값을 적으면 어노테이션보다 우선Contexa가 로그인까지 맡게 할 때 CONTEXA_OWNED
contexa.bridge.populate-security-contexttrueCONTEXA_OWNED일 때 SecurityContext가 비어 있으면 브리지가 찾은 사용자로 채움(HOST_OWNED에서는 채우지 않음)Contexa가 소유하면서도 SecurityContext는 앱이 채울 때 false
contexa.bridge.authentication.session.object-type-name없음세션 사용자 객체의 클래스 이름(점수 +8)세션에 사용자처럼 보이는 객체가 여럿일 때
contexa.bridge.authentication.session.auto-discovertrue후보 이름 밖의 세션 속성까지 훑기지정한 이름 · 후보 이름만 보게 할 때 false
contexa.bridge.authentication.prefer-security-contexttruefalse면 SecurityContext 대신 세션 · 요청 속성 · 헤더의 사용자 객체로 인증 도장을 만듦세션 · 헤더의 값을 먼저 읽게 할 때
contexa.bridge.authentication.security-context.mfa-keysmfa, mfaVerified, mfaCompleted, secondFactorVerifiedMFA 완료 플래그를 찾을 이름앱이 MFA 완료를 다른 이름으로 둘 때
contexa.bridge.authentication.security-context.amr-keysamrMFA · 로그인 방식을 계산할 RFC 8176 값의 이름토큰이 다른 클레임에 amr을 둘 때
contexa.bridge.authentication.session.attribute없음사용자 객체가 든 세션 속성 이름(없으면 후보 이름 → 자동 탐색)세션의 사용자 객체 이름을 알려 줄 때
contexa.bridge.authentication.headers.enabledfalse게이트웨이 헤더 읽기게이트웨이가 헤더로 사용자를 넘길 때(신뢰 프록시와 함께)
contexa.bridge.network.trusted-proxies없음헤더 · X-Forwarded-For를 믿을 프록시헤더를 켤 때 반드시
contexa.bridge.network.trusted-proxy-validation-enabledtrue신뢰 프록시 검사. 끄면 헤더 읽기는 늘 거부되고, 클라이언트 IP는 누가 보냈든 X-Forwarded-For를 믿는 옛 방식으로 정해짐바꾸지 않습니다(끄면 IP를 위조할 수 있음)
contexa.bridge.step-up.reauthentication-url없음HOST_OWNED에서 추가 확인 화면이 사용자를 앱 자체 MFA나 신원 공급자의 재인증으로 보내는 주소(예: prompt=login이나 max_age=0을 붙인 OIDC 인가 요청). 비어 있으면 이 방법을 보여 주지 않습니다. 그 뒤 인증 도장에 CHALLENGE보다 새로운 MFA 완료가 보이면 CHALLENGE가 풀립니다앱이 사용자를 직접 다시 인증할 수 있을 때(HOST_OWNED의 추가 확인)
contexa.bridge.sync.synthetic-email-domainshadow.contexa.local이메일이 없는 거울 사용자에게 붙이는 이메일 도메인회사 이메일 규칙에 맞출 때
contexa.bridge.sync.enabledtrue사용자 거울 동기화사용자 거울 동기화를 끌 때

contexa.bridge.* 설정 전체(311개)는 설정 색인에 있습니다.

확장점

확장점쓰는 때
AuthBridge앱만의 방법으로 요청에서 사용자를 꺼낼 때. 빈 하나를 선언하면 기본 세션 · 요청 속성 · 헤더 브리지를 대신합니다.
AuthenticationStampResolver · AuthorizationStampResolver · DelegationStampResolver도장을 만드는 곳을 더하거나 바꿀 때(@Order로 순서 지정)
ContexaAuthBridgeHandler직접 넘기기 처리 자체를 바꿀 때
BridgeUserMirrorSyncService사용자 거울을 다르게 남길 때
AgentClientDirectory어떤 클라이언트 · 계정이 승인된 에이전트인지 알려 줄 때(에이전트 보안)