From b891677ba500e0db4af2d0836223f8774d7d570f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torkel=20=C3=96degaard?= Date: Wed, 15 Jul 2015 14:48:39 +0200 Subject: [PATCH] docs(ldap): added ldap integration docs and config examples, #1450 --- conf/ldap.toml | 15 +++- conf/sample.ini | 4 +- docs/mkdocs.yml | 1 + docs/sources/installation/configuration.md | 23 ++++++ docs/sources/installation/ldap.md | 93 ++++++++++++++++++++++ 5 files changed, 133 insertions(+), 3 deletions(-) create mode 100644 docs/sources/installation/ldap.md diff --git a/conf/ldap.toml b/conf/ldap.toml index c12f286af4d..957fc1258ba 100644 --- a/conf/ldap.toml +++ b/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" diff --git a/conf/sample.ini b/conf/sample.ini index a1c3c607e1a..5baf097ea20 100644 --- a/conf/sample.ini +++ b/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] diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 13eaf757c94..4bf9e577d51 100644 --- a/docs/mkdocs.yml +++ b/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'] diff --git a/docs/sources/installation/configuration.md b/docs/sources/installation/configuration.md index 6310ccb7973..e35bd164ba4 100644 --- a/docs/sources/installation/configuration.md +++ b/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 +
+ ## [auth.google] You need to create a Google project. You can do this in the [Google @@ -315,6 +317,23 @@ automatically signed up.
+## [auth.basic] +### enable +When enable is `true` (default) the http api will accept basic authentication. + +
+ +## [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. + +
+ ## [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). +
+ ## [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. +
+ ## [dashboards.json] If you have a system that automatically builds dashboards as json files you can enable this feature to have the diff --git a/docs/sources/installation/ldap.md b/docs/sources/installation/ldap.md new file mode 100644 index 00000000000..261d975886a --- /dev/null +++ b/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. +