기존 로그인과 연결하기(인증 브리지)
앱이 이미 가진 로그인 · 권한 · 위임 정보를 Contexa가 요청마다 읽어 판정의 사실로 쓰게 하는 방법입니다. 앱이 무엇을 해 두어야 하는지, Contexa가 어디서 어떤 순서로 읽는지, MFA를 어떻게 알려 주는지, 게이트웨이 헤더와 직접 넘기기, 확장점을 설명합니다.
한눈에 보기
Contexa를 기본 모드(@EnableAISecurity, 앱이 로그인을 소유하는 HOST_OWNED)로 켜면 로그인은 앱의 Spring Security가 그대로 맡습니다. Contexa는 요청마다 인증 브리지(BridgeResolutionFilter)로 그 결과를 읽어 세 장의 도장을 만들고, 이 도장이 판정 프롬프트의 사실이 됩니다.
- 요청
- 앱Spring Security가 로그인 사용자를
SecurityContext에 둠앱이 원래 하던 인증 - Contexa인증 브리지가 도장 세 장을 만듦인증 도장 · 인가 도장 · 위임 도장 + 완성도 보고서. 요청 속성
ctxa.bridge.*에 둠 - 판정 프롬프트의 사실로그인 방식 · MFA 여부 · 권한 · 위임 범위 · 정보의 출처
앱이 해 두어야 할 일
- Spring Security와 자기
SecurityFilterChain을 둡니다. 앱의 체인이 없으면 Spring Boot 기본 보안(모든 요청 인증)이 걸리고, Contexa가 시작할 때 경고 로그로 알려 줍니다. 앱 사용자도 없으면 시작이 거부됩니다. - 로그인한 사용자를
SecurityContext에 인증된Authentication으로 넣습니다. 브리지는 인증된(익명이 아닌)Authentication이 있을 때만 도장을 만듭니다. 없으면 아무것도 만들지 않고, 보호 메서드(@Protectable)는SHADOW·ENFORCE모드(기본은ENFORCE)에서 거부되며DISABLED·OBSERVE에서는 거부되지 않습니다. - MFA와 로그인 방식을 알려 줍니다.
Authentication의 details나 principal에mfaVerified같은 값을 두거나, OAuth2 · OIDC라면 토큰의amr클레임으로 충분합니다(MFA 알려 주기). - 세션 객체에 역할 · 위임 정보가 있으면 키 이름만 맞춥니다. 브리지가 세션 속성을 훑어 사용자 객체를 찾습니다(세션 · 요청 속성에서 사용자 찾기).
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에서 사용자를 찾지 못하면 브리지는 세션, 그다음 요청 속성에서 사용자 객체를 찾습니다. 찾는 순서는 셋입니다.
- 지정한 이름.
contexa.bridge.authentication.session.attribute(요청 속성은contexa.bridge.authentication.request-attributes.attribute)에 이름을 주면 그 속성을 먼저 봅니다. 사용자 ID가 있으면 바로 씁니다. - 후보 이름. 세션은
currentUser·authenticatedUser·sessionUser·userSession·principal·user·securityUser·authenticatedPrincipal, 요청 속성은currentUser·authenticatedUser·requestUser·principal·user·authenticatedPrincipal·authUser를 봅니다. - 자동 탐색.
auto-discover(기본 켬)이면 나머지 속성도 모두 훑습니다.
2 · 3단계에서는 사용자 ID(userId · username · id · loginId · email)가 있는 객체만 후보가 되고, 아래 점수가 가장 높은 객체를 씁니다. 세션에 사용자처럼 보이는 객체가 여럿이면 1단계 이름이나 object-type-name(클래스의 전체 이름 또는 짧은 이름)을 알려 주는 것이 안전합니다.
| 객체에 있는 것 | 점수 |
|---|---|
| 사용자 ID | 10(없으면 후보가 아님) |
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 사용자 속성) 그 맵에서 찾습니다.
- 앱이 직접 준 값이 먼저입니다. MFA 완료는
mfa·mfaVerified·mfaCompleted·secondFactorVerified, 로그인 방식은authenticationType·authMethod·loginMethod등에서 읽습니다. - 없으면
amr클레임(RFC 8176)에서 계산합니다. 출처는DERIVED_FROM_AMR로 표시됩니다.
amr 값 | 로그인 방식 |
|---|---|
pwd | PASSWORD |
otp, sms, tel | ONE_TIME_CODE |
pop, hwk, swk | PASSKEY |
face, fpt, iris, retina, vbm | BIOMETRIC |
- 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 <수준>). 모델은 이것으로 "모르는 것"을 알고 판단합니다.
| 수준 | 점수 | 뜻 |
|---|---|---|
NONE | 0 | 인증된 사용자를 찾지 못함 |
AUTHENTICATION_ONLY | 40 | 누구인지만 앎 |
AUTHORIZATION_CONTEXT | 75(빠진 것마다 감점) | 권한 · 인가 결과까지 앎 |
DELEGATION_CONTEXT | 90 | 위임 정보까지 앎 |
사용자 거울
브리지는 외부에서 로그인한 사용자를 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.enabled | true | 브리지 필터 켜기(끄면 직접 넘기기만 동작) | 브리지를 끌 때(판정 사실이 줄어듦) |
contexa.bridge.ownership | HOST_OWNED(mode=FULL이면 CONTEXA_OWNED) | 로그인을 누가 소유하나. 이 값을 적으면 어노테이션보다 우선 | Contexa가 로그인까지 맡게 할 때 CONTEXA_OWNED |
contexa.bridge.populate-security-context | true | CONTEXA_OWNED일 때 SecurityContext가 비어 있으면 브리지가 찾은 사용자로 채움(HOST_OWNED에서는 채우지 않음) | Contexa가 소유하면서도 SecurityContext는 앱이 채울 때 false |
contexa.bridge.authentication.session.object-type-name | 없음 | 세션 사용자 객체의 클래스 이름(점수 +8) | 세션에 사용자처럼 보이는 객체가 여럿일 때 |
contexa.bridge.authentication.session.auto-discover | true | 후보 이름 밖의 세션 속성까지 훑기 | 지정한 이름 · 후보 이름만 보게 할 때 false |
contexa.bridge.authentication.prefer-security-context | true | false면 SecurityContext 대신 세션 · 요청 속성 · 헤더의 사용자 객체로 인증 도장을 만듦 | 세션 · 헤더의 값을 먼저 읽게 할 때 |
contexa.bridge.authentication.security-context.mfa-keys | mfa, mfaVerified, mfaCompleted, secondFactorVerified | MFA 완료 플래그를 찾을 이름 | 앱이 MFA 완료를 다른 이름으로 둘 때 |
contexa.bridge.authentication.security-context.amr-keys | amr | MFA · 로그인 방식을 계산할 RFC 8176 값의 이름 | 토큰이 다른 클레임에 amr을 둘 때 |
contexa.bridge.authentication.session.attribute | 없음 | 사용자 객체가 든 세션 속성 이름(없으면 후보 이름 → 자동 탐색) | 세션의 사용자 객체 이름을 알려 줄 때 |
contexa.bridge.authentication.headers.enabled | false | 게이트웨이 헤더 읽기 | 게이트웨이가 헤더로 사용자를 넘길 때(신뢰 프록시와 함께) |
contexa.bridge.network.trusted-proxies | 없음 | 헤더 · X-Forwarded-For를 믿을 프록시 | 헤더를 켤 때 반드시 |
contexa.bridge.network.trusted-proxy-validation-enabled | true | 신뢰 프록시 검사. 끄면 헤더 읽기는 늘 거부되고, 클라이언트 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-domain | shadow.contexa.local | 이메일이 없는 거울 사용자에게 붙이는 이메일 도메인 | 회사 이메일 규칙에 맞출 때 |
contexa.bridge.sync.enabled | true | 사용자 거울 동기화 | 사용자 거울 동기화를 끌 때 |
contexa.bridge.* 설정 전체(311개)는 설정 색인에 있습니다.
확장점
| 확장점 | 쓰는 때 |
|---|---|
AuthBridge | 앱만의 방법으로 요청에서 사용자를 꺼낼 때. 빈 하나를 선언하면 기본 세션 · 요청 속성 · 헤더 브리지를 대신합니다. |
AuthenticationStampResolver · AuthorizationStampResolver · DelegationStampResolver | 도장을 만드는 곳을 더하거나 바꿀 때(@Order로 순서 지정) |
ContexaAuthBridgeHandler | 직접 넘기기 처리 자체를 바꿀 때 |
BridgeUserMirrorSyncService | 사용자 거울을 다르게 남길 때 |
AgentClientDirectory | 어떤 클라이언트 · 계정이 승인된 에이전트인지 알려 줄 때(에이전트 보안) |