Konduo Manual

한국어

English

한국어

English

Appearance

Keycloak 플러그인 ​

TLS 설정 위치 ​

TLS 모드·CA·클라이언트 인증서와 키·서버 이름·인증서 검증 설정은 보안 > TLS에 표시합니다. 주소·포트 등 실제 연결 설정은 기존 구역에 남습니다. 이 분류 변경은 필드 이름, 저장 값, 기본값, 비밀값 처리와 조건부 표시·검증을 바꾸지 않습니다.

기본 접근성 관측 ​

리소스 개요는 메트릭 소스와 별개로 접근 가능·접근 불가·접근 미확인을 표시합니다. 성공한 접속 확인은 전체 멤버, 복제, 파티션이나 작업의 정상 상태를 보장하지 않습니다. 구체적인 도메인 상태는 진단과 도메인 경보에서 확인합니다. 기존 liveness/readiness 정보는 도메인 상세 증거이며 기본 접근성 경보의 조건이 아닙니다. 미확인은 발생 중인 경보를 복구시키지 않습니다.

TLS ​

Keycloak 디스커버리와 관리 API 엔드포인트를 검증하려면 tls_ca_cert에 사설 CA 인증서(PEM)를 입력합니다. 인증서 DNS 이름이 접속 주소와 다르면 tls_server_name을 지정하고, 상호 TLS가 필요하면 tls_client_cert와 tls_client_key를 함께 입력합니다. tls_insecure_skip_verify는 서버 검증을 생략하며 기본값은 꺼짐입니다.

차트 값 의미 ​

Prometheus 대상 수집 결과를 상태 문자열로 표시하며 Keycloak 전체 건강도와 구분합니다. 대상별 결과가 다르면 불일치 관측으로 남깁니다. 클러스터 크기는 정수이며 매핑팩 v2는 서로 다른 노드 관측을 보존합니다. 퍼센트 게이지 범위는 0–100입니다.

트래픽 추세 3개는 한 행을 채웁니다. 인증·JVM·데이터베이스·캐시·워커 상세는 차트 2개씩 별도 구역으로 나누지 않고 3~4열의 연속 그리드로 표시합니다. 기존 개인화 배치와 쿼리 정의는 변경하지 않습니다.

개요는 가용성·CPU·힙·클러스터 크기를 요약하고 트래픽 추세를 보여줍니다. 런타임과 의존 자원에서는 인증 처리·JVM·DB·캐시·워커 비교를 추세 행으로 구분합니다. 전체 17개 패널과 저장된 배치는 유지하며 선택적 메트릭 부재를 정상으로 간주하지 않습니다.

Keycloak 플러그인은 Keycloak realm과 런타임 상태를 Konduo 리소스로 등록합니다. 인증 제공자 역할이 아니라, Keycloak 운영 상태와 읽기 전용 디렉터리 근거를 보여주는 리소스 플러그인입니다.

특징 ​

  • 발급자 발견, Admin API 준비 상태, 인벤토리 요약, 사용자/그룹 읽기 전용 조회를 제공합니다.
  • 리소스 대상 카드에는 발급자 URL의 /realms/{realm}에서 확인한 렐름 이름을 표시합니다. 디스커버리에 실패해도 설정한 렐름 이름은 확인할 수 있습니다.
  • Prometheus 매핑팩으로 HTTP, JVM, DB 풀, 캐시, 작업자 풀, 세션/비밀번호 해싱 신호를 연결합니다.
  • 토큰 엔드포인트와 클라이언트 세션 통계를 분리해 세션 압박을 진단합니다.
  • 진단은 발견, Admin API, 메트릭, 이력 근거를 분리해 보여줍니다.
  • 로그인 실패 근거는 최근 LOGIN_ERROR 이벤트를 제한된 범위로 읽고 식별자를 마스킹합니다.
  • 외부 IdP 준비도는 별칭, 제공자, 활성 상태, 동기화 모드, 브로커 플로우를 읽기 전용으로 요약합니다.
  • 키 교체 힌트는 렐름 키 메타데이터와 인증서 만료 정보를 안전하게 요약합니다.
  • 보안 설정 스냅샷은 현재 realm 설정과 선택한 기대 프로파일의 단순 차이만 보여줍니다.
  • 알림 규칙은 JVM 압박, DB 대기, 작업자 포화, 캐시 효율, 수집 근거를 다룹니다.

