SCIM으로 사용자·팀 관리하기

SCIM으로 사용자·팀 관리하기 (Manage users and teams with SCIM)

SCIM은 사용자 라이프사이클과 팀 멤버십 작업을 자동화해 Grafana의 ID 관리를 간소화해요. 이 문서는 SCIM이 기존 Grafana 설정과 어떻게 작동하는지, 사용자 프로비저닝을 어떻게 처리하는지, 팀 동기화를 어떻게 관리하는지 설명합니다.

참고: Grafana Enterprise와 Grafana Cloud에서 사용할 수 있어요.

출처: 문서

본문

SCIM으로 할 수 있는 일:

생성부터 비활성화까지 사용자 라이프사이클 자동화
기존 사용자 관리 (IDP 자격과 연결)
팀 라이프사이클 자동화 (그룹 추가 시 팀 자동 생성, 멤버십 업데이트, 그룹 제거 시 팀 삭제)
자동 디프로비저닝으로 보안 유지
더 견고한 SCIM 그룹 동기화로 Team Sync 대체

SCIM으로 사용자 프로비저닝

SCIM은 기존 사용자 관리 방법과 함께 동작해요. 사용자는 SAML just-in-time 프로비저닝(SAML 로그인 시), Grafana UI, Terraform·Grafana API 같은 자동화 도구로도 만들 수 있습니다. 가장 일관된 관리를 위해 SCIM으로 사용자 프로비저닝을 중앙화하는 것을 권장해요.

참고: 사용자 프로비저닝에는 SCIM 구성에 user_sync_enabled = true가 필요해요. 경고: SCIM을 통해 프로비저닝된 사용자는 Grafana에서 삭제할 수 없고, IDP에서만 비활성화할 수 있어요. 사용자 관리 전략(특히 컴플라이언스·데이터 보존)을 계획할 때 중요합니다.

IDP별 구성 단계는 Entra ID로 SCIM 구성, Okta로 SCIM 구성을 참고하세요.

SCIM이 사용자를 식별하는 방법

초기 사용자 조회: 관리자가 IDP에서 Unique identifier field를 정의하면, IDP가 이 필터로 Grafana의 각 사용자를 조회하고 사용자마다 단일 결과를 기대합니다.
조회 결과 기반 신원 연결:
- 단일 일치 시: IDP가 Grafana에서 사용자의 고유 ID를 가져와 저장하고, 정보를 가져올 수 있는지 확인한 뒤 Grafana의 사용자 정보를 업데이트
- 일치 없음 시: IDP가 Grafana에서 사용자 생성을 시도. 성공하면 고유 ID를 가져와 저장. 같은 이메일의 사용자가 이미 있으면 업데이트되고 그 시점부터 SCIM이 관리
- IDP는 발견된 Grafana 사용자와 Grafana 내부 ID 간 관계를 학습 → Grafana에 External ID로 업데이트 → Grafana 인증 검증이 이 External ID를 기대하도록 업데이트
로그인 시 사용자 매칭: 사용자가 SAML로 로그인할 때 Grafana는 SCIM이 프로비저닝한 올바른 계정과 안전하게 매칭해야 해요. 두 프로세스 양쪽에서 일관된 고유 식별자(예: Entra ID의 objectId)가 필요합니다. SAML 클레임 구성, Grafana SAML의 assertion_attribute_login 설정, SCIM 매핑에서 Grafana externalId를 SAML의 동일 고유 식별자로 설정해야 해요. 자세한 내용은 SAML 구성 상세를 참고하세요.

이 과정은 이메일 변경·속성 수정으로 인한 보안 문제를 막기 위해 두 시스템 간 안전·일관된 사용자 식별을 보장합니다.

참고: 프로비저닝 중 Grafana에서 쓰임이 없는 사용자 속성은 조용히 무시됩니다.

기존 Grafana 사용자

SCIM이 External ID 매칭 과정으로 관계를 수립
IDP 자격과의 안전한 링크 생성
기존 설정·접근 모두 보존
IDP에서 할당되기 전까지 계정 활성·변경 없음 유지

다른 프로비저닝 방법의 사용자 처리

충돌을 막고 일관된 관리를 위해 SCIM 도입 시 다른 프로비저닝 방법을 비활성화하거나 제한하세요.

SAML JIT 프로비저닝: SAML 설정의 allow_sign_up 비활성화. 기존 JIT 사용자는 계속 동작하지만 SCIM으로 마이그레이션해야 함
Terraform/API 프로비저닝: 이 방법의 새 사용자 생성 중단. 기존 사용자는 마이그레이션하고 Terraform 사용자 생성 리소스 제거·보관 고려
수동 사용자 생성: UI 기반 생성을 관리자만으로 제한. 수동 생성 사용자를 SCIM으로 마이그레이션 계획

새 사용자

IDP에서 Grafana에 할당될 때 SCIM이 계정 생성
IDP 그룹 멤버십과 SAML 역할 매핑 기반 초기 접근 설정
수동 Grafana 계정 생성 불필요

