diff --git a/README.md b/README.md index 6518833..dfc3f34 100644 --- a/README.md +++ b/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 is for [Grav CMS](http://github.com/getgrav/grav). Allows authentication against an LDAP Server +The **Login LDAP** Plugin for [Grav CMS](http://github.com/getgrav/grav) allows user 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 diff --git a/blueprints.yaml b/blueprints.yaml index d581d75..c6db021 100644 --- a/blueprints.yaml +++ b/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: diff --git a/login-ldap.php b/login-ldap.php index 5f0fd97..92459b3 100644 --- a/login-ldap.php +++ b/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'; diff --git a/login-ldap.yaml b/login-ldap.yaml index 26b6384..e49bd37 100644 --- a/login-ldap.yaml +++ b/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