포털 공통 중앙 인증 계약
목적
Directory Service는 하위 포털의 유일한 브라우저 인증 제공자다. ARISAM Document Library, Guide Center, Process Center를 포함한 모든 하위 포털은 사용자 비밀번호를 직접 수집·검증·저장하지 않는다. 포털은 중앙 로그인 화면으로 리디렉션하고, callback에서 일회성 authorization code를 PKCE로 교환한 뒤 자기 서비스의 세션과 권한 모델에 연결한다.
이 계약의 운영 기준은 포털별 환경변수가 아니라 Directory Service 관리자 웹 화면의 도메인·URL 설정이다. 포털의 공개 도메인이나 callback이 바뀌면 중앙 설정을 갱신하며, 포털 코드는 현재 요청의 공개 origin에서 callback 주소를 계산한다.
웹 기반 포털 등록
관리자는 Directory Service의 도메인·URL 설정에서 포털마다 아래 값을 관리한다. client_id와 callback URL은 authorize 요청과 정확히 일치해야 하며, callback은 HTTPS 공개 주소여야 한다.
| 항목 | 역할 | 관리 위치 |
|---|---|---|
| Portal ID | Directory Service 내부 포털 식별자·감사 기록·토큰 azp | Directory Service 관리자 웹 화면 |
| Client ID | authorize·token 교환에 사용하는 공개 포털 식별자 | Directory Service 관리자 웹 화면 및 포털 코드의 고정 기본값 |
| Base URL | 포털 공개 origin·브랜딩 기준 | Directory Service 관리자 웹 화면 |
| Redirect URI | 중앙 로그인 후 복귀하는 정확한 callback 주소 | Directory Service 관리자 웹 화면 |
| 활성 상태·브랜딩 | 로그인 화면에 표시되는 포털 정보와 사용 가능 상태 | Directory Service 관리자 웹 화면 |
포털 배포 환경에는 browser authentication을 위한 Directory URL, client ID, redirect URI를 별도로 넣지 않는다. Directory Service의 공개 주소는 공통 기본값 https://directoryservice.배포 도메인을 사용하고, callback은 각 포털의 요청 origin과 아래의 고정 경로로 계산한다.
| 포털 | Client ID | Callback path |
|---|---|---|
| ARISAM Document Library | arisam | /auth/callback |
| Guide Center | guide-center | /auth/directory/callback |
| Process Center | process-center | /auth/callback |
브라우저 인증 흐름
- 포털의 로그인 시작 endpoint는 cryptographically random
state와 PKCE verifier를 만든다. - 포털은
state,code_challenge,code_challenge_method=S256,client_id, 계산된redirect_uri를 포함해/connect/authorize로 리디렉션한다. - Directory Service는 활성화된 웹 등록과 callback URL을 정확히 검증하고 중앙 사용자 자격증명을 확인한다.
- Directory Service는 5분·1회 사용 authorization code를 callback으로 전달한다.
- 포털 callback은 state와 만료 시간을 검증하고
/api/directory/v1/auth/token/pkce에 code, verifier, client ID, redirect URI를 보낸다. - 포털은 응답 사용자 정보를 자기 서비스의 사용자·권한 원장에 연결하고 HttpOnly 서비스 세션을 발급한다.
브라우저 PKCE token exchange에는 포털 API Key를 사용하지 않는다. 포털 API Key는 Directory 동기화, 서버 간 배포 알림처럼 browser login과 분리된 machine-to-machine 기능에만 사용한다.
Access token claims
포털이 검증하는 Directory access token에는 다음 신원 claim이 들어간다. name은 기존 포털을 위한 하위 호환 표시 이름이고, 화면 언어를 지원하는 포털은 koreanName/englishName을 골라 쓴다.
| claim | 설명 |
|---|---|
sub | Directory 사용자 ID |
loginId, email | 로그인 식별자 |
name | 하위 호환 표시 이름 — koreanName 우선, 없으면 englishName |
koreanName, englishName | 화면 언어에 맞게 고를 수 있는 이름 |
companyId | 소속 회사 ID — 소비 포털의 데이터 스코프 기준 |
companyDefaultLocale | 소속 회사의 기본 언어(ko/en) — 사용자별 언어가 없을 때 폴백 |
departmentId | 소속 부서 ID |
azp | 요청 포털 ID |
scope | directory:user (UI Center 관리자는 ui:read ui:write 추가) |
portalAdmin | 포털 관리자 여부 |
mustChangePassword | 다음 로그인에서 비밀번호 변경이 필요한지 |
보안·권한 원칙
| 원칙 | 요구 사항 |
|---|---|
| PKCE | S256 verifier와 challenge를 사용하고 verifier는 HttpOnly 단기 쿠키 또는 서명된 challenge cookie로만 보관한다. |
| State | state는 단기 만료·단일 로그인 시도에 묶고 callback에서 비교한 뒤 즉시 삭제한다. |
| Token | Directory access token은 서버에서만 사용하거나 암호화된 HttpOnly 쿠키에 저장한다. 브라우저 JavaScript·로그·URL에 기록하지 않는다. |
| 권한 | 중앙 인증은 신원만 확인한다. 각 포털의 admin, 콘텐츠 접근, 업무 권한은 포털의 로컬 권한 원장이 최종 결정한다. |
| 비밀번호 | 비밀번호 변경은 Directory Service 사용자 API를 사용하고 최소 10자 정책을 따른다. |
| 롤백 | 포털 장애 시 로컬 로그인으로 되돌리는 대신, Directory Service 웹 화면에서 해당 포털을 비활성화하고 배포를 중단하지 않는다. |
새 포털 도입 절차
새 하위 포털은 코드 배포보다 먼저 Directory Service 관리자 화면에서 Portal ID, Client ID, Base URL, callback을 등록한다. 이후 포털은 위 공통 flow를 구현하고, authorize 성공·잘못된 callback 거부·PKCE verifier 불일치·사용된 code 거부·비활성 사용자 거부를 테스트한다. 포털은 자신의 웹 callback URL을 Directory Service 외부에 중복된 환경변수로 저장하지 않는다.
서버 간 위임 토큰(on-behalf-of)
포털·서비스가 사용자 권한으로 다른 서비스(RagService 등)를 서버 간 호출할 때 쓰는 위임 토큰 계약은 위임 토큰(on-behalf-of) 계약에서 관리한다. 중앙 인증은 신원과 컨텍스트만 제공하고 최종 업무 권한은 각 소비 서비스가 강제한다는 원칙은 브라우저 인증과 동일하다.