Grafana의 SAML 인증

Grafana의 SAML 인증 (SAML authentication in Grafana)

SAML 인증 통합은 Grafana 사용자가 외부 SAML 2.0 Identity Provider(IdP)로 로그인하게 해줘요. 이를 활성화하면 Grafana가 인증 흐름에서 Service Provider(SP)가 되어 IdP와 상호작용하며 사용자 정보를 교환해요. 이 기능은 Grafana Enterprise와 Grafana Cloud에서 사용할 수 있어요.

출처: 문서

본문

Grafana에서 SAML 인증 설정 옵션

Grafana SAML 인증은 여러 방법으로 구성할 수 있어요. 구성 옵션은 동일하며, Grafana의 모든 인증 설정을 한곳에 유지하려면 Grafana 구성 파일이나 Terraform 공급자를 사용해요. Grafana Cloud 사용자는 구성 파일에 접근할 수 없으므로 다른 방법으로 SAML을 구성해야 해요.

Caution: API 또는 UI의 구성은 Grafana 구성 파일의 구성보다 우선해요. API의 SAML 설정은 구성 파일에 설정된 SAML 구성을 덮어쓸 수 있어요. Grafana가 설정의 우선순위를 결정하는 방법은 SSO Settings API 문서를 참고하세요.

사용 가능한 방법:

SSO Settings API로 SAML 구성.
SAML 사용자 인터페이스로 SAML 구성.
Grafana 구성 파일로 SAML 구성 — Grafana Cloud에서는 사용 불가.
Grafana Terraform 공급자로 SAML 구성.

Okta 또는 Entra ID를 Identity Provider로 쓰는 경우:

SAML 바인딩

Grafana는 다음 SAML 2.0 바인딩을 지원해요:

SP → IdP: HTTP-POST 바인딩, HTTP-Redirect 바인딩
IdP → SP: HTTP-POST 바인딩

요청 시작 (Request initiation)

Grafana는 SP-initiated 요청과 IdP-initiated 요청을 모두 지원해요. 기본적으로 SP-initiated 요청이 활성화돼요. IdP-initiated 로그인 활성화 지침은 "IdP-initiated Single Sign-On (SSO)" 문서를 참고하세요.

Identity Provider (IdP) 등록

SAML 통합이 올바르게 동작하려면 IdP가 Grafana가 SP임을 인지하게 해야 해요. 통합은 두 개의 핵심 엔드포인트를 제공해요:

/saml/metadata 엔드포인트: SP 메타데이터를 포함. 수동으로 다운로드·업로드하거나 IdP가 엔드포인트에서 직접 요청하게 할 수 있어요. 일부 공급자는 이를 Identifier 또는 Entity ID라고 부르며, /saml/acs 엔드포인트는 ACS(Assertion Customer Service) 콜백을 받도록 설계됐어요. 일부 공급자는 이를 SSO URL 또는 Reply URL이라고 불러요.

IdP 메타데이터

메시지 검증을 위해 IdP의 공개 부분도 정의해야 해요. SAML IdP 메타데이터 XML은 Grafana가 사용자 정보를 교환하는 위치와 방식을 정의해요. Grafana는 IdP 메타데이터를 지정하는 세 가지 방법을 지원해요:

접미사 없이 idp_metadata를 쓰면 base64 인코딩된 XML 파일 내용으로 가정.
_path 접미사와 함께 쓰면 경로로 가정하고 파일시스템에서 파일을 읽으려 시도.
_url 접미사와 함께 쓰면 URL로 가정하고 주어진 위치에서 메타데이터를 로드하려 시도.

어설션 매핑 (Assertion mapping)

SAML SSO 인증 흐름 중 Grafana는 ACS 콜백을 받아요. 콜백에는 인증 중인 사용자의 관련 정보가 SAML 응답에 포함돼요. Grafana는 응답을 파싱해 내부 데이터베이스에 사용자를 만들거나(또는 업데이트)해요. Grafana가 사용자 정보를 매핑하기 위해 어설션의 개별 속성을 봐요. 이 속성들을 Key/Value 쌍으로 생각할 수 있어요. Grafana에서 사용자를 만드는 데 필요한 데이터는 Name, Login handle, email이에요. Grafana는 이 값들에 대해 어떤 키를 볼지 수정하게 하는 구성 옵션을 제공해요.

SCIM 프로비저닝 통합

Entra ID에서 이 Grafana 애플리케이션에 SCIM 프로비저닝도 사용한다면, 원활한 동작을 위해 SAML과 SCIM 간 사용자 식별자를 정렬하는 것이 중요해요. SAML 사용자를 SCIM 프로비저닝 사용자에 연결하는 고유 식별자는 Grafana SAML 구성의 assertion_attribute_external_uid 설정으로 결정돼요. 이 설정은 SCIM 프로비저닝에 사용되는 externalId(보통 Entra ID user.objectid로 설정)와 일치해야 해요.

SAML 어설션의 일관된 식별자 보장: SCIM 프로비저닝 설정에서 Grafana의 externalId 속성에 매핑한 Entra ID의 고유 식별자(보통 user.objectid)는 SAML 어설션의 클레임으로도 전송돼야 해요. Entra ID Enterprise Application의 Single sign-on > Attributes & Claims에서 이 식별자를 제공하는 클레임을 추가하세요. 예를 들어 user.objectid에서 값을 가져오는 UserID(또는 externalId 같은 이름)라는 클레임을 추가할 수 있어요.
SCIM용 Grafana SAML 설정 구성: Grafana 구성의 [auth.saml] 섹션에서 assertion_attribute_external_uid를 이전 단계에서 구성한 SAML 클레임 이름으로 설정해요(예: userUID 또는 Entra ID가 보내는 방식에 따라 http://schemas.microsoft.com/identity/claims/objectidentifier 전체 URI). assertion_attribute_login 설정은 사용자가 로그인할 속성(예: userPrincipalName, mail)에 매핑하도록 계속 구성해야 해요.

예제 Grafana 구성:

[auth.saml]
# ... other SAML settings ...
assertion_attribute_login = http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier # Or other login attribute
assertion_attribute_external_uid = http://schemas.microsoft.com/identity/claims/objectidentifier # Or your custom claim name for user.objectid

assertion_attribute_external_uid에 지정된 값이 Entra ID에서 SAML 어설션으로 전송되는 클레임 이름과 정확히 일치하는지 확인하세요. 3. SCIM 연결 식별자와 Entra ID: 기본적으로(assertion_attribute_external_uid가 설정되지 않은 경우) Grafana는 SAML 어설션의 userUID 속성을 SCIM 연결에 사용해요. Entra ID 권장: Entra ID가 user.objectid를 클레임으로 보내도록 하고, 이 클레임 이름을 Entra ID에서 userUID로 설정하거나, 다른 클레임 이름을 쓰려면 Grafana에서 assertion_attribute_external_uid를 Entra ID에서 선택한 클레임 이름과 일치하게 설정해요.

고급 구성

고급 구성과 문제 해결은 다음 페이지를 참고하세요:

Grafana의 SAML 인증