Merge pull request #2492 from agilgur5/master

docs(ldap): Clarify LDAP features and sample config

docs/README.md

@@ -15,4 +15,4 @@ $ cd docs
 $ make docs
 ```
 
-Open [localhost:8100](http://localhost:8180) to view the docs.
+Open [localhost:8180](http://localhost:8180) to view the docs.

docs/sources/installation/configuration.md

@@ -325,12 +325,12 @@ When enabled is `true` (default) the http api will accept basic authentication.
 
 ## [auth.ldap]
 ### enabled
-Set to `true` to enable ldap integration (default: `false`)
+Set to `true` to enable LDAP integration (default: `false`)
 
 ### config_file
-Path to the ldap specific configuration file (default: `/etc/grafana/ldap.toml`)
+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.
+> For details on LDAP Configuration, go to the [LDAP Integration](ldap.md) page.
 
 <hr>
 

docs/sources/installation/ldap.md

@@ -6,12 +6,12 @@ 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.
+Grafana 2.1 ships with a strong LDAP integration feature. The LDAP integration in Grafana allows your
+Grafana 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
+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
@@ -21,13 +21,13 @@ specific configuration file (default: `/etc/grafana/ldap.toml`).
 verbose_logging = false
 
 [[servers]]
-# Ldap server host
+# LDAP server host
 host = "127.0.0.1"
-# Default port is 389 or 636 if use_ssl = true
+# Usual port is 389, or, if TLS is supported, 636
 port = 389
-# Set to true if ldap server supports TLS
+# Set to true if LDAP server supports TLS
 use_ssl = false
-# set to true if you want to skip ssl cert validation
+# set to true if you want to skip SSL cert validation
 ssl_skip_verify = false
 
 # Search user bind dn
@@ -40,7 +40,7 @@ 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
+# Map LDAP user attributes to Grafana user attributes
 [servers.attributes]
 name = "givenName"
 surname = "sn"
@@ -48,26 +48,26 @@ username = "cn"
 member_of = "memberOf"
 email =  "email"
 
-# Map ldap groups to grafana org roles
+# 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
+# The Grafana organization database id, optional, if left out, the default org (id 1) will be used
 # org_id = 1
 
-[[servers.ldap_group_to_org_role_mappings]]
+[[servers.group_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
+# 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.
+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).
 
 ```
@@ -75,7 +75,7 @@ bind_dn = "cn=admin,dc=grafana,dc=org"
 bind_password = "grafana"
 ```
 
-### Single bind Example
+### 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.
@@ -84,12 +84,12 @@ 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).
+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.
+## Group Mappings
+In `[[servers.group_mappings]]` you can map an LDAP group to a Grafana organization and role. These will be synced every time the user logs in, with LDAP being the authoratative source.
+So, if you change a user's role in the Grafana Org. Users page, this change will be reset the next time the user logs in. If you change the LDAP groups of a user, the change will take effect the next time the user logs in.
+### Priority between Multiple Mappings
+The first group mapping that an LDAP user is matched to will be used for the sync. If you have LDAP users that fit multiple mappings, the topmost mapping in the TOML config will be used.