Set up Grafana with LDAP authentication to connect with Active Directory, configure role-based access control for teams, and implement production-ready security policies for enterprise environments.
Prerequisites
- Active Directory server with administrative access
- Service account for LDAP binding
- SSL certificates for production deployment
What this solves
This tutorial configures Grafana to authenticate users through LDAP with Active Directory integration. You'll set up role-based access control to automatically assign permissions based on LDAP groups, eliminating manual user management while maintaining security policies across your organization.
Step-by-step installation
Update system packages
Start by updating your package manager to ensure you have the latest versions.
sudo apt update && sudo apt upgrade -y
Install Grafana
Install Grafana from the official repository to get the latest stable version with security updates.
curl -fsSL https://packages.grafana.com/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/grafana.gpg
echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] https://packages.grafana.com/oss/deb stable main" | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt update
sudo apt install -y grafana
Install LDAP dependencies
Install the required LDAP client libraries that Grafana uses to communicate with Active Directory.
sudo apt install -y ldap-utils
Test LDAP connectivity
Verify you can connect to your Active Directory server before configuring Grafana.
ldapsearch -x -H ldap://ad.example.com:389 -D "CN=grafana-ldap,CN=Users,DC=example,DC=com" -W -b "DC=example,DC=com" "(sAMAccountName=testuser)"
Create LDAP configuration
Create the LDAP configuration file that defines how Grafana connects to Active Directory and maps groups to roles.
# LDAP configuration for Active Directory integration
[[servers]]
host = "ad.example.com"
port = 389
use_ssl = false
start_tls = true
skip_verify_ssl = false
ssl_skip_verify = false
Bind credentials for service account
bind_dn = "CN=grafana-ldap,CN=Users,DC=example,DC=com"
bind_password = "SecurePassword123!"
User search configuration
search_filter = "(sAMAccountName=%s)"
search_base_dns = ["DC=example,DC=com"]
User attribute mapping
[servers.attributes]
name = "givenName"
surname = "sn"
username = "sAMAccountName"
member_of = "memberOf"
email = "mail"
Group to role mapping
[[servers.group_mappings]]
group_dn = "CN=Grafana Admins,OU=Groups,DC=example,DC=com"
org_role = "Admin"
grafana_admin = true
[[servers.group_mappings]]
group_dn = "CN=Grafana Editors,OU=Groups,DC=example,DC=com"
org_role = "Editor"
[[servers.group_mappings]]
group_dn = "CN=Grafana Viewers,OU=Groups,DC=example,DC=com"
org_role = "Viewer"
Configure Grafana main settings
Enable LDAP authentication in Grafana's main configuration and set security options.
sudo cp /etc/grafana/grafana.ini /etc/grafana/grafana.ini.backup
[auth.ldap]
enabled = true
config_file = /etc/grafana/ldap.toml
allow_sign_up = true
sync_cron = "0 0 1 *"
active_sync_enabled = true
[security]
admin_user = admin
admin_password = StrongAdminPassword123!
secret_key = SecureSecretKey123456789012345678901234567890
disable_gravatar = true
cookie_secure = true
cookie_samesite = strict
strict_transport_security = true
[server]
protocol = https
cert_file = /etc/ssl/certs/grafana.crt
cert_key = /etc/ssl/private/grafana.key
http_port = 3000
enforce_domain = true
[users]
allow_sign_up = false
allow_org_create = false
auto_assign_org = true
auto_assign_org_id = 1
auto_assign_org_role = Viewer
default_theme = dark
[auth]
disable_login_form = false
disable_signout_menu = false
oauth_auto_login = false
[log]
mode = file
level = info
format = json
Set proper file permissions
Configure secure permissions for Grafana configuration files to protect sensitive LDAP credentials.
sudo chown grafana:grafana /etc/grafana/ldap.toml
sudo chmod 640 /etc/grafana/ldap.toml
sudo chown grafana:grafana /etc/grafana/grafana.ini
sudo chmod 640 /etc/grafana/grafana.ini
Create SSL certificates
Generate SSL certificates for secure HTTPS communication. For production, use certificates from a trusted CA.
sudo mkdir -p /etc/ssl/private
sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-keyout /etc/ssl/private/grafana.key \
-out /etc/ssl/certs/grafana.crt \
-subj "/C=US/ST=State/L=City/O=Organization/CN=grafana.example.com"
sudo chown grafana:grafana /etc/ssl/private/grafana.key
sudo chown grafana:grafana /etc/ssl/certs/grafana.crt
sudo chmod 600 /etc/ssl/private/grafana.key
sudo chmod 644 /etc/ssl/certs/grafana.crt
Start and enable Grafana
Enable Grafana to start automatically on boot and start the service immediately.
sudo systemctl enable --now grafana-server
sudo systemctl status grafana-server
Configure firewall rules
Open the necessary ports for Grafana HTTPS access while maintaining security.
sudo ufw allow 3000/tcp comment 'Grafana HTTPS'
sudo ufw reload
Configure role-based access control
Create Active Directory groups
Create security groups in Active Directory that correspond to Grafana roles. These groups control user permissions.
New-ADGroup -Name "Grafana Admins" -SamAccountName "GrafanaAdmins" -GroupCategory Security -GroupScope Global -DisplayName "Grafana Administrators" -Path "OU=Groups,DC=example,DC=com"
New-ADGroup -Name "Grafana Editors" -SamAccountName "GrafanaEditors" -GroupCategory Security -GroupScope Global -DisplayName "Grafana Editors" -Path "OU=Groups,DC=example,DC=com"
New-ADGroup -Name "Grafana Viewers" -SamAccountName "GrafanaViewers" -GroupCategory Security -GroupScope Global -DisplayName "Grafana Viewers" -Path "OU=Groups,DC=example,DC=com"
Add users to groups
Assign users to the appropriate Grafana groups based on their required access level.
Add-ADGroupMember -Identity "Grafana Admins" -Members "john.doe"
Add-ADGroupMember -Identity "Grafana Editors" -Members "jane.smith","bob.wilson"
Add-ADGroupMember -Identity "Grafana Viewers" -Members "alice.brown","charlie.davis"
Configure organization-level permissions
Set up additional RBAC configurations for multiple organizations if needed.
# Additional organization mappings
[[servers.group_mappings]]
group_dn = "CN=DevOps Team,OU=Groups,DC=example,DC=com"
org_role = "Editor"
org_id = 1
[[servers.group_mappings]]
group_dn = "CN=Security Team,OU=Groups,DC=example,DC=com"
org_role = "Admin"
org_id = 1
[[servers.group_mappings]]
group_dn = "CN=Business Users,OU=Groups,DC=example,DC=com"
org_role = "Viewer"
org_id = 2
Test LDAP authentication
Use Grafana's LDAP debug tool to test the configuration before users attempt to log in.
sudo grafana cli admin ldap-test --username testuser --password TestPassword123!
sudo grafana cli admin ldap-sync --username testuser
Verify your setup
sudo systemctl status grafana-server
curl -k https://localhost:3000/api/health
sudo journalctl -u grafana-server -f
Access Grafana at https://your-server:3000 and test login with an Active Directory user account. Check that users are assigned the correct roles based on their group membership.
You can also monitor LDAP authentication in real-time by watching the logs while users log in. This helps verify group mappings are working correctly.
Common issues
| Symptom | Cause | Fix |
|---|---|---|
| LDAP bind fails | Incorrect bind DN or password | Test with ldapsearch command and verify service account credentials |
| Users can't authenticate | Wrong search base or filter | Check search_base_dns matches your domain structure |
| Wrong permissions assigned | Group DN mismatch | Use ldapsearch to find exact group DN and update ldap.toml |
| SSL/TLS connection fails | Certificate issues | Set skip_verify_ssl = true for testing, fix certificates for production |
| Users not syncing | Sync schedule not running | Check sync_cron setting and manually sync with grafana cli admin ldap-sync |
| Permission denied errors | Wrong file ownership | Ensure grafana user owns config files: chown grafana:grafana /etc/grafana/ldap.toml |
Next steps
- Secure Grafana with OAuth authentication and RBAC integration
- Setup Grafana alerting with Slack and Microsoft Teams integration
- Configure advanced Grafana dashboards and alerting with Prometheus integration
- Configure automated LDAP group synchronization with role updates
- Implement Grafana multi-tenancy with LDAP organization mapping
Running this in production?
Automated install script
Run this to automate the entire setup
#!/usr/bin/env bash
set -euo pipefail
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
NC='\033[0m'
# Global variables
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
LDAP_SERVER=""
BIND_DN=""
SEARCH_BASE=""
ADMIN_GROUP=""
EDITOR_GROUP=""
VIEWER_GROUP=""
# Usage information
usage() {
echo -e "${BLUE}Usage: $0 [OPTIONS]${NC}"
echo "Configure Grafana with LDAP authentication and role-based access control"
echo
echo "Required arguments:"
echo " --ldap-server SERVER LDAP server hostname or IP"
echo " --bind-dn DN Bind DN for LDAP authentication"
echo " --search-base BASE LDAP search base"
echo " --admin-group GROUP LDAP group for admin users"
echo " --editor-group GROUP LDAP group for editor users"
echo " --viewer-group GROUP LDAP group for viewer users"
echo
echo "Example:"
echo " $0 --ldap-server ldap.company.com --bind-dn 'CN=grafana,OU=Service Accounts,DC=company,DC=com' \\"
echo " --search-base 'DC=company,DC=com' --admin-group 'CN=GrafanaAdmins,OU=Groups,DC=company,DC=com' \\"
echo " --editor-group 'CN=GrafanaEditors,OU=Groups,DC=company,DC=com' \\"
echo " --viewer-group 'CN=GrafanaViewers,OU=Groups,DC=company,DC=com'"
exit 1
}
# Logging functions
log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
# Cleanup on failure
cleanup() {
local exit_code=$?
if [ $exit_code -ne 0 ]; then
log_error "Installation failed. Performing cleanup..."
systemctl stop grafana-server 2>/dev/null || true
systemctl disable grafana-server 2>/dev/null || true
fi
}
trap cleanup ERR
# Check if running as root or with sudo
check_privileges() {
if [ "$EUID" -ne 0 ]; then
log_error "Please run this script as root or with sudo"
exit 1
fi
}
# Auto-detect distribution
detect_distro() {
if [ ! -f /etc/os-release ]; then
log_error "/etc/os-release not found. Cannot detect distribution."
exit 1
fi
. /etc/os-release
case "$ID" in
ubuntu|debian)
PKG_MGR="apt"
PKG_UPDATE="apt update"
PKG_INSTALL="apt install -y"
PKG_UPGRADE="apt upgrade -y"
;;
almalinux|rocky|centos|rhel|ol)
PKG_MGR="dnf"
PKG_UPDATE="dnf check-update || true"
PKG_INSTALL="dnf install -y"
PKG_UPGRADE="dnf update -y"
;;
fedora)
PKG_MGR="dnf"
PKG_UPDATE="dnf check-update || true"
PKG_INSTALL="dnf install -y"
PKG_UPGRADE="dnf update -y"
;;
amzn)
PKG_MGR="yum"
PKG_UPDATE="yum check-update || true"
PKG_INSTALL="yum install -y"
PKG_UPGRADE="yum update -y"
;;
*)
log_error "Unsupported distribution: $ID"
exit 1
;;
esac
log_info "Detected distribution: $ID ($VERSION_ID)"
}
# Parse command line arguments
parse_args() {
while [[ $# -gt 0 ]]; do
case $1 in
--ldap-server)
LDAP_SERVER="$2"
shift 2
;;
--bind-dn)
BIND_DN="$2"
shift 2
;;
--search-base)
SEARCH_BASE="$2"
shift 2
;;
--admin-group)
ADMIN_GROUP="$2"
shift 2
;;
--editor-group)
EDITOR_GROUP="$2"
shift 2
;;
--viewer-group)
VIEWER_GROUP="$2"
shift 2
;;
-h|--help)
usage
;;
*)
log_error "Unknown option: $1"
usage
;;
esac
done
# Validate required arguments
if [[ -z "$LDAP_SERVER" || -z "$BIND_DN" || -z "$SEARCH_BASE" ||
-z "$ADMIN_GROUP" || -z "$EDITOR_GROUP" || -z "$VIEWER_GROUP" ]]; then
log_error "All required arguments must be provided"
usage
fi
}
# Update system packages
update_system() {
echo "[1/6] Updating system packages..."
$PKG_UPDATE
$PKG_UPGRADE
log_info "System packages updated successfully"
}
# Install required dependencies
install_dependencies() {
echo "[2/6] Installing dependencies..."
case "$PKG_MGR" in
apt)
$PKG_INSTALL curl gnupg2 software-properties-common
;;
dnf|yum)
$PKG_INSTALL curl gnupg2
;;
esac
log_info "Dependencies installed successfully"
}
# Install Grafana
install_grafana() {
echo "[3/6] Installing Grafana..."
case "$PKG_MGR" in
apt)
# Add Grafana GPG key and repository
curl -fsSL https://packages.grafana.com/gpg.key | gpg --dearmor -o /usr/share/keyrings/grafana.gpg
echo "deb [signed-by=/usr/share/keyrings/grafana.gpg] https://packages.grafana.com/oss/deb stable main" > /etc/apt/sources.list.d/grafana.list
$PKG_UPDATE
$PKG_INSTALL grafana
;;
dnf|yum)
# Create Grafana repository file
cat > /etc/yum.repos.d/grafana.repo << 'EOF'
[grafana]
name=grafana
baseurl=https://packages.grafana.com/oss/rpm
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=https://packages.grafana.com/gpg.key
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
EOF
$PKG_INSTALL grafana
;;
esac
log_info "Grafana installed successfully"
}
# Configure LDAP authentication
configure_ldap() {
echo "[4/6] Configuring LDAP authentication..."
# Create LDAP configuration file
cat > /etc/grafana/ldap.toml << EOF
# LDAP Configuration for Grafana
[[servers]]
host = "$LDAP_SERVER"
port = 389
use_ssl = false
start_tls = true
ssl_skip_verify = false
bind_dn = "$BIND_DN"
bind_password = ''
search_filter = "(sAMAccountName=%s)"
search_base_dns = ["$SEARCH_BASE"]
[servers.attributes]
name = "givenName"
surname = "sn"
username = "sAMAccountName"
member_of = "memberOf"
email = "mail"
# Group mappings
[[servers.group_mappings]]
group_dn = "$ADMIN_GROUP"
org_role = "Admin"
grafana_admin = true
[[servers.group_mappings]]
group_dn = "$EDITOR_GROUP"
org_role = "Editor"
grafana_admin = false
[[servers.group_mappings]]
group_dn = "$VIEWER_GROUP"
org_role = "Viewer"
grafana_admin = false
EOF
# Set correct permissions
chown root:grafana /etc/grafana/ldap.toml
chmod 640 /etc/grafana/ldap.toml
log_info "LDAP configuration created successfully"
}
# Configure Grafana main settings
configure_grafana() {
echo "[5/6] Configuring Grafana settings..."
# Backup original configuration
cp /etc/grafana/grafana.ini /etc/grafana/grafana.ini.backup
# Update Grafana configuration to enable LDAP
cat >> /etc/grafana/grafana.ini << 'EOF'
#################################### Auth LDAP ##########################
[auth.ldap]
enabled = true
config_file = /etc/grafana/ldap.toml
allow_sign_up = true
[users]
auto_assign_org = true
auto_assign_org_id = 1
auto_assign_org_role = Viewer
EOF
log_info "Grafana configuration updated successfully"
}
# Start and enable services
start_services() {
echo "[6/6] Starting and enabling Grafana service..."
# Enable and start Grafana
systemctl daemon-reload
systemctl enable grafana-server
systemctl start grafana-server
# Wait for service to start
sleep 5
# Configure firewall if firewalld is active
if systemctl is-active --quiet firewalld; then
firewall-cmd --permanent --add-port=3000/tcp
firewall-cmd --reload
log_info "Firewall configured to allow Grafana (port 3000)"
fi
log_info "Grafana service started and enabled successfully"
}
# Verify installation
verify_installation() {
echo
echo "=== Installation Verification ==="
# Check service status
if systemctl is-active --quiet grafana-server; then
log_info "✓ Grafana service is running"
else
log_error "✗ Grafana service is not running"
return 1
fi
# Check if Grafana is listening on port 3000
if ss -tlnp | grep -q ":3000"; then
log_info "✓ Grafana is listening on port 3000"
else
log_error "✗ Grafana is not listening on port 3000"
return 1
fi
# Check LDAP configuration file
if [ -f /etc/grafana/ldap.toml ]; then
log_info "✓ LDAP configuration file exists"
else
log_error "✗ LDAP configuration file missing"
return 1
fi
echo
echo -e "${GREEN}=== Installation Complete! ===${NC}"
echo
echo "Next steps:"
echo "1. Access Grafana at: http://$(hostname -I | awk '{print $1}'):3000"
echo "2. Default admin credentials: admin/admin (change on first login)"
echo "3. Configure LDAP bind password in /etc/grafana/ldap.toml"
echo "4. Test LDAP authentication with your Active Directory users"
echo
echo "Configuration files:"
echo "- Grafana config: /etc/grafana/grafana.ini"
echo "- LDAP config: /etc/grafana/ldap.toml"
echo "- Logs: /var/log/grafana/grafana.log"
}
# Main execution
main() {
check_privileges
detect_distro
parse_args "$@"
log_info "Starting Grafana LDAP authentication setup..."
update_system
install_dependencies
install_grafana
configure_ldap
configure_grafana
start_services
verify_installation
log_info "Grafana LDAP authentication setup completed successfully!"
}
main "$@"
Review the script before running. Execute with: bash install.sh