Grafana 구성 파일로 SAML 인증 구성

Grafana 구성 파일로 SAML 인증 구성 (Configure SAML authentication using the Grafana configuration file)

Grafana Enterprise와 Grafana Cloud에서 사용 가능한 문서로, Grafana 구성 파일(grafana.ini)을 편집해 SAML 인증을 설정하는 방법을 단계별로 설명해 줘요. IdP 메타데이터, NameID 형식, 자동 로그인, IdP-initiated SSO 등 주요 옵션을 다룹니다.

출처: Configure SAML authentication using the Grafana configuration file

본문

참고: Grafana Enterprise와 Grafana Cloud에서 사용 가능해요. Grafana 구성에 대한 자세한 내용은 Configuration 문서를 참고하세요.

구성 파일로 Grafana의 SAML 인증을 설정하려면 다음 단계를 따르세요.

1. Grafana 구성 파일의 [auth.saml] 섹션에서 enabled를 true로 설정해요.
2. 요구사항에 맞게 SAML을 구성해요. 모든 사용 가능한 구성 옵션을 검토하세요.
3. IdP별 구성은 다음을 참고해요.
   • Okta로 SAML 구성
   • Entra ID로 SAML 구성
4. 구성 파일을 저장한 뒤 Grafana 서버를 재시작해요.

SAML이 포함된 Grafana 구성 파일 예시:

[server]
root_url = https://grafana.example.com

[auth.saml]
enabled = true
name = My IdP
auto_login = false
private_key_path = "/path/to/private_key.pem"
certificate_path = "/path/to/certificate.cert"
idp_metadata_url = "https://my-org.okta.com/app/my-application/sso/saml/metadata"
assertion_attribute_name = DisplayName
assertion_attribute_login = Login
assertion_attribute_email = Email
assertion_attribute_groups = Group

SAML Name ID

name_id_format 구성 필드는 SAML assertion에서 NameID 요소의 요청 형식을 지정해요. 기본값은 urn:oasis:names:tc:SAML:2.0:nameid-format:transient이며 구성 파일에 명시할 필요는 없어요.

Maximum issue delay (최대 지연)

SAML 응답 재생 공격과 SP(Grafana)와 IdP 사이의 내부 클록 오차를 방지해요. SP가 AuthnRequest를 발행한 시점부터 SP(Grafana)가 처리하는 시점까지의 최대 시간을 설정할 수 있어요. 지속 시간으로 지정하며, 예: max_issue_delay = 90s 또는 max_issue_delay = 1h.

Metadata valid duration (메타데이터 유효 기간)

SP 메타데이터는 인증서 회전이나 바인딩 위치 변경 등으로 언젠가 만료될 수 있어요. Grafana는 메타데이터가 얼마나 오래 유효한지 지정할 수 있게 해 줘요. validUntil 필드를 활용해 언제까지 메타데이터가 유효한지 소비자에게 알려 줘요. 지속 시간은 현재 시간에 더해져서 계산돼요. 예: metadata_valid_duration = 48h.

새 사용자 가입 허용 (Allow new user sign up)

기본적으로 SAML 인증을 사용하는 새 Grafana 사용자는 자동으로 계정이 생성돼요. 인증과 계정 생성을 분리하고 기존 계정이 있는 사용자만 SAML로 로그인하게 하려면 allow_sign_up 옵션을 false로 설정하세요.

자동 로그인 구성 (Configure automatic login)

auto_login 옵션을 true로 설정하면 로그인 화면을 건너뛰고 자동으로 로그인을 시도해요. 여러 인증 제공자가 auto login으로 설정된 경우 이 설정은 무시돼요. 자동 로그인 동작 및 트러블슈팅에 대한 자세한 내용은 Automatic login 문서를 참고하세요.

auto_login = true

허용 조직 구성 (Configure allowed organizations)