등록 전 확인 ​

  • 발급자 URL, Admin API 서비스 계정 클라이언트 ID/비밀값, realm-management 읽기 전용 역할을 준비합니다.
  • 사용자/그룹 조회에는 최소 view-realm, view-users, query-users 수준의 권한을 사용합니다.
  • 선택 진단을 사용하려면 clients, events, identity providers, keys, sessions 읽기 권한도 점검합니다.
  • 메트릭 대시보드는 Keycloak 수집 대상을 선택하는 라벨 필터가 필요합니다.

운영 팁 ​

  • 이 플러그인은 Konduo 로그인 방식을 변경하지 않습니다.
  • 디렉터리 사용자/그룹은 정규화된 응답 행이며 Konduo 신원으로 저장되지 않습니다.
  • 일반 가용성은 Core 상태 점검/프로브 상태를 기준으로 보고, 메트릭 규칙은 Keycloak 도메인 위험을 보조합니다.

운영 화면 ​

  • 렐름 개요는 발급자 발견, 토큰 엔드포인트, Admin API 준비 상태, 렐름 메타데이터를 확인하게 합니다.
  • 인벤토리 요약은 렐름, 클라이언트, 사용자, 그룹 규모를 한 번에 확인하게 하며 클라이언트 비밀값은 표시하지 않습니다.
  • 사용자/그룹 화면은 읽기 전용 디렉터리 근거로 계정 존재와 그룹 구성을 확인하는 용도입니다.
  • 대시보드는 HTTP 요청, JVM, DB 풀, 캐시, 작업자 풀, 세션, 비밀번호 해싱 관련 메트릭을 보여줍니다.
  • 진단은 발견, Admin API, 자격 증명/권한, 메트릭 수집 범위, 런타임 압박을 구분해 표시합니다.
  • 세션 압박 진단은 Admin API 권한이 부족해도 메트릭 소스 준비 상태를 계속 보여줍니다.
  • 로그인 실패 근거는 원인 요약과 제한된 이벤트 행을 제공하며 급증 탐지나 상관분석은 CE 범위가 아닙니다.
  • 외부 IdP 진단은 secret/certificate 설정값을 표시하지 않으며 실제 외부 로그인 테스트는 수행하지 않습니다.
  • 키 교체 진단은 인증서 본문, public/private key, secret material을 표시하지 않고 만료 힌트만 제공합니다.
  • 보안 설정 차이는 위험도, 보안 점수, 규정 준수 평가가 아니며 그런 평가는 CE 범위 밖입니다.

진단과 알림 관점 ​

  • 알림 규칙은 JVM 메모리, DB 접속 대기, 작업자 포화, 캐시 적중률, HTTP 오류/지연, 수집 근거를 중심으로 합니다.
  • 발급자 발견이 성공해도 Admin API 권한이 부족하면 디렉터리 보기와 일부 진단은 부분 상태가 될 수 있습니다.
  • Admin API 진단은 realm/users/groups/clients/events/IdP/keys/sessions 권한을 개별 행으로 분류합니다.
  • Keycloak 메트릭 라벨은 배포, 렐름, 클라이언트 단위가 섞일 수 있으므로 라벨 필터가 대상 렐름/런타임만 선택하는지 확인해야 합니다.
  • 선택된 모든 힙 메모리 풀에서 사용량/최대 크기 시계열이 짝을 이루고 최대 크기가 양수일 때만 힙 사용률을 표시합니다. GC 이벤트가 없으면 평균 GC 일시 정지 시간을 표시하지 않습니다. 클러스터 크기는 백분율 게이지가 아니라 현재 노드 수 상태값으로 표시합니다.
  • 디렉터리 근거는 운영 확인용이며 Konduo 사용자/역할/RBAC의 기준 원본이 아닙니다.

