docs(ldap): added ldap integration docs and config examples, #1450

conf/ldap.toml

@@ -1,16 +1,25 @@
-verbose_logging = true
+# Set to true to log user information returned from LDAP
+verbose_logging = false
 
 [[servers]]
+# Ldap server host
 host = "127.0.0.1"
+# Default port is 389 or 636 if use_ssl = true
 port = 389
+# Set to true if ldap server supports TLS
 use_ssl = false
 
+# Search user bind dn
 bind_dn = "cn=admin,dc=grafana,dc=org"
+# Search user bind password
 bind_password = "grafana"
 
+# Search filter, for example "(cn=%s)" or "(sAMAccountName=%s)"
 search_filter = "(cn=%s)"
+# An array of base dns to search through
 search_base_dns = ["dc=grafana,dc=org"]
 
+# Specify names of the ldap attributes your ldap uses
 [servers.attributes]
 name = "givenName"
 surname = "sn"
@@ -18,14 +27,18 @@ username = "cn"
 member_of = "memberOf"
 email =  "email"
 
+# Map ldap groups to grafana org roles
 [[servers.group_mappings]]
 group_dn = "cn=admins,dc=grafana,dc=org"
 org_role = "Admin"
+# The Grafana organization database id, optional, if left out the default org (id 1) will be used
+# org_id = 1
 
 [[server.ldap_group_to_org_role_mappings]]
 group_dn = "cn=users,dc=grafana,dc=org"
 org_role = "Editor"
 
 [[servers.group_mappings]]
+# If you want to match all (or no ldap groups) then you can use wildcard
 group_dn = "*"
 org_role = "Viewer"

conf/sample.ini

@@ -180,8 +180,8 @@
 
 #################################### Auth LDAP ##########################
 [auth.ldap]
-enabled = false
-config_file = /etc/grafana/ldap.toml
+;enabled = false
+;config_file = /etc/grafana/ldap.toml
 
 #################################### SMTP / Emailing ##########################
 [smtp]

docs/mkdocs.yml

@@ -34,6 +34,7 @@ pages:
 - ['installation/docker.md', 'Installation', 'Installing on Docker']
 
 - ['installation/configuration.md', 'Installation', 'Configuration']
+- ['installation/ldap.md', 'Installation', 'LDAP Integration']
 - ['installation/provisioning.md', 'Installation', 'Provisioning']
 - ['installation/performance.md', 'Installation', 'Performance tips']
 - ['installation/troubleshooting.md', 'Installation', 'Troubleshooting']

docs/sources/installation/configuration.md

@@ -280,6 +280,8 @@ Grafana instance. For example:
     token_url = https://github.com/login/oauth/access_token
     allow_sign_up = false
 
+<hr>
+
 ## [auth.google]
 
 You need to create a Google project. You can do this in the [Google
@@ -315,6 +317,23 @@ automatically signed up.
 
 <hr>
 
+## [auth.basic]
+### enable
+When enable is `true` (default) the http api will accept basic authentication.
+
+<hr>
+
+## [auth.ldap]
+### enable
+Set to `true` to enable ldap integration (default: `false`)
+
+### config_file
+Path to the ldap specific configuration file (default: `/etc/grafana/ldap.toml`)
+
+> For detail on LDAP Configuration, go to the [Ldap Integration](ldap.md) page.
+
+<hr>
+
 ## [session]
 
 ### provider
@@ -354,6 +373,8 @@ Set to true if you host Grafana behind HTTPs only. Defaults to `false`.
 
 How long sessions lasts in seconds. Defaults to `86400` (24 hours).
 
+<hr>
+
 ## [analytics]
 
 ### reporting_enabled
@@ -368,6 +389,8 @@ enabled. Counters are sent every 24 hours. Default value is `true`.
 If you want to track Grafana usage via Google analytics specify *your* Universal Analytics ID
 here. By default this feature is disabled.
 
+<hr>
+
 ## [dashboards.json]
 
 If you have a system that automatically builds dashboards as json files you can enable this feature to have the

docs/sources/installation/ldap.md

@@ -0,0 +1,93 @@
+---
+page_title: LDAP Integration
+page_description: LDAP Integrtaion guide for Grafana.
+page_keywords: grafana, ldap, configuration, documentation, integration
+---
+
+# LDAP Integration
+
+Grafana 2.1 ships with strong LDAP integration feature. The LDAP integration in Grafan allows your
+Grafan users to login with their LDAP credentials. You can also specify mappings between LDAP
+group memberships and Grafana Organization user roles.
+
+## Configuration
+You turn on ldap in the [main config file](configuration/#authldap) as well as specify the path to the ldap
+specific configuration file (default: `/etc/grafana/ldap.toml`).
+
+### Example config
+
+```toml
+# Set to true to log user information returned from LDAP
+verbose_logging = false
+
+[[servers]]
+# Ldap server host
+host = "127.0.0.1"
+# Default port is 389 or 636 if use_ssl = true
+port = 389
+# Set to true if ldap server supports TLS
+use_ssl = false
+
+# Search user bind dn
+bind_dn = "cn=admin,dc=grafana,dc=org"
+# Search user bind password
+bind_password = "grafana"
+
+# Search filter, for example "(cn=%s)" or "(sAMAccountName=%s)"
+search_filter = "(cn=%s)"
+# An array of base dns to search through
+search_base_dns = ["dc=grafana,dc=org"]
+
+# Specify names of the ldap attributes your ldap uses
+[servers.attributes]
+name = "givenName"
+surname = "sn"
+username = "cn"
+member_of = "memberOf"
+email =  "email"
+
+# Map ldap groups to grafana org roles
+[[servers.group_mappings]]
+group_dn = "cn=admins,dc=grafana,dc=org"
+org_role = "Admin"
+# The Grafana organization database id, optional, if left out the default org (id 1) will be used
+# org_id = 1
+
+[[server.ldap_group_to_org_role_mappings]]
+group_dn = "cn=users,dc=grafana,dc=org"
+org_role = "Editor"
+
+[[servers.group_mappings]]
+# If you want to match all (or no ldap groups) then you can use wildcard
+group_dn = "*"
+org_role = "Viewer"
+```
+
+## Bind & Bind Password
+
+By default the configuration expects you to specify a bind DN and bind password. This should be a read only user that can perform ldap searches.
+When the user DN is found a second bind is performed with the user provided username & password (in the normal Grafana login form).
+
+```
+bind_dn = "cn=admin,dc=grafana,dc=org"
+bind_password = "grafana"
+```
+
+### Single bind Example
+
+If you can provide a single bind expression that matches all possible users you can skip the second bind and bind against the user DN directly.
+This allows you to not specify a bind_password in the configuration file.
+
+```
+bind_dn = "cn=%s,o=users,dc=grafana,dc=org"
+```
+
+In this case you skip providing a `bind_password` and instead provide a `bind_dn` value with a `%s` somewhere. This will be replaced with the username
+entered in on the Grafana login page. The search filter and search bases settings are still needed to perform the ldap search to retreive the other ldap
+information (like ldap groups and email).
+
+## Ldap to Grafana Org Role Sync
+In the `[[servers.group_mappings]]` you can map a LDAP group to a grafana organization and role. These will be synced every time the user logs in. So
+if you change a users role in the Grafana Org. Users page, this change will be reset the next time the user logs in. Similarly if you
+can LDAP groups for a user in LDAP the change will take effect the next time the user logs in to Grafana.
+