Appendix F: LDAP Authentication

appendices/README.md

@@ -309,3 +309,72 @@ A brief list of online ressources that around #ThreatIntel
 * [A curated list of awesome malware analysis tools and resources](https://github.com/rshipp/awesome-malware-analysis/blob/master/README.md). Inspired by [awesome-python](https://github.com/vinta/awesome-python) and [awesome-php](https://github.com/ziadoz/awesome-php).
 * [An authoritative list of awesome devsecops tools with the help from community experiments and contributions](https://github.com/devsecops/awesome-devsecops/blob/master/README.md).[DEV.SEC.OPS](http://devsecops.org)
 * [Advance Python IoC extractor](https://github.com/InQuest/python-iocextract)
+
+# Appendix F: LDAP Authentication
+
+MISP supports LDAP authentication from version 2.4.xxx. This manual will show how to configure LDAP authentication. 
+
+#### Installation and configuration
+
+1. Install `mod_ldap` PHP module
+    ```bash
+    # for Centos or RHEL
+    yum install rh-php72-php-ldap
+    # for Ubuntu or debian
+    apt install php-ldap
+    ```
+2. Prepare variables for configuration
+
+* `{{ LDAP_SERVER }}` – a full LDAP URI of server. For example: `ldap://example.com`.
+* `{{ LDAP_BASE_DN }}` – DN for path that contains users. For example: `cn=users,cn=accounts,dc=example,dc=com`.
+* `{{ LDAP_BIND_DN }}` – user that can read. For example: `uid=misp,cn=sysaccounts,cn=etc,dc=example,dc=com`.
+* `{{ LDAP_BIND_PASSWORD }}` – password for that user.
+* `{{ LDAP_USER_GROUP }}` – group with access to MISP. For example: `cn=misp-users,cn=groups,cn=accounts,dc=example,dc=com`.
+   
+3. Configure MISP ApacheSecureAuth in `app/Config/config.php`
+
+    ```php
+    'LdapAuth' => array(
+      'enabled' => true,
+      'name' => 'My Identity provider',
+      'ldapServer' => '{{ LDAP_SERVER }}',
+      'ldapDN' => '{{ LDAP_BASE_DN }}',
+      'ldapSearchFilter' => '(objectclass=inetuser)',
+      'ldapReaderUser' => '{{ LDAP_BIND_DN }}',
+      'ldapReaderPassword' => '{{ LDAP_BIND_PASSWORD }}',
+      'ldapUserGroup' => '{{ LDAP_USER_GROUP }}',
+      'updateUser' => true,
+    );
+    ```
+
+Required variables:
+
+* `enabled` – if it is true, all users must log in trought LDAP account.
+* `ldapServer` – a full LDAP URI of the form ldap://hostname:port or ldaps://hostname:port for TLS encryption.
+* `ldapDN` – DN for path that contains users.
+
+Optional variables:
+
+* `name` – indentity provider name. Will be shown in login screen and user editing for. Can contain HTML.
+* `ldapReaderUser` – DN or RDN LDAP user with permission to read LDAP information about users.
+* `ldapReaderPassword` – password for that user.
+* `ldapSearchFilter` - LDAP search filter.
+* `ldapSearchAttribute` - LDAP attribute that contains username. Default: `uid`.
+* `ldapEmailField` - LDAP attribute (string) or attributes (array) that will be checked if contains user e-mail address. If you want to change or add field, you should also add that field/fields to `ldapAttributes`. Default: `mail`.
+* `ldapAttributes` – fields that will be fetched from LDAP server. Default: `mail` and `memberof`.
+* `ldapUserGroup` - LDAP group that must be assigned to user to access MISP. Default: not set.
+* `updateUser` - if `true`, MISP will update existing users information (like e-mail address or role) from LDAP after login. Default: `false`.
+* `ldapDefaultOrg` – default organisation ID for user from LDAP. By default it is first organisation in database.
+* `ldapDefaultRoleId` - default role for newly created user. It can be integer or array when key contains LDAP group and value assigned role ID. Must be defined if `updateUser` is set to `true` (without that variable, user will be disabled).
+* `ldapProtocol` - protocol version used. Default: 3.
+* `ldapNetworkTimeout` - timeout for communication with LDAP server in seconds. Default: 5 seconds.
+* `ldapAllowReferrals` - follow referrals returned by the LDAP server. Default: `false`.
+* `ldapStartTls` - enable STARTTLS. Default: `true`.
+
+#### Debugging
+
+Setting LDAP authentication can be sometimes tricky. For debugging, you can check MISP error log (by default in `/var/www/MISP/app/tmp/logs/`) that can contain useful information with problem description.
+
+#### Caveats
+
+* When user is disabled in LDAP, it will not disabled in MISP. That means that user cannot login, but for example notification e-mails still works or it is possible to use user Auth key to access MISP information.