관리 경계 ​

  • 사용자 생성/삭제, 비밀번호 재설정, 역할 매핑, 클라이언트/렐름 설정 변경은 CE 플러그인 관리 범위가 아닙니다.
  • 보안 설정 drift는 중립적인 snapshot/diff이며 감사 리포트나 규정 준수 판단으로 사용하지 않습니다.
  • Admin API 인증 정보는 읽기 전용 최소 권한을 권장합니다.
  • 플러그인은 Keycloak 상태를 관찰하지만 Konduo의 인증 방식이나 세션 정책을 변경하지 않습니다.
  • 클라이언트 비밀값과 토큰은 민감 정보 경계 안에서만 사용하고 진단에 노출하지 않습니다.

대표 시나리오 ​

  • 로그인 장애가 의심되면 발급자 발견, Admin API 준비 상태, HTTP 오류/지연, DB 풀 대기, 작업자 포화를 함께 확인합니다.
  • 특정 사용자가 보이지 않으면 서비스 계정 역할, 렐름, 사용자 검색 권한, 페이지네이션/필터 조건을 확인합니다.
  • 캐시 효율이 낮으면 캐시 적중/미스, 클러스터 노드 상태, JVM 메모리, 최근 렐름/클라이언트 변경을 같이 봅니다.
  • 비밀번호 해싱 부담이 높으면 로그인 트래픽, 작업자 풀, CPU/JVM 압박을 묶어 판단합니다.

선택적 유휴 프로세스 종료 ​

코어의 유휴 종료 정책을 명시적으로 활성화하면 요청과 코어 참조가 모두 유휴 상태일 때 Keycloak 플러그인 프로세스를 종료할 수 있습니다. 이 플러그인은 백그라운드 작업이나 보관 중인 쿼리 결과를 갖지 않습니다. 종료 준비는 유휴 HTTP 연결을 닫고 새 상태 점검·쿼리·액션을 차단합니다. 진행 중인 요청이 있으면 준비하지 않고 기존 요청 처리를 유지합니다. 준비를 취소하면 다시 요청을 받으며 메타데이터 조회는 계속 가능합니다. 다음 허용된 요청에서 새 프로세스를 시작할 수 있습니다. Keycloak 서비스와 저장된 리소스 설정에는 영향을 주지 않습니다. 운영자가 정책을 활성화하지 않으면 기본적으로 플러그인 프로세스를 계속 실행합니다.

Keycloak Enterprise 확장 ​

TLS 설정 위치 ​

TLS 모드·CA·클라이언트 인증서와 키·서버 이름·인증서 검증 설정은 보안 > TLS에 표시합니다. 주소·포트 등 실제 연결 설정은 기존 구역에 남습니다. 이 분류 변경은 필드 이름, 저장 값, 기본값, 비밀값 처리와 조건부 표시·검증을 바꾸지 않습니다.

기본 접근성 관측 ​

리소스 개요는 메트릭 소스와 별개로 접근 가능·접근 불가·접근 미확인을 표시합니다. 성공한 접속 확인은 전체 멤버, 복제, 파티션이나 작업의 정상 상태를 보장하지 않습니다. 구체적인 도메인 상태는 진단과 도메인 경보에서 확인합니다. 기존 liveness/readiness 정보는 도메인 상세 증거이며 기본 접근성 경보의 조건이 아닙니다. 미확인은 발생 중인 경보를 복구시키지 않습니다.

TLS ​

