updated docs and such

README.md

@@ -1,12 +1,10 @@
-# Login Ldap Plugin
+# Login LDAP Plugin
 
-**This README.md file should be modified to describe the features, installation, configuration, and general usage of this plugin.**
+The **Login LDAP** Plugin for [Grav CMS](http://github.com/getgrav/grav) allows user authentication against an LDAP Server. 
-
-The **Login Ldap** Plugin is for [Grav CMS](http://github.com/getgrav/grav). Allows authentication against an LDAP Server
 
 ## Installation
 
-Installing the Login Ldap plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
+Installing the Login LDAP plugin can be done in one of two ways. The GPM (Grav Package Manager) installation method enables you to quickly and easily install the plugin with a simple terminal command, while the manual method enables you to do so via a zip file.
 
 ### GPM Installation (Preferred)
 
@@ -14,7 +12,7 @@ The simplest way to install this plugin is via the [Grav Package Manager (GPM)](
 
     bin/gpm install login-ldap
 
-This will install the Login Ldap plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/login-ldap`.
+This will install the Login LDAP plugin into your `/user/plugins` directory within Grav. Its files can be found under `/your/site/grav/user/plugins/login-ldap`.
 
 ### Manual Installation
 
@@ -23,34 +21,78 @@ To install this plugin, just download the zip version of this repository and unz
 You should now have all the plugin files under
 
     /your/site/grav/user/plugins/login-ldap
-	
+    
-> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav) and the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) to operate.
+Before configuring this plugin, you should copy the `user/plugins/login-ldap/login-ldap.yaml` to `user/config/plugins/login-ldap.yaml` and only edit that copy.    
 
-### Admin Plugin
+### Admin Installation
 
-If you use the admin plugin, you can install directly through the admin plugin by browsing the `Plugins` tab and clicking on the `Add` button.
+If you use the admin plugin, you can install directly through the admin plugin by browsing the to `Plugins` in the sidebar menu and clicking on the `Add` button.
 
-## Configuration
+Configuring the Login LDAP plugin is as easy as navigating to the `Plugins` manager, and editing the configuration options.
 
-Before configuring this plugin, you should copy the `user/plugins/login-ldap/login-ldap.yaml` to `user/config/plugins/login-ldap.yaml` and only edit that copy.
+## Configuration Options
 
-Here is the default configuration and an explanation of available options:
+The default configuration and an explanation of available options:
 
 ```yaml
 enabled: true
+host:
+port: 389
+version: 3
+ssl: false
+start_tls: false
+opt_referrals: false
+user_dn: uid=[username],dc=company,dc=com
+search_dn: dc=company,dc=com
+map_username: uid
+map_fullname: givenName lastName
+map_email: mail
+
+save_grav_user: false
+store_ldap_data: false
+default_access_levels:
+  groups: ldap_users
+  access:
+    site:
+      login: 'true'
 ```
 
-Note that if you use the admin plugin, a file with your configuration, and named login-ldap.yaml will be saved in the `user/config/plugins/` folder once the configuration is saved in the admin.
+### Server Settings
+
+|Key                   |Description                 | Values |
+|:---------------------|:---------------------------|:-------|
+|enabled|Enables the plugin | [default: **true**] \| false|
+|host|The DNS name or IP address of your LDAP server | e.g. ldap.yourcompany.com |
+|port|The TCP port of the host that the LDAP server runs under |  [default: **389**]|
+|version|LDAP Version 3 is most popular (only change this if you know what you are doing) | [default: **3**]  |
+|ssl|Enable SSL for the connection (typically for port 636or 3269) | true \| [default: **false**] |
+|start_tls|Negotiate TLS encryption with the LDAP server (requires all traffic to be encrypted) | true \| [default: **false**] |
+|opt_referrals|Sets the value of LDAP_OPT_REFERRALS (Set to "off" for Windows 2003 servers) | true \| [default: **false**] |
+
+### LDAP Configuration
+
+|Key                   |Description                 | Values |
+|:---------------------|:---------------------------|:-------|
+|user_dn|DN String used to authenticate a user, where `[username]` is replaced by username value entered via login | e.g. `uid=[username],dc=company,dc=com` |
+|search_dn|DN String used to retrieve user data | e.g. `ou=users,dc=company,dc=com` |
+|group_dn|DN String used to retrieve user group data [OPTIONAL] | e.g. `ou=groups,dc=company,dc=com` |
+|map_username|LDAP Attribute(s) that contains the user's username | [default: **uid**] |
+|map_fullname|LDAP Attribute(s) that contains the user's full name | [default: **givenName lastName**] |
+|map_email|LDAP Attribute(s) that contains the user's email address | [default: **mail**] |
+
+### Advanced Configuration
+
+|Key                   |Description                 | Values |
+|:---------------------|:---------------------------|:-------|
+|save_grav_user|Store the grav user account as a local YAML account | true \| [default: **false**] |
+|store_ldap_data|If storing a local Grav user, you can also store LDAP data so its available in Grav| true \| [default: **false**] |
+|default_access_levels.groups|Set a default group for all users logging in via LDAP [OPTIONAL] | e.g. `ldap_users` |
+|default_access_levels.access.site|The default access to assign to users logging in via LDAP | e.g. `site: [login: 'true']` |
+
+> Note that if you use the admin plugin, a file with your configuration will be saved in the `user/config/plugins/login-ldap.yaml`.
 
 ## Usage
 
-**Describe how to use the plugin.**
+Once properly configured, the functionality of the LDAP plugin is transparent to the user.  A user will be able to login via the normal login process and have access based on their account setup. 
 
-## Credits
-
-**Did you incorporate third-party code? Want to thank somebody?**
-
-## To Do
-
-- [ ] Future plans, if any
 

blueprints.yaml

@@ -12,6 +12,9 @@ bugs: https://github.com/trilbymedia/grav-plugin-login-ldap/issues
 docs: https://github.com/trilbymedia/grav-plugin-login-ldap/blob/develop/README.md
 license: MIT
 
+dependencies:
+  - { name: login, version: '>=2.6.3' }
+
 form:
   validation: strict
   fields:
@@ -38,6 +41,7 @@ form:
           label: Host
           size: large
           help: Host name of the LDAP server
+          placeholder: ldap.yourcompany.com
           validate:
             required: true
 
@@ -103,7 +107,7 @@ form:
 
         user_dn:
           type: text
-          label: User Search DN
+          label: User DN
           size: large
           placeholder: uid=[username],dc=company,dc=com
           help: String used to authenticate a user, where [username] is directly replaced by user value entered via login
@@ -112,10 +116,19 @@ form:
 
         search_dn:
           type: text
-          label: User Data DN
+          label: User Search DN
           size: large
-          placeholder: dc=company,dc=com
+          placeholder: ou=users,dc=company,dc=com
           help: String used to retrieve user data. If not provided, extra LDAP user data will not be stored in Grav user account file
+          validate:
+            required: true
+
+        group_dn:
+          type: text
+          label: Group Search DN
+          size: large
+          placeholder: ou=groups,dc=company,dc=com
+          help: String used to retrieve user group data. If not provided, extra LDAP group data will not be stored in Grav user account file
 
         map_username:
           type: text
@@ -165,7 +178,7 @@ form:
         store_ldap_data:
           type: toggle
           label: Store LDAP data
-          help: If sotring a local Grav user, you can also store LDAP data to use in Grav
+          help: If storing a local Grav user, you can also store LDAP data to use in Grav
           highlight: 0
           default: 0
           options:

login-ldap.php

@@ -81,6 +81,10 @@ class LoginLDAPPlugin extends Plugin
         $start_tls      = $this->config->get('plugins.login-ldap.start_tls');
         $opt_referrals  = $this->config->get('plugins.login-ldap.opt_referrals');
 
+        if (is_null($host)) {
+            throw new ConnectionException('FATAL: LDAP host entry missing in plugin configuration...');
+        }
+
         // Set Encryption
         if ((bool) $ssl) {
             $encryption = 'ssl';

login-ldap.yaml

@@ -6,7 +6,8 @@ ssl: false
 start_tls: false
 opt_referrals: false
 user_dn: uid=[username],dc=company,dc=com
-search_dn: dc=company,dc=com
+search_dn: ou=users,dc=company,dc=com
+group_dn: ou=groups,dc=company,dc=com
 map_username: uid
 map_fullname: givenName lastName
 map_email: mail