LDAP 인증 구성하기

LDAP 인증 구성하기 (Configure LDAP authentication)

Grafana의 LDAP 통합으로 사용자가 LDAP 자격 증명으로 로그인할 수 있어요. LDAP 그룹 멤버십과 Grafana 조직 사용자 역할 간 매핑도 지정할 수 있습니다. ldap.toml 구성 파일을 쓰고 [auth.ldap] 섹션에서 활성화하는 방법을 알려드릴게요.

참고: Enhanced LDAP 인증은 Grafana Cloud와 Grafana Enterprise에서 사용할 수 있어요.

출처: 문서

본문

지원되는 LDAP 서버

Grafana는 기본 LDAP v3 기능을 지원하는 서드파티 LDAP 라이브러리를 사용해요. OpenLDAP이나 Active Directory 등 LDAPv3 호환 서버라면 구성할 수 있어요.

LDAP 활성화

메인 구성 파일에서 LDAP를 활성화하고 LDAP 전용 구성 파일 경로(기본 /etc/grafana/ldap.toml)를 지정하세요. 활성화 후 기본 동작은 LDAP 인증 성공 시 Grafana 사용자를 자동 생성하는 것입니다. 기존 사용자만 로그인하게 하려면 [auth.ldap] 섹션에서 allow_sign_up을 false로 바꾸세요.

[auth.ldap]
# Set to `true` to enable LDAP integration (default: `false`)
enabled = true

# Path to the LDAP specific configuration file (default: `/etc/grafana/ldap.toml`)
config_file = /etc/grafana/ldap.toml

# Allow sign-up should be `true` (default) to allow Grafana to create users on successful LDAP authentication.
# If set to `false` only already existing Grafana users will be able to login.
allow_sign_up = true

조직 역할 동기화 비활성화

LDAP으로 인증하지만 역할 매핑을 쓰지 않고 조직·역할을 수동으로 할당하려면 skip_org_role_sync 옵션을 쓰세요.

[auth.ldap]
enabled = true
config_file = /etc/grafana/ldap.toml
allow_sign_up = true

# Prevent synchronizing ldap users organization roles
skip_org_role_sync = true

Grafana LDAP 구성

ldap.toml 예시:

[[servers]]
# Ldap server host (specify multiple hosts space separated)
host = "ldap.my_secure_remote_server.org"
# Default port is 389 or 636 if use_ssl = true
port = 636
# Set to true if LDAP server should use an encrypted TLS connection (either with STARTTLS or LDAPS)
use_ssl = true
# If set to true, use LDAP with STARTTLS instead of LDAPS
start_tls = false
# The value of an accepted TLS cipher. By default, this value is empty. Example value: ["TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384"])
# For a complete list of supported ciphers and TLS versions, refer to: https://go.dev/src/crypto/tls/cipher_suites.go
# Starting with Grafana v11.0 only ciphers with ECDHE support are accepted for TLS 1.2 connections.
tls_ciphers = []
# This is the minimum TLS version allowed. By default, this value is empty. Accepted values are: TLS1.1 (only for Grafana v10.4 or earlier), TLS1.2, TLS1.3.
min_tls_version = ""
# set to true if you want to skip SSL cert validation
ssl_skip_verify = false
# set to the path to your root CA certificate or leave unset to use system defaults
# root_ca_cert = "/path/to/certificate.crt"
# Authentication against LDAP servers requiring client certificates
# client_cert = "/path/to/client.crt"
# client_key = "/path/to/client.key"

# Search user bind dn
bind_dn = "cn=admin,dc=grafana,dc=org"
# Search user bind password
# If the password contains # or ; you have to wrap it with triple quotes. Ex """#password;"""
bind_password = "grafana"
# We recommend using variable expansion for the bind_password
# bind_password = '$__env{LDAP_BIND_PASSWORD}'

# Timeout in seconds. Applies to each host specified in the 'host' entry (space separated).
timeout = 10

# User search filter, for example "(cn=%s)" or "(sAMAccountName=%s)" or "(uid=%s)"
# Allow login from email or username, example "(|(sAMAccountName=%s)(userPrincipalName=%s))"
search_filter = "(cn=%s)"

# An array of base dns to search through
search_base_dns = ["dc=grafana,dc=org"]

# group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
# group_search_filter_user_attribute = "distinguishedName"
# group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]

# Specify names of the LDAP attributes your LDAP uses
[servers.attributes]
member_of = "memberOf"
email =  "email"

참고: ldap.toml 파일을 수정할 때마다 변경 사항을 적용하려면 Grafana를 재시작해야 해요.

Grafana UI 사용

Administration > Authentication > LDAP로 이동해 Grafana UI로도 LDAP을 구성할 수 있어요. 자세한 내용은 LDAP 사용자 인터페이스 문서를 참고하세요.

환경 변수 사용

TOML 구성에서 환경 변수를 보간할 수 있어요. 예: bind_password = "${LDAP_ADMIN_PASSWORD}".

Bind와 bind password