Keycloak 디스커버리와 관리 API 엔드포인트를 검증하려면 tls_ca_cert에 사설 CA 인증서(PEM)를 입력합니다. 인증서 DNS 이름이 접속 주소와 다르면 tls_server_name을 지정하고, 상호 TLS가 필요하면 tls_client_cert와 tls_client_key를 함께 입력합니다. tls_insecure_skip_verify는 서버 검증을 생략하며 기본값은 꺼짐입니다.

차트 값 의미 ​

Prometheus 대상 수집 결과를 상태 문자열로 표시하며 Keycloak 전체 건강도와 구분합니다. 대상별 결과가 다르면 불일치 관측으로 남깁니다. 클러스터 크기는 정수이며 매핑팩 v2는 서로 다른 노드 관측을 보존합니다. 퍼센트 게이지 범위는 0–100입니다.

트래픽 추세 3개는 한 행을 채웁니다. 인증·JVM·데이터베이스·캐시·워커 상세는 차트 2개씩 별도 구역으로 나누지 않고 3~4열의 연속 그리드로 표시합니다. 기존 개인화 배치와 쿼리 정의는 변경하지 않습니다.

개요는 가용성·CPU·힙·클러스터 크기를 요약하고 트래픽 추세를 보여줍니다. 런타임과 의존 자원에서는 인증 처리·JVM·DB·캐시·워커 비교를 연속 추세 그리드로 표시합니다. 전체 17개 패널과 저장된 배치는 유지하며 선택적 메트릭 부재를 정상으로 간주하지 않습니다.

Keycloak Enterprise 확장은 Keycloak 리소스 모니터링에 MCP 설명자, 이상 징후 규칙, Admin API 진단, 메트릭 매핑을 추가합니다. 로그인은 별도의 auth-oidc 공급자가 담당하고, Keycloak 플러그인은 렐름 운영과 진단에 집중합니다.

메트릭 해석 ​

  • 선택된 모든 힙 메모리 풀에서 사용량/최대 크기 시계열이 짝을 이루고 최대 크기가 양수일 때만 힙 사용률을 표시합니다. GC 이벤트가 없으면 평균 GC 일시 정지 시간을 표시하지 않습니다. 클러스터 크기는 백분율 게이지가 아니라 현재 노드 수 상태값으로 표시합니다.

특징 ​

  • 리소스 대상 카드에는 디스커버리에 실패해도 발급자 URL에서 확인한 렐름 이름을 표시합니다.
  • MCP에서 대시보드 템플릿, 모니터링 개요, 진단, 인벤토리/세션/로그인 실패/IdP/키/보안 근거, 메트릭 매핑, 알림/이상 징후 규칙 카탈로그를 제공합니다.
  • Admin API 발견, 렐름 상태, JVM, DB 풀, 작업자, 캐시, 인증 트래픽 압박을 진단 근거로 노출합니다.
  • CE의 읽기 전용 근거 위에 Enterprise 로그인 실패 급증 상관분석과 가중 보안 설정 차이 위험도 평가를 추가합니다.
  • Prometheus 매핑팩은 Keycloak 논리 메트릭을 실제 메트릭 이름으로 연결합니다.
  • 관련 인스턴스 템플릿으로 Keycloak 렐름에서 auth-oidc 공급자 생성을 도와줍니다.

등록 전 확인 ​

  • Keycloak 기준 URL, 렐름, Admin API 접근 권한, 메트릭 엔드포인트 노출 여부를 준비합니다.
  • 로그인 연동이 필요하면 Keycloak 리소스와 별도로 auth-oidc 공급자 클라이언트를 등록합니다.
  • Admin API 서비스 계정 자격 증명과 로그인 클라이언트 자격 증명을 분리합니다.

운영 팁 ​

  • Keycloak 플러그인의 디렉터리/Admin API 경로를 로그인 처리 경로로 사용하지 않습니다.
  • 이상 징후 규칙은 메트릭 소스 연결이 있어야 의미 있는 평가가 가능합니다.
  • OIDC 로그인 장애와 Keycloak 리소스 진단 장애를 분리해 추적합니다.

