중앙 인증 연동 운영 가이드
인증 흐름
외부 포털은 사용자를 자체 로그인 화면에서 인증하지 않는다. 포털은 client_id, 정확한 redirect_uri, state를 포함해 Directory Service의 /connect/authorize 화면으로 이동한다. Directory Service는 관리자 화면에 등록된 포털 설정과 callback 주소를 정확히 비교한 뒤 중앙 사용자 자격증명의 scrypt 해시를 검증한다. 인증이 성공하면 원문이 아닌 일회성 authorization code를 callback으로 전달한다.
포털 서버는 Directory Service의 POST /api/directory/v1/auth/token에 포털 API Key와 grant_type=authorization_code를 보내 code를 교환한다. code는 해시로 저장되고 5분 후 만료되며 한 번만 소비된다. 교환 결과의 사용자 JWT는 8시간 후 만료되고 issuer directory-service, audience directory-user, 포털 식별자 azp를 포함한다.
포털별 설정
포털 설정은 관리자 화면의 도메인·URL 설정에서 저장한다. DB의 portal_configurations가 존재하면 환경변수 PORTAL_LOGIN_CLIENTS_JSON보다 우선하며, 비활성화된 DB override는 환경변수 설정으로 되살아나지 않는다. callback 주소는 저장 시 HTTPS와 정확한 URL 형식을 검사한다.
포털 온보딩 체크리스트
포털을 등록만 하고 포털 서버에 아무것도 설정하지 않으면 로그인이 조용히 실패한다. 실제 사례: FileStore 운영에 PORTAL_JWT_SECRET이 없어 callback이 받은 토큰을 검증하지 못했고, 화면에는 "로그인했는데 다시 로그인 화면"으로만 보였다.
그래서 관리자 화면의 포털 등록·설정에서 등록된 포털을 고르면 포털 쪽에 설정할 이름과 값을 표로 보여 준다(settings.portalOnboardingChecklist, 계산은 server/portalOnboardingChecklist.ts 한곳에 있다). 비밀값은 값 대신 안내만 표시한다.
| 이름 | 필수 | 설명 |
|---|---|---|
PORTAL_CONSOLE_URL | 필수 | 포털이 브라우저를 보낼 중앙 로그인 주소. 서버 Secret의 PORTAL_CONSOLE_PUBLIC_URL 값이 표에 채워진다. |
PORTAL_JWT_SECRET | 필수 | PortalConsole과 같은 값. 없거나 다르면 포털이 토큰을 검증하지 못해 로그인이 끝나지 않고 로그인 화면으로 되돌아온다. |
<앱>_CLIENT_ID | 필수 | 등록한 client_id(기본값은 포털 식별자). 예: FILE_STORE_CLIENT_ID. |
<앱>_PUBLIC_URL | 필수 | callback 기준 주소. 리버스 프록시 뒤에서는 반드시 설정한다. |
| 허용 callback URL | 필수 | 등록값과 완전 일치해야 한다. 다르면 "등록되지 않았거나 허용되지 않은 포털 callback 주소입니다."로 거절한다. |
<앱>_PORTAL_ID | 선택 | 토큰 azp 검증값. 기본값이 포털 식별자라 보통은 설정하지 않아도 된다. |
| 컨트롤 플레인 관리자 지정 | 플랫폼 계열만 | 플랫폼 계열은 로그인 자체가 관리자 기능이라 portal_admin_assignments(portalId=ui-center)에 지정된 계정만 로그인할 수 있다. |
로그인 직후 포털 로그인 화면으로 되돌아오면 포털 서버 로그에서 사유를 먼저 본다(예: FileStore는 /admin 진입 로그 file_store_admin_entry의 directorySessionReason, 부팅 경고 file_store_directory_login_misconfigured).
비밀번호 변경
인증된 포털 사용자는 Authorization: Bearer <user_jwt>와 directory:user scope로 POST /api/directory/v1/auth/password/change를 호출할 수 있다. 요청 본문은 current_password와 new_password이며 새 비밀번호는 10자 이상이어야 한다. 현재 비밀번호 검증에 실패하면 변경하지 않고, 성공 시 scrypt 해시만 저장하고 mustChangePassword를 해제한다. API Key만 가진 포털 서버는 이 사용자 전용 경로를 호출할 수 없다.
관리자는 사용자 등록·수정 화면에서 초기 비밀번호를 설정하거나 재설정할 수 있다. 이 경로도 평문을 저장하지 않고 자격증명 테이블에 해시와 변경 시각만 기록한다. API Key, JWT secret, DATABASE_URL과 같은 비밀값은 운영 Secret으로만 관리한다.
운영 점검
도메인 변경 시 관리자 화면에서 포털 기본 URL과 callback 목록을 함께 바꾼다. 포털 배포 후 callback endpoint가 실제로 같은 경로를 처리하는지 확인한다. 이후 authorization 요청, code 교환, token introspection, 잘못된 redirect URI 거부를 확인한다. DB 접속 주소는 Secret 교체 후 서버 재시작과 연결 상태 표시를 점검한다.