기본적으로 검색용 읽기 전용 사용자를 나타내는 bind DN과 password를 지정해야 해요. 사용자 DN을 찾으면 일반 Grafana 로그인 폼의 사용자 제공 username/password로 두 번째 bind가 수행됩니다. 모든 사용자를 매칭하는 단일 bind 표현식을 제공할 수 있다면(bind_dn = "cn=%s,o=users,dc=grafana,dc=org"처럼 %s 포함) 두 번째 bind를 건너뛰고 bind password를 생략할 수 있어요. %s는 Grafana 로그인 페이지의 username으로 치환됩니다.

POSIX 스키마

LDAP 서버가 memberOf 속성을 지원하지 않으면 다음 옵션을 추가하세요.

group_search_filter = "(&(objectClass=posixGroup)(memberUid=%s))"
group_search_base_dns = ["ou=groups,dc=grafana,dc=org"]
group_search_filter_user_attribute = "uid"

그룹 매핑

[[servers.group_mappings]]에서 LDAP 그룹을 Grafana 조직·역할에 매핑할 수 있어요. 사용자가 로그인할 때마다 동기화되며 LDAP이 권위 있는 소스입니다. LDAP 사용자가 여러 매핑에 해당하면 ldap.toml에서 가장 위의 매핑이 사용됩니다.

[[servers]]
# other settings omitted for clarity

[[servers.group_mappings]]
group_dn = "cn=superadmins,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

[[servers.group_mappings]]
group_dn = "cn=admins,dc=grafana,dc=org"
org_role = "Admin"

[[servers.group_mappings]]
group_dn = "cn=users,dc=grafana,dc=org"
org_role = "Editor"

[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"

참고: 그룹 매핑을 주석 처리하려면 해당 그룹의 헤더([[servers.group_mappings]])도 주석 처리해야 해요. 그렇지 않으면 빈 매핑으로 검증에 실패합니다.

중첩/재귀 그룹 멤버십

중첩 그룹 멤버십 사용자는 LDAP_MATCHING_RULE_IN_CHAIN을 지원하는 LDAP 서버가 필요하며, 제출된 username이 속한 그룹을 반환하도록 group_search_filter를 구성해야 해요. group_search_base_dns로 일치 그룹 위치를 지정할 수 있고, 지정하지 않으면 앞서 정의한 search_base_dns가 사용됩니다.

Active Directory 예시:

group_search_filter = "(member:1.2.840.113556.1.4.1941:=%s)"
group_search_base_dns = ["DC=mycorp,DC=mytld"]
group_search_filter_user_attribute = "dn"

group_search_filter = "(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])"
group_search_filter = "(|(member:1.2.840.113556.1.4.1941:=CN=%s,[user container/OU])(member:1.2.840.113556.1.4.1941:=CN=%s,[another user container/OU]))"
group_search_filter_user_attribute = "cn"

AD 검색에 대한 자세한 내용은 Microsoft Search Filter Syntax를 참고하세요. 문제 해결 시 [servers.attributes]의 member_of를 "dn"으로 바꾸면 디버그 활성화 때 더 정확한 그룹 멤버십을 보여줘요.

구성 예시

OpenLDAP

[[servers]]
host = "127.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

여러 LDAP 서버

Grafana는 여러 LDAP 서버로부터 정보를 받을 수 있어요. 각 서버를 별도 [[servers]] 블록으로 구성하세요.

# --- First LDAP Server ---
[[servers]]
host = "10.0.0.1"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

[[servers.group_mappings]]
group_dn = "cn=admins,ou=groups,dc=grafana,dc=org"
org_role = "Admin"
grafana_admin = true

# --- Second LDAP Server ---
[[servers]]
host = "10.0.0.2"
port = 389
use_ssl = false
start_tls = false
ssl_skip_verify = false
bind_dn = "cn=admin,dc=grafana,dc=org"
bind_password = "grafana"
search_filter = "(cn=%s)"
search_base_dns = ["ou=users,dc=grafana,dc=org"]

[servers.attributes]
member_of = "memberOf"
email =  "email"

[[servers.group_mappings]]
group_dn = "cn=editors,ou=groups,dc=grafana,dc=org"
org_role = "Editor"

[[servers.group_mappings]]
group_dn = "*"
org_role = "Viewer"

Active Directory

다음 AD 설정을 가정: IP 10.0.0.1, 도메인 CORP, DNS corp.local.

[[servers]]
host = "10.0.0.1"
port = 3269
use_ssl = true
start_tls = false
ssl_skip_verify = true
bind_dn = "CORP\\%s"
search_filter = "(sAMAccountName=%s)"
search_base_dns = ["dc=corp,dc=local"]

[servers.attributes]
member_of = "memberOf"
email =  "mail"

포트 요구사항

AD가 SSL을 지원하지 않으면 use_ssl = false와 port = 389를 쓰세요. 정확한 설정은 Microsoft 문서에서 확인하세요.

문제 해결

grafana.ini 또는 custom.ini에서 LDAP 디버그 로깅을 활성화하세요:

[log]
filters = ldap:debug

더 알아보기 (Learn more)

• LDAP UI 구성
• Grafana 구성
• 역할 기반 접근 제어
• Grafana LDAP 라이브러리 (go-ldap)