본문으로 건너뛰기

서비스 클라이언트 (M2M)

외부 서비스(quant-ai, 자동화 파이프라인, 스케줄러 등)가 사용자 JWT 없이 GenD API를 호출할 수 있도록 admin UI 에서 Keycloak service-account 클라이언트를 발급·회전·관리합니다.

기존에는 Keycloak Admin Console 에 직접 접근해야 했지만, /admin/service-clients 에서 다음 작업을 자체 처리할 수 있습니다 (#654).

서비스 클라이언트 (M2M)

주요 기능​

  • 자체 발급: admin 사용자가 외부 서비스용 client_id + client_secret 을 즉시 발급합니다.
  • 권한 부여: 발급 시 viewer / analyst realm role 을 선택해 read-only 또는 query 권한을 분리합니다.
  • 시크릿 회전: 노출 시 즉시 회전(rotate)하여 이전 secret 을 무효화합니다.
  • 활성/비활성 토글: 운영 중 일시 차단이 필요하면 client 를 disable 합니다.
  • 삭제: 더 이상 사용하지 않는 client 를 영구 제거합니다.

이 페이지는 admin 사용자만 접근 가능합니다 (/api/v1/admin/service-clients).

사용 방법​

새 클라이언트 발급​

  1. 관리 > 서비스 클라이언트 메뉴로 이동합니다.
  2. 새 발급 버튼을 클릭합니다.
  3. 다음 정보를 입력합니다:
    • suffix: client_id 의 접미사 (예: quant-ai → gend-service-quant-ai)
    • 권한 role: viewer 또는 analyst
    • 설명 (선택): 용도 기록
  4. 발급 클릭 후 한 번만 표시되는 client_secret 을 안전하게 복사하여 외부 서비스에 저장합니다.

client_secret 은 발급 시점에만 노출됩니다. 닫으면 다시 확인할 수 없으니 시크릿 매니저 / Vault 에 즉시 저장하세요.

시크릿 회전​

  1. 회전이 필요한 client 의 행 > ⋯ > 회전 클릭.
  2. 새 secret 이 즉시 발급되며 모달에 한 번 노출됩니다.
  3. 이전 secret 으로 발급된 외부 서비스의 in-flight 요청은 access_token 만료 후 401 을 받습니다 (기본 30분).

활성/비활성 토글​

행 우측의 활성 스위치를 클릭하면 즉시 Keycloak 의 client enabled 플래그가 토글됩니다. 비활성 client 는 token endpoint 에서 unauthorized_client 오류로 차단됩니다.

삭제​

행 > ⋯ > 삭제. 삭제 후 같은 suffix 의 client 는 회복할 수 없으며, 동일 suffix 로 재발급 시 새로운 client_secret 이 생성됩니다.

API 엔드포인트​

메서드경로설명
GET/api/v1/admin/service-clients발급된 service client 목록 조회
POST/api/v1/admin/service-clients새 client 발급 (suffix + role)
POST/api/v1/admin/service-clients/{client_id}/rotateclient_secret 회전
PATCH/api/v1/admin/service-clients/{client_id}enabled, role, description 변경
DELETE/api/v1/admin/service-clients/{client_id}client 삭제

권한: 모두 admin realm role 필수. service account 토큰으로는 호출할 수 없습니다 (#900 참고).

외부 서비스에서 사용하기​

발급된 client_id + client_secret 으로 Keycloak token endpoint 호출:

curl -X POST "https://gend.genon.ai/auth/realms/gend/protocol/openid-connect/token" \
  -d "grant_type=client_credentials" \
  -d "client_id=gend-service-quant-ai" \
  -d "client_secret=<발급받은-secret>"

응답으로 받은 access_token 을 GenD API 호출 시 Authorization: Bearer ... 헤더에 첨부합니다. 자세한 외부 호출 예시는 M2M 서비스 계정 인증 을 참고하세요.

관련 문서​