역할 관리

SCIM은 사용자 동기화를 처리하지만 역할 할당은 처리하지 않아요. 역할 관리는 Role Sync로 처리하며, 역할 변경은 사용자 인증 시 적용됩니다.

기존 사용자를 SCIM 프로비저닝으로 마이그레이션

이점: 기존 사용자 설정·대시보드·권한 보존, 마이그레이션 중 접근 중단 없음, 배치 단위 점진적 마이그레이션 가능, 감사 추적·이력 데이터 유지.

단계:

IDP 준비: 모든 기존 Grafana 사용자가 IDP에 계정이 있는지 확인. 고유 식별자 필드(이메일·username·object ID)가 시스템 간 일치하도록 검증. IDP에 SCIM 앱 구성하되 아직 사용자 할당은 하지 않기
Grafana에서 SCIM 구성: SCIM 엔드포인트·인증 설정, user_sync_enabled = true 활성화, 고유 식별자 필드 구성

참고: SCIM 프로비저닝 사용자만 로그인을 제한하려면 [auth.scim]의 reject_non_provisioned_users를 활성화하세요. Cloud Portal 사용자는 이 설정과 무관하게 로그인할 수 있어요.

[auth.scim] reject_non_provisioned_users = true

매칭 메커니즘 테스트: SCIM API로 기존 사용자가 고유 식별자로 찾아지는지 확인:

curl --location 'https://{$GRAFANA_URL}/apis/scim.grafana.app/v0alpha1/namespaces/{$STACK_ID}/Users?filter=userName eq "[email protected]"' \
--header 'Authorization: Bearer glsa_x...xxxx'

각 기존 사용자에 대해 정확히 하나의 사용자 레코드가 반환되어야 해요. 4. IDP에서 사용자 할당: 기존 사용자를 IDP의 Grafana 앱에 할당. SCIM 식별 과정이 기존 사용자와 IDP 자격을 자동 연결. 충돌·오류 모니터링 5. 마이그레이션 검증: 기존 권한으로 접근 가능한지, SAML/SSO 로그인이 작동하는지, 각 사용자에 External ID가 설정되었는지 확인

고려사항: 마이그레이션 전 — Grafana DB 백업, 기존 사용자 감사, 예외(고유 식별자 불일치) 계획. 마이그레이션 중 — 로그 모니터링, 소규모 배치 처리, 사용자 커뮤니케이션. 후 — 수동 프로비저닝 비활성화, 문서 업데이트, 정기 감사.

문제 해결: 고유 식별자에 여러 사용자 발견 → 식별자 설정 검토, 중복 계정 확인, 더 구체적인 식별자 사용. 조회에서 사용자 미발견 → 식별자 값이 정확히 일치하는지, 양쪽 시스템에 사용자가 존재하는지 확인. 인증 실패 → SAML assertion assertion_attribute_external_uid가 올바른 고유 식별자를 포함하는지, SCIM·SAML 양쪽에서 같은 고유 식별자를 쓰는지 확인.

SCIM으로 팀 프로비저닝

SCIM은 Team Sync보다 강력한 자동 팀 관리 기능을 제공해요. Team Sync는 IDP 그룹을 기존 Grafana 팀에 매핑만 하지만, SCIM은 IDP의 그룹 변경에 따라 팀을 자동 생성·삭제할 수 있어요.

참고: 팀 프로비저닝에는 group_sync_enabled = true 필요. 경고: SCIM으로 프로비저닝된 팀은 Grafana에서 수동 삭제할 수 없고, IDP에서 해당 그룹을 제거해야 삭제됩니다. 수동 삭제를 원하면 SCIM 그룹 동기화를 비활성화할 수 있어요.

SCIM vs Team Sync

경고: SCIM 그룹 동기화와 Team Sync를 동시에 활성화하지 마세요(충돌 가능). Team Sync 마이그레이션 지원이 출시될 때까지는 SCIM 사용자 프로비저닝을 쓰면서 팀 관리는 Team Sync를 유지할 수 있어요.

하나의 팀 동기화 방법을 선택하세요. SCIM 그룹 동기화를 활성화하면 Team Sync를 끄고, Team Sync를 선호하면 SCIM 그룹 동기화를 켜지 마세요.

주요 차이점 (SCIM 그룹 동기화의 장점): 자동 팀 생성(IDP에 새 그룹 추가 시), 자동 팀 삭제(IDP에서 그룹 삭제 시), 실시간 업데이트(그룹 할당 변경 즉시 반영), 간편한 관리(Grafana에서 수동 팀 생성 불필요).

팀 동기화 동작: IDP에서 사용자를 그룹에 할당 → SCIM이 멤버십 변경 감지 → 새 IDP 그룹에 Grafana 팀 생성·사용자 매핑, 그룹 멤버십 변경 시 사용자 제거 → 지속적으로 멤버십 동기화.

SCIM으로 사용자·팀 관리하기