Directory Service 중앙 로그인
기본 동작
Document Library는 운영 환경에서 Directory Service 중앙 인증을 기본 로그인 방식으로 사용한다. 사용자는 Document Library에 비밀번호를 입력하지 않고 Directory Service의 중앙 로그인 화면으로 이동한다. doclib은 authorization code를 PKCE로 교환해 사용자 신원을 확인한 뒤, 기존 managed_users 원장의 활성 여부·관리자 역할·콘텐츠 권한을 적용한다.
개발 환경의 자동 로그인 우회만 예외로 유지한다. 운영 환경에서 중앙 인증을 켜기 위해 DIRECTORY_CENTRAL_AUTH_ENABLED, DIRECTORY_SERVICE_URL, DIRECTORY_PORTAL_CLIENT_ID, DIRECTORY_PORTAL_REDIRECT_URI를 설정할 필요가 없다.
Directory Service 웹 등록
Directory Service 관리자 화면의 도메인·URL 설정에서 아래 포털을 등록하고 활성화한다. 이 웹 등록이 doclib 중앙 로그인 계약의 유일한 운영 설정이다.
| 설정 | 값 |
|---|---|
| Portal ID | document-lib |
| Client ID | document-lib |
| Portal name | Document Library |
| Base URL | doclib의 실제 공개 origin |
| Redirect URI | <doclib 공개 origin>/auth/callback |
예를 들어 현재 배포 플랫폼 주소를 사용할 때 callback은 https://documents.rlab.monster/auth/callback이다. 공개 도메인이 바뀌면 doclib 배포 환경 변수가 아니라 Directory Service 관리자 웹 화면의 Base URL·Redirect URI를 함께 갱신한다.
인증 흐름
/api/auth/directory/login이 단기 state와 PKCE verifier를 HttpOnly 서명 쿠키에 저장한다.- 브라우저는
https://directory.rlab.monster/connect/authorize로 이동한다. - Directory Service는
client_id=document-lib과 현재 origin에서 계산된 callback URI를 웹 등록값과 정확히 비교한다. - callback은 state와 verifier를 검증한 뒤 PKCE token endpoint에서 일회성 code를 교환한다.
- doclib은 Directory 사용자 ID와 KnoxID를 로컬 활성 사용자에게 매핑하고, 암호화된 토큰 쿠키 및 HttpOnly 서비스 세션을 발급한다.
비밀번호 변경은 Directory Service 사용자 API로 전달되며, 새 비밀번호는 10자 이상이어야 한다. Directory access token은 브라우저 JavaScript와 로그에 노출하지 않는다.
운영 전 점검
| 확인 항목 | 기대 결과 |
|---|---|
| Directory Service 포털 등록 | document-lib client와 정확한 HTTPS callback이 활성 상태 |
| doclib 로그인 화면 | 디렉터리 계정으로 계속 버튼 표시 |
| callback | 중앙 로그인 후 원래 doclib 경로로 복귀 |
| 권한 | doclib에 없거나 비활성인 사용자는 중앙 인증 성공 후에도 거부 |
| 비밀번호 변경 | Directory Service에서 성공하고 mustChangePassword 상태 해제 |
문제 발생 시에는 Directory Service 관리자 화면에서 callback·활성 상태를 먼저 점검한다. 브라우저 인증의 Directory 주소·클라이언트 ID·callback은 배포 플랫폼 환경 변수로 중복 관리하지 않는다.