운영 시나리오 ​

  • 로그인 지연이나 실패가 증가하면 렐름 상태, 작업자 포화, DB 풀, 캐시 변동, 인증 트래픽 압박을 함께 확인합니다.
  • 로그인 실패 상관분석으로 제한된 LOGIN_ERROR 근거를 선택적 기준값과 비교한 뒤 사건 확대 여부를 판단합니다.
  • 보안 위험도 평가는 가중 realm 설정 차이를 신원 정책 담당자와 검토하는 운영 보조 정보이며 법적 컴플라이언스 증명이 아닙니다.
  • Keycloak을 Konduo 로그인 공급자로도 사용할 때는 관련 인스턴스 템플릿으로 auth-oidc 인스턴스를 만들고 자격 증명 경계를 분리합니다.
  • MCP 진단은 렐름 운영 상태와 메트릭 매핑 준비 상태를 읽기 전용으로 노출해 장애 분석 에이전트가 IdP 상태를 빠르게 요약하게 합니다.

경계 ​

  • Keycloak 리소스 플러그인은 렐름 운영과 진단 담당이고, 실제 Konduo 로그인 처리는 auth-oidc 인증 플러그인이 담당합니다.
  • Admin API 자격 증명은 리소스 진단에만 사용하고 로그인 클라이언트 비밀값과 섞지 않습니다.
  • MCP 설명자는 읽기 중심이며 디렉터리 변경, secret material, Keycloak 설정 변경을 노출하지 않습니다.

MCP diagnostic execution effects ​

The run_diagnostics tool changes diagnostic execution and cooldown state. Its descriptor declares operation_class: diagnostic_lifecycle; MCP advertises readOnlyHint=false, destructiveHint=false and idempotentHint=false. Diagnostic queries retain read-only hints. Both queries and actions continue to require mcp:invoke and the existing resource permissions/audit checks. Safety hints do not change authorization or guarantee safe retries.

MCP tool input contracts ​

Discovery and admin readiness diagnostics and static catalogs accept {}. Summary, metrics, and monitoring diagnostics declare metric_source_id; historical evidence also declares lookback. Existing filter aliases remain supported for metric selection. Optional correlation baseline and expected security profile inputs retain their existing bounds.

The advertised JSON Schema is checked before plugin dispatch. Omitted optional values retain plugin defaults. Arguments do not replace resource-instance authorization; stored connection credentials are supplied by Konduo. Open schemas are retained only for existing dynamic filters or aliases, and each advertised property describes its caller-facing meaning. Plugin result shapes can vary with product/version, available evidence, and partial failures; no stable outputSchema is promised for these dynamic responses. 클라이언트와 리소스 지원 범위는 Enterprise 소스 저장소의 enterprise/backend/docs/plugin-contract.md에 정의되어 있습니다.

선택적 유휴 프로세스 종료 ​

코어의 유휴 종료 정책을 명시적으로 활성화하면 요청과 코어 참조가 모두 유휴 상태일 때 Keycloak 플러그인 프로세스를 종료할 수 있습니다. 이 플러그인은 백그라운드 작업이나 보관 중인 쿼리 결과를 갖지 않습니다. 종료 준비는 유휴 HTTP 연결을 닫고 새 상태 점검·쿼리·액션을 차단합니다. 진행 중인 요청이 있으면 준비하지 않고 기존 요청 처리를 유지합니다. 준비를 취소하면 다시 요청을 받으며 메타데이터 조회는 계속 가능합니다. 다음 허용된 요청에서 새 프로세스를 시작할 수 있습니다. Keycloak 서비스와 저장된 리소스 설정에는 영향을 주지 않습니다. 운영자가 정책을 활성화하지 않으면 기본적으로 플러그인 프로세스를 계속 실행합니다.