allowed_organizations 옵션으로 사용자가 Grafana에 로그인하려면 그중 적어도 하나의 조직의 구성원이어야 하는 조직 목록을 지정할 수 있어요. 사용자의 조직 목록을 SAML 속성에서 얻으려면 assertion_attribute_org 옵션을 구성해야 해요. 이 옵션은 사용자가 속한 조직 목록을 포함하는 SAML 속성을 지정해요. 공백이 포함된 값을 목록에 넣으려면 다음 JSON 문법을 사용하세요.

allowed_organizations = ["org 1", "second org"]

HTTP-Post 바인딩으로 SAML 구성

IdP가 SAML SSO에 여러 바인딩을 지원하면 Grafana는 기본적으로 HTTP-Redirect 바인딩을 사용해요. IdP가 HTTP-Post 바인딩만 지원한다면 Grafana가 IdP에 POST 요청을 시작할 수 있도록 content_security_policy_template(content_security_policy = true일 때)과 content_security_policy_report_only_template(content_security_policy_report_only = true일 때)을 업데이트해야 할 수 있어요. 이 설정들은 Grafana가 보내는 CSP(Content Security Policy) 헤더를 정의해요.

Grafana가 IdP에 POST 요청을 시작할 수 있게 하려면 Grafana 구성 파일에서 content_security_policy_template과 content_security_policy_report_only_template을 업데이트하고 form-action 지시문에 IdP 도메인을 추가하세요. 기본적으로 form-action은 self로 설정되어 Grafana와 같은 도메인으로의 POST만 허용해요. IdP 도메인으로의 POST를 허용하려면 form-action 지시문에 IdP 도메인을 포함하도록 업데이트해요. 예: form-action 'self' https://idp.example.com.

참고: Grafana Cloud 인스턴스의 경우 Grafana Support에 문의해 content_security_policy_template과 content_security_policy_report_only_template 설정을 업데이트해야 해요. IdP의 메타데이터 URL/파일을 함께 제공해야 합니다.

IdP-initiated Single Sign-On (SSO)

기본적으로 Grafana는 서비스 제공자(SP)가 시작한 로그인만 허용해요(Grafana의 로그인 페이지를 통한 SAML 로그인). 사용자가 IdP에서 Grafana로 직접 로그인하게 하려면 allow_idp_initiated 구성 옵션을 true로 설정하고, IdP 구성에 지정된 것과 같은 값으로 relay_state를 구성하세요.

IdP-initiated SSO는 보안 위험이 있어 기능을 활성화하기 전에 위험을 반드시 이해해야 해요. IdP-initiated 로그인을 사용하면 Grafana는 요청받지 않은(Solicited가 아닌) SAML 응답을 받으며, 로그인 흐름이 사용자에 의해 시작되었는지 확인할 수 없어요. 이 때문에 SAML 메시지가 도난당하거나 교체되었는지 감지하기 어려워요. 이로 인해 IdP-initiated 로그인은 로그인 CSRF(교차 사이트 요청 위조)와 MITM(중간자) 공격에 취약해요. 가능하면 IdP-initiated 로그인을 사용하지 않고 비활성화 상태로 두는 것을 권장해요.

Assertion 매핑

assertion_attribute_name은 특별한 assertion 매핑으로, 단일 키(단일 assertion 속성에 대한 매핑) 또는 $__saml{} 문법을 사용하는 변수 템플릿이 될 수 있어요. 이 속성이 잘못 구성되면 Grafana는 시작 시 오류 메시지를 기록하고 SAML 로그인을 허용하지 않아요. 템플릿의 변수가 SAML 응답에 없으면 로그인 시도 후에도 오류를 기록해요. 자세한 내용은 Assertion mapping 문서를 참고하세요.

예시:

# plain string mapping
assertion_attribute_name = displayName

# template mapping
assertion_attribute_name = $__saml{firstName} $__saml{lastName}

더 알아보기 (Learn more)

• SAML 인증 구성
• SAML 구성 옵션
• SAML UI로 구성
• Okta로 SAML 구성
• SAML 인증 트러블슈팅