diff --git a/doc/Extensions/Authentication.md b/doc/Extensions/Authentication.md new file mode 100644 index 000000000..9d4be0086 --- /dev/null +++ b/doc/Extensions/Authentication.md @@ -0,0 +1,99 @@ +# Authentication modules + +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 + +- MySQL: mysql + +- LDAP: ldap + + HTTP Auth: http-auth + +#### User levels + +- 1: Normal User. You will need to assign device / port permissions for users at this level. + +- 5: Global Read. + +- 10: This is a global read/write admin account + +- 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"; +``` + +#### MySQL Authentication + +Config option: `mysql` + +This is default option with LibreNMS so you should have already got the configuration setup. + +```php +$config['db_host'] = "HOSTNAME"; +$config['db_user'] = "DBUSER"; +$config['db_pass'] = "DBPASS"; +$config['db_name'] = "DBNAME"; +``` + +#### 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. + +#### LDAP Authentication + +Config option: `ldap` + +This one is a little more complicated :) + +```php +$config['auth_ldap_version'] = 3; # v2 or v3 +$config['auth_ldap_server'] = "ldap.example.com"; +$config['auth_ldap_port'] = 389; +$config['auth_ldap_prefix'] = "uid="; +$config['auth_ldap_suffix'] = ",ou=People,dc=example,dc=com"; +$config['auth_ldap_group'] = "cn=groupname,ou=groups,dc=example,dc=com"; + +$config['auth_ldap_groupbase'] = "ou=group,dc=example,dc=com"; +$config['auth_ldap_groups']['admin']['level'] = 10; +$config['auth_ldap_groups']['pfy']['level'] = 7; +$config['auth_ldap_groups']['support']['level'] = 1; +$config['auth_ldap_groupmemberattr'] = "memberUid"; +``` + +Typically auth_ldap_suffix, auth_ldap_group, auth_ldap_groupbase, auth_ldap_groups are what's required to be configured. + +An example config setup for use with Jumpcloud LDAP as a service is: + +```php +$config['auth_mechanism'] = "ldap"; # default, other options: ldap, http-auth +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_server'] = "ldap.jumpcloud.com"; +$config['auth_ldap_port'] = 389; +$config['auth_ldap_prefix'] = "uid="; +$config['auth_ldap_suffix'] = ",ou=Users,o={id},dc=jumpcloud,dc=com"; +$config['auth_ldap_groupbase'] = "cn=librenms,ou=Users,o={id},dc=jumpcloud,dc=com"; +$config['auth_ldap_groupmemberattr'] = "memberUid"; +``` + +Replace {id} with the unique ID provided by Jumpcloud. diff --git a/doc/Support/Configuration.md b/doc/Support/Configuration.md index 997e2a01f..fb8e1fd18 100644 --- a/doc/Support/Configuration.md +++ b/doc/Support/Configuration.md @@ -355,7 +355,8 @@ Please see [IRC Bot](http://docs.librenms.org/Extensions/IRC-Bot/) section of th $config['auth_mechanism'] = "mysql"; ``` This is the authentication type to use for the WebUI. MySQL is the default and configured when following the installation -instructions. ldap and http-auth are also valid options. +instructions. ldap and http-auth are also valid options. For instructions on the different authentication modules please +see [Authentication](http://doc.librenms.org/Extensions/Authentication/). ```php $config['auth_remember'] = '30'; @@ -368,21 +369,6 @@ $config['allow_unauth_graphs_cidr'] = array(); ``` This option will enable unauthenticated access to the graphs from `allow_unauth_graphs_cidr` ranges that you allow. Use of this option is highly discouraged in favour of the [API](http://docs.librenms.org/API/API-Docs/) that is now available. - -```php -$config['auth_ldap_version'] = 3; # v2 or v3 -$config['auth_ldap_server'] = "ldap.example.com"; -$config['auth_ldap_port'] = 389; -$config['auth_ldap_prefix'] = "uid="; -$config['auth_ldap_suffix'] = ",ou=People,dc=example,dc=com"; -$config['auth_ldap_group'] = "cn=groupname,ou=groups,dc=example,dc=com"; -$config['auth_ldap_groupbase'] = "ou=group,dc=example,dc=com"; -$config['auth_ldap_groups']['admin']['level'] = 10; -$config['auth_ldap_groups']['pfy']['level'] = 7; -$config['auth_ldap_groups']['support']['level'] = 1; -$config['auth_ldap_groupmemberattr'] = "memberUid"; -``` -These configuration options will enable you to integrate your LDAP service into LibreNMS and allow authentication. #### Cleanup options