From 5e5684f2cd7077c12663d97ac5e563bdc603d3aa Mon Sep 17 00:00:00 2001 From: Tony Murray Date: Wed, 13 Sep 2017 13:51:39 -0500 Subject: [PATCH] docs: Reorganize authentication documentation (#7329) Audit headers Fix a few mistakes Try to clarify some items --- doc/Extensions/Authentication.md | 244 +++++++++++++++++-------------- 1 file changed, 131 insertions(+), 113 deletions(-) diff --git a/doc/Extensions/Authentication.md b/doc/Extensions/Authentication.md index 8803b0ff78..7ebf21bd62 100644 --- a/doc/Extensions/Authentication.md +++ b/doc/Extensions/Authentication.md @@ -4,19 +4,27 @@ source: Extensions/Authentication.md LibreNMS supports multiple authentication modules along with [Two Factor Auth](http://docs.librenms.org/Extensions/Two-Factor-Auth/). Here we will provide configuration details for these modules. -#### Available authentication modules +### Available authentication modules -- MySQL: mysql +- MySQL: [mysql](#mysql-authentication) -- LDAP: ldap +- Active Directory: [active_directory](#active-directory-authentication) -- Active Directory: active_directory +- LDAP: [ldap](#ldap-authentication) -- HTTP Auth: http-auth +- Radius: [radius](#radius-authentication) -- Radius: radius +- HTTP Auth: [http-auth](#http-authentication), [ad_authorization](#http-authentication-ad-authorization), [ldap_authorization](#http-authentication-ldap-authorization) -#### User levels +### Enable authentication module + +To enable a particular authentication module you need to set this up in config.php. + +```php +$config['auth_mechanism'] = "mysql"; +``` + +### User levels - 1: Normal User. You will need to assign device / port permissions for users at this level. @@ -26,33 +34,26 @@ Here we will provide configuration details for these modules. - 11: Demo Account. Provides full read/write with certain restrictions (i.e can't delete devices). -#### Enable authentication module - -To enable a particular authentication module you need to set this up in config.php. - -```php -$config['auth_mechanism'] = "mysql"; -``` - -#### Note for SELinux users +### Note for SELinux users When using SELinux on the LibreNMS server, you need to allow Apache (httpd) to connect LDAP/Active Directory server, this is disabled by default. You can use SELinux Booleans to allow network access to LDAP resources with this command: ```shell setsebool -P httpd_can_connect_ldap=1 ``` -#### Testing authentication +### Testing authentication You can test authentication with this script: ```shell ./scripts/auth_test.php ``` Enable debug output to troubleshoot issues -### MySQL Authentication + +# MySQL Authentication Config option: `mysql` -This is default option with LibreNMS so you should have already got the configuration setup. +This is default option with LibreNMS so you should have already have the configuration setup. ```php $config['db_host'] = "HOSTNAME"; @@ -61,28 +62,73 @@ $config['db_pass'] = "DBPASS"; $config['db_name'] = "DBNAME"; ``` -### HTTP Authentication -Config option: `http-auth` +# Active Directory Authentication -LibreNMS will expect the user to have authenticated via your webservice already. At this stage it will need to assign a -userlevel for that user which is done in one of two ways: +Config option: `active_directory` -- A user exists in MySQL still where the usernames match up. +Install __php_ldap__ or __php7.0-ldap__, making sure to install the same version as PHP. + +If you have issues with secure LDAP try setting `$config['auth_ad_check_certificates']` to `0`, this will ignore certificate errors. + +### Require actual membership of the configured groups + +If you set `$config['auth_ad_require_groupmembership']` to 1, the authenticated user has to be a member of the specific group. +Otherwise all users can authenticate, and will be either level 0 or you may set `$config['auth_ad_global_read']` to 1 and all users will have read only access unless otherwise specified. + +#### Old account cleanup +Cleanup of old accounts is done by checking the authlog. You will need to set the number of days when old accounts will be purged AUTOMATICALLY by daily.sh. + +> Please ensure that you set the $config['authlog_purge'] value to be greater than $config['active_directory']['users_purge'] otherwise old users won't be removed. + +### Sample configuration -- A global guest user (which still needs to be added into MySQL: -```php -$config['http_auth_guest'] = "guest"; ``` -This will then assign the userlevel for guest to all authenticated users. +$config['auth_mechanism'] = "active_directory"; +$config['auth_ad_url'] = "ldaps://"; // you can add multiple servers, separated by a space +$config['auth_ad_domain'] = ""; +$config['auth_ad_base_dn'] = ""; // groups and users must be under this dn +$config['auth_ad_check_certificates'] = true; // require a valid ssl certificate +$config['auth_ad_binduser'] = 'examplebinduser'; +$config['auth_ad_bindpassword'] = 'examplepassword'; +$config['auth_ad_timeout'] = 5; // time to wait before giving up (or trying the next server) +$config['auth_ad_debug'] = false; // enable for verbose debug messages +$config['active_directory']['users_purge'] = 30; // purge users who haven't logged in for 30 days. +$config['auth_ad_require_groupmembership'] = false; // require users to be members of a group listed below +$config['auth_ad_groups']['']['level'] = 10; +$config['auth_ad_groups']['']['level'] = 7; +``` -### LDAP Authentication +Replace `` with your Active Directory admin-user group and `` with your standard user group. +It is __highly suggested__ to create a bind user, otherwise "remember me", alerting users, and the API will not work. + +### Active Directory redundancy + +You can set two Active Directory servers by editing the `$config['auth_ad_url']` like this example: + +``` +$config['auth_ad_url'] = "ldaps://dc1.example.com ldaps://dc2.example.com"; +``` + +### Active Directory LDAP filters + +You can add an LDAP filter to be ANDed with the builtin user filter (`(sAMAccountName=$username)`). + +The defaults are: + +``` +$config['auth_ad_user_filter'] = "(objectclass=user)"; +$config['auth_ad_group_filter'] = "(objectclass=group)"; +``` + +This yields `(&(objectclass=user)(sAMAccountName=$username))` for the user filter and `(&(objectclass=group)(sAMAccountName=$group))` for the group filter. + + +# LDAP Authentication Config option: `ldap` -This one is a little more complicated :) - -First of all, install ___php-ldap___ for CentOS/RHEL or ___php5-ldap___ for Ubuntu/Debian. +Install __php_ldap__ or __php7.0-ldap__, making sure to install the same version as PHP. ```php $config['auth_ldap_version'] = 3; # v2 or v3 @@ -100,16 +146,23 @@ $config['auth_ldap_uid_attribute'] = 'uidnumber'; ``` Typically auth_ldap_suffix, auth_ldap_group, auth_ldap_groupbase, auth_ldap_groups are what's required to be configured. -It is highly suggested to create a bind user, other wise "remember me", alerting AD users, and the API will not work. + +### LDAP server redundancy + +You can set two LDAP servers by editing the `$config['auth_ldap_server']` like this example: + +``` +$config['auth_ldap_server'] = "ldaps://dir1.example.com ldaps://dir2.example.com"; +``` An example config setup for use with Jumpcloud LDAP as a service is: ```php -$config['auth_mechanism'] = "ldap"; # default, other options: ldap, http-auth +$config['auth_mechanism'] = "ldap"; unset($config['auth_ldap_group']); unset($config['auth_ldap_groups']); $config['auth_ldap_groups']['librenms']['level'] = 10; -$config['auth_ldap_version'] = 3; # v2 or v3 +$config['auth_ldap_version'] = 3; $config['auth_ldap_server'] = "ldap.jumpcloud.com"; $config['auth_ldap_port'] = 389; $config['auth_ldap_prefix'] = "uid="; @@ -120,87 +173,11 @@ $config['auth_ldap_groupmemberattr'] = "memberUid"; Replace {id} with the unique ID provided by Jumpcloud. -### HTTP Authentication / LDAP Authorization -Config option: `ldap-authorization` - -This module is a combination of ___http-auth___ and ___ldap___ - -LibreNMS will expect the user to have authenticated via your webservice already (e.g. using Kerberos Authentication in Apache) but will use LDAP to determine and assign the userlevel of a user. -The userlevel will be calculated by using LDAP group membership information as the ___ldap___ module does. - -The configuration is the same as for the ___ldap___ module with one extra option: auth_ldap_cache_ttl. -This option allows to control how long user information (user_exists, userid, userlevel) are cached within the PHP Session. -The default value is 300 seconds. -To disabled this caching (highly discourage) set this option to 0. - -```php -$config['auth_ldap_cache_ttl'] = 300; -``` - -### Active Directory Authentication - -Config option: `active_directory` - -This is similar to LDAP Authentication. Install __php_ldap__ for CentOS/RHEL or __php5-ldap__ for Debian/Ubuntu. - -If you have issues with secure LDAP try setting `$config['auth_ad_check_certificates']` to `0`. - -##### Require actual membership of the configured groups - -If you set ```$config['auth_ad_require_groupmembership']``` to 1, the authenticated user has to be a member of the specific group. Otherwise all users can authenticate, and will be either level 0 or you may set ```$config['auth_ad_global_read']``` to 1 and all users will have read only access unless otherwise specified. - -> Cleanup of old accounts is done using the authlog. You will need to set the cleanup date for when old accounts will be purged which will happen AUTOMATICALLY. -> Please ensure that you set the $config['authlog_purge'] value to be greater than $config['active_directory]['users_purge'] otherwise old users won't be removed. - - -##### Sample configuration - -``` -$config['auth_ad_url'] = "ldaps://"; // you can add multiple servers, separated by a space -$config['auth_ad_domain'] = ""; -$config['auth_ad_base_dn'] = ""; -$config['auth_ad_check_certificates'] = true; // require a valid ssl certificate -$config['auth_ad_binduser'] = 'examplebinduser'; -$config['auth_ad_bindpassword'] = 'examplepassword'; -$config['auth_ad_timeout'] = 5; // time to wait before giving up (or trying the next server) -$config['auth_ad_debug'] = false; // enable for verbose debug messages -$config['active_directory']['users_purge'] = 30; // purge users who haven't logged in for 30 days. -$config['auth_ad_require_groupmembership'] = false; // require users to be members of a group listed below -$config['auth_ad_groups']['']['level'] = 10; -$config['auth_ad_groups']['']['level'] = 7; -``` - -Replace `` with your Active Directory admin-user group and `` with your standard user group. - -##### Active Directory redundancy - -You can set two Active Directory servers by editing the `$config['auth_ad_url']` like this example: - -``` -$config['auth_ad_url'] = "ldaps://dc1.example.com ldaps://dc2.example.com"; -``` - -##### Active Directory LDAP filters - -You can add an LDAP filter to be ANDed with the builtin user filter (`(sAMAccountName=$username)`). - -The defaults are: - -``` -$config['auth_ad_user_filter'] = "(objectclass=user)"; -$config['auth_ad_group_filter'] = "(objectclass=group)"; -``` - -This yields `(&(objectclass=user)(sAMAccountName=$username))` for the user filter and `(&(objectclass=group)(sAMAccountName=$group))` for the group filter. - -### Radius Authentication +# Radius Authentication Please note that a mysql user is created for each user the logs in successfully. User level 1 is assigned to those accounts so you will then need to assign the relevant permissions unless you set `$config['radius']['userlevel']` to be something other than 1. -> Cleanup of old accounts is done using the authlog. You will need to set the cleanup date for when old accounts will be purged which will happen AUTOMATICALLY. -> Please ensure that you set the $config['authlog_purge'] value to be greater than $config['radius']['users_purge'] otherwise old users won't be removed. - ```php $config['radius']['hostname'] = 'localhost'; $config['radius']['port'] = '1812'; @@ -210,7 +187,29 @@ $config['radius']['users_purge'] = 14;//Purge users who haven't logged in for 14 $config['radius']['default_level'] = 1;//Set the default user level when automatically creating a user. ``` -### HTTP Authentication / AD Authorization +#### Old account cleanup +Cleanup of old accounts is done by checking the authlog. You will need to set the number of days when old accounts will be purged AUTOMATICALLY by daily.sh. + +> Please ensure that you set the $config['authlog_purge'] value to be greater than $config['radius']['users_purge'] otherwise old users won't be removed. + + +# HTTP Authentication + +Config option: `http-auth` + +LibreNMS will expect the user to have authenticated via your webservice already. At this stage it will need to assign a +userlevel for that user which is done in one of two ways: + +- A user exists in MySQL still where the usernames match up. + +- A global guest user (which still needs to be added into MySQL: +```php +$config['http_auth_guest'] = "guest"; +``` +This will then assign the userlevel for guest to all authenticated users. + + +## HTTP Authentication / AD Authorization Config option: `ad-authorization` @@ -233,3 +232,22 @@ $config['auth_ad_binduser'] = "ad_binduser"; $config['auth_ad_bindpassword'] = "ad_bindpassword"; $config['auth_ldap_cache_ttl'] = 300; ``` + + +## HTTP Authentication / LDAP Authorization + +Config option: `ldap-authorization` + +This module is a combination of ___http-auth___ and ___ldap___ + +LibreNMS will expect the user to have authenticated via your webservice already (e.g. using Kerberos Authentication in Apache) but will use LDAP to determine and assign the userlevel of a user. +The userlevel will be calculated by using LDAP group membership information as the ___ldap___ module does. + +The configuration is the same as for the ___ldap___ module with one extra option: auth_ldap_cache_ttl. +This option allows to control how long user information (user_exists, userid, userlevel) are cached within the PHP Session. +The default value is 300 seconds. +To disabled this caching (highly discourage) set this option to 0. + +```php +$config['auth_ldap_cache_ttl'] = 300; +```