Skip to content

Instantly share code, notes, and snippets.

@Kagee

Kagee/MISP and LDAP using the ApacheSecureAuth module.md

Last active November 27, 2023 10:00
Download ZIP

Revisions

  1. Kagee revised this gist Oct 5, 2023. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -161,6 +161,7 @@ The "1.2.840.113556.1.4.1941" is a OID called LDAP_MATCHING_RULE_IN_CHAIN. It is

    # Unsorted notes<a name="notes"/>
    * Oct 5 15:13:26 HOSTNAME MISP: error: [Error] Call to undefined function ldap_set_option() -> install php-ldap (same name in debian/red hat)
    * must install mod_ldap in red hat, find name of same pacakge in debian
    * Error in LDAP search query: Bad search filter -> remeber to have ( ) around filter in cofig.php
    * example: apache config for login with mail: AuthLDAPUrl ldap://ad-server01:389/DC=company,DC=com?mail?sub STARTTLS
    * consider setting REDIRECT_REMOTE_USER as default in example
  2. Kagee revised this gist Oct 5, 2023. 1 changed file with 9 additions and 0 deletions.
    9 changes: 9 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -158,3 +158,12 @@ The "1.2.840.113556.1.4.1941" is a OID called LDAP_MATCHING_RULE_IN_CHAIN. It is
    | LDAP with TLS (StartTLS) | The standardized way of protecting LDAP with TLS. Unfortunately it uses the same URI schema as unencrypted LDAP (`ldap://) and the same port, TCP/389.
    | LDAPS (LDAP over SSL/TLS) | A non-standard way of doing LDAP over an established TLS connection. Upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation). LDAPS is often denoted using the URI schema `ldaps://`, and uses port TCP/636.
    | UPN | In Microsoft Active Directory, a User Principal Name (UPN) is a username and domain in an email address format. In a UPN, the username is followed by a separator "at sign" (@) followed by the active directory's internet domain. [More](https://www.techtarget.com/whatis/definition/User-Principal-Name-UPN)</sup> |

    # Unsorted notes<a name="notes"/>
    * Oct 5 15:13:26 HOSTNAME MISP: error: [Error] Call to undefined function ldap_set_option() -> install php-ldap (same name in debian/red hat)
    * Error in LDAP search query: Bad search filter -> remeber to have ( ) around filter in cofig.php
    * example: apache config for login with mail: AuthLDAPUrl ldap://ad-server01:389/DC=company,DC=com?mail?sub STARTTLS
    * consider setting REDIRECT_REMOTE_USER as default in example
    * example search ldapsearch -x -H ldap://ad-server01:389 -vvv -D "CN=srv_misp,OU=MISP,OU=Serice Accounts,DC=company,DC=com" -W -b "OU=company,DC=company,DC=com" "(mail=name@company.com)(memberOf=CN=MISP-Admin,OU=Service Croups,OU=company_KE,DC=company,DC=com)"
    * Local admin: You will have to change the email of the local admin account to match one in AD or you can technically still make the local admin account work, if it is a requirement. just setup a vhost on another port or domain that points to the same MISP instance, and don't include the Auth config. Then you will be presented with the default login screen there, and can log in with local account(s).
    * it should work for non-debian/non-ubuntu, just replace everywhere it says "apache2" with httpd.
  3. Kagee revised this gist Mar 27, 2023. No changes.
  4. Kagee revised this gist Mar 27, 2023. 1 changed file with 8 additions and 0 deletions.
    8 changes: 8 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -102,6 +102,12 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    # Configure Apache for LDAP authentication and authorization <a name="apache_conf)"/>
    The "1.2.840.113556.1.4.1941" is a OID called LDAP_MATCHING_RULE_IN_CHAIN. It is a common solution to support (both) nested and non-nested AD groups via LDAP (you can read about it in google)
    ````
    # For turning on LDAP Debug output
    # LDAPLibraryDebug 7
    <VirtualHost ....>
    ...
    <Location "/users/login">
    AuthType Basic
    AuthName "MISP"
    @@ -113,6 +119,8 @@ The "1.2.840.113556.1.4.1941" is a OID called LDAP_MATCHING_RULE_IN_CHAIN. It is
    Require valid-user
    Require ldap-filter memberof:1.2.840.113556.1.4.1941:=...
    </Location>
    ...
    </VirtualHost>
    ````

    # Configure MISP for LDAP usage <a name="misp_conf)"/>
  5. Kagee revised this gist Mar 21, 2023. 1 changed file with 5 additions and 13 deletions.
    18 changes: 5 additions & 13 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -102,15 +102,7 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    # Configure Apache for LDAP authentication and authorization <a name="apache_conf)"/>
    The "1.2.840.113556.1.4.1941" is a OID called LDAP_MATCHING_RULE_IN_CHAIN. It is a common solution to support (both) nested and non-nested AD groups via LDAP (you can read about it in google)
    ````
    <Location "/">
    # If we are PyMISP (we have an Authorization header), but no Basic Auth skip LDAP authentication
    <If "-n %{HTTP:Authorization} && ! %{HTTP:Authorization} =~ /Basic/ ">
    </If>
    # If we have a MISP cookie, skip LDAP authentication. This is useful is you setup port :1443 to bypass LDAP auth
    # You might be redirected to a login prompt if your cookie is stale. No super nice as a user experience.
    # <ElseIf "%{HTTP:Cookie} =~ /MISP-.+/ ">
    # </ElseIf>
    <Else>
    <Location "/users/login">
    AuthType Basic
    AuthName "MISP"
    AuthBasicProvider ldap
    @@ -120,24 +112,24 @@ The "1.2.840.113556.1.4.1941" is a OID called LDAP_MATCHING_RULE_IN_CHAIN. It is
    LDAPReferrals off
    Require valid-user
    Require ldap-filter memberof:1.2.840.113556.1.4.1941:=...
    </Else>
    </Location>
    ````

    # Configure MISP for LDAP usage <a name="misp_conf)"/>
    ````
    'ApacheSecureAuth' => array(
    // If proxy variable = HTTP_REMOTE_USER, If BasicAuth ldap = PHP_AUTH_USER
    // Possibly REDIRECT_REMOTE_USER or HTTP_REMOTE_USER. DO NOT USE PHP_AUTH_USER
    'apacheEnv' => 'REMOTE_USER',
    'ldapServer' => 'ldap://...',
    'starttls' => true,
    'ldapProtocol' => 3,
    'ldapNetworkTimeout' => 10,
    'ldapReaderUser' => '...',
    'ldapReaderPassword' => '...', // the LDAP reader user password
    'ldapDN' => '...',
    'ldapSearchFilter' => '', // Search filter to limit results from ldapsearh fx to specific group. FX
    'ldapDN' => 'dc=intern,dc=misp,dc=com',
    'ldapSearchFilter' => '(memberof:1.2.840.113556.1.4.1941:=CN=AllowMISPLogin,OU=MISP,OU=Access Groups,DC=intern,DC=misp,DC=com)',
    'ldapDN' => 'dc=internal,dc=example,dc=com',
    'ldapSearchFilter' => '(memberof:1.2.840.113556.1.4.1941:=CN=AllowMISPLogin,OU=MISP,OU=Access Groups,DC=intern,DC=example,DC=com)',
    'ldapSearchAttribut' => 'samaccountname', // LOWERCASE
    'ldapFilter' => array('mail','userprincipalname'),
    'ldapDefaultRoleId' => 3,
  6. Kagee revised this gist Feb 14, 2023. 1 changed file with 3 additions and 0 deletions.
    3 changes: 3 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -100,6 +100,7 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    13. If the user is not found in the DB, a new user will be configured with the default role and organization. (ldapDefaultOrg and ldapDefaultRoleId)

    # Configure Apache for LDAP authentication and authorization <a name="apache_conf)"/>
    The "1.2.840.113556.1.4.1941" is a OID called LDAP_MATCHING_RULE_IN_CHAIN. It is a common solution to support (both) nested and non-nested AD groups via LDAP (you can read about it in google)
    ````
    <Location "/">
    # If we are PyMISP (we have an Authorization header), but no Basic Auth skip LDAP authentication
    @@ -135,6 +136,8 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    'ldapReaderPassword' => '...', // the LDAP reader user password
    'ldapDN' => '...',
    'ldapSearchFilter' => '', // Search filter to limit results from ldapsearh fx to specific group. FX
    'ldapDN' => 'dc=intern,dc=misp,dc=com',
    'ldapSearchFilter' => '(memberof:1.2.840.113556.1.4.1941:=CN=AllowMISPLogin,OU=MISP,OU=Access Groups,DC=intern,DC=misp,DC=com)',
    'ldapSearchAttribut' => 'samaccountname', // LOWERCASE
    'ldapFilter' => array('mail','userprincipalname'),
    'ldapDefaultRoleId' => 3,
  7. Kagee revised this gist Feb 13, 2023. 1 changed file with 53 additions and 1 deletion.
    54 changes: 53 additions & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -10,13 +10,19 @@ Ugly diff hack to render text as red using Github's markdown parser
    - it and report back to the developers if you run into any issues.
    ```

    ```diff
    - This guide is a work in progress and
    - not considered a completed product.
    ```

    # Table of Contents
    * [Assumptions and limitations](#assump_limit)
    * [Requirements](#requirements)
    * [Example data](#example_data)
    * [Test LDAP connection and credentials](#ldap_test)
    * [Login flow explanation](#login_flow)
    * [Login flow explanation](#login_flow)
    * [Configure Apache for LDAP authentication and authorization](#apache_conf)
    * [Configure MISP for LDAP usage](#misp_conf)
    * [Terminology](#terminology)

    # Assumptions and limitations <a name="assump_limit"/>
    @@ -93,6 +99,52 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    12. If the user data of found, and a user exists in the MISP DB with that identification (mail, upn, other), the user will be logged inn.
    13. If the user is not found in the DB, a new user will be configured with the default role and organization. (ldapDefaultOrg and ldapDefaultRoleId)

    # Configure Apache for LDAP authentication and authorization <a name="apache_conf)"/>
    ````
    <Location "/">
    # If we are PyMISP (we have an Authorization header), but no Basic Auth skip LDAP authentication
    <If "-n %{HTTP:Authorization} && ! %{HTTP:Authorization} =~ /Basic/ ">
    </If>
    # If we have a MISP cookie, skip LDAP authentication. This is useful is you setup port :1443 to bypass LDAP auth
    # You might be redirected to a login prompt if your cookie is stale. No super nice as a user experience.
    # <ElseIf "%{HTTP:Cookie} =~ /MISP-.+/ ">
    # </ElseIf>
    <Else>
    AuthType Basic
    AuthName "MISP"
    AuthBasicProvider ldap
    AuthLDAPUrl "ldap://.../...?uid?sub?(objectclass=*)" STARTTLS
    AuthLDAPBindDN ",,,"
    AuthLDAPBindPassword ",,,"
    LDAPReferrals off
    Require valid-user
    Require ldap-filter memberof:1.2.840.113556.1.4.1941:=...
    </Else>
    </Location>
    ````

    # Configure MISP for LDAP usage <a name="misp_conf)"/>
    ````
    'ApacheSecureAuth' => array(
    // If proxy variable = HTTP_REMOTE_USER, If BasicAuth ldap = PHP_AUTH_USER
    'apacheEnv' => 'REMOTE_USER',
    'ldapServer' => 'ldap://...',
    'ldapProtocol' => 3,
    'ldapNetworkTimeout' => 10,
    'ldapReaderUser' => '...',
    'ldapReaderPassword' => '...', // the LDAP reader user password
    'ldapDN' => '...',
    'ldapSearchFilter' => '', // Search filter to limit results from ldapsearh fx to specific group. FX
    'ldapSearchAttribut' => 'samaccountname', // LOWERCASE
    'ldapFilter' => array('mail','userprincipalname'),
    'ldapDefaultRoleId' => 3,
    'ldapDefaultOrg' => '1',
    'ldapAllowReferrals' => false,
    'ldapEmailField' => array('userprincipalname'),
    'updateUser' => true,
    ),
    ````

    # Terminology <a name="terminology"/>
    | Term | Explanation |
    |-----------------------------|---------------------------------------------------------------|
  8. Kagee revised this gist Feb 13, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -43,7 +43,7 @@ __Active Directory:__
    * The DN, UPN and password for this service user
    * The DN for a group that will be used to control MISP access
    * A test user for testing the MISP login
    * This user should be a member of the access group, either directly or via other nested groups.
    * This user should be a member of the access group, either directly or via nested group memberships.

    # Example data <a name="example_data"/>
    In this guide we will use the following example data
  9. Kagee revised this gist Feb 13, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -54,7 +54,7 @@ In this guide we will use the following example data
    | Domain name | `example.com` |
    | Hostname of AD server(s) | `ad.example.com` |
    | MISP Access group | `CN=R_MISP_Access,OU=Misp,OU=Access Groups,DC=example,DC=com` |
    | AD Service account DN | `CN=svc_misp,OU=Service Users,DC=example,DC=com` |
    | AD Service account DN | `CN=srv_misp,OU=Service Users,DC=example,DC=com` |
    | AD Service account UPN | `srv_misp@example.com` |
    | AD Service account password | `ServiceUserPassword1234` |
    | Example user username | `user101` |
  10. Kagee revised this gist Feb 13, 2023. No changes.
  11. Kagee revised this gist Feb 13, 2023. 1 changed file with 3 additions and 1 deletion.
    4 changes: 3 additions & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -32,7 +32,9 @@ Before starting, you should have the following access and data. You can see exam
    __MISP Server:__
    * Terminal (ssh) access to the server MISP is running on
    * sudo (root) access to the server MISP is running on
    * The server MISP is running on must be able to connect to the AD LDAP/LDAPS oirt
    * The server MISP is running on must be able to connect to the AD LDAP port
    * This may require allowing both LDAP and TLS in a firewall on port TCP/389.

    __Active Directory:__
    * The domain name of the AD domain
    * A hostname for connecting to AD via LDAP
  12. Kagee revised this gist Feb 13, 2023. 1 changed file with 2 additions and 1 deletion.
    3 changes: 2 additions & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -94,9 +94,10 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    # Terminology <a name="terminology"/>
    | Term | Explanation |
    |-----------------------------|---------------------------------------------------------------|
    | AD (Active Directory) | Active Directory is a directory service developed by Microsoft for Windows domain networks. Active Directory uses LDAP, Microsoft's version of Kerberos, and DNS. [More](https://en.wikipedia.org/wiki/Active_Directory)
    | DN (Distinguished name) | The LDAP API references an LDAP object by its distinguished name (DN). A DN is a sequence of relative distinguished names (RDN) connected by commas. [More](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ldap/distinguished-names) |
    | LDAP (the protocol) | The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services. Directory services play an important role in developing intranet and Internet applications by allowing the sharing of information about users, systems, networks, services, and applications throughout the network. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) |
    | LDAP (unencrypted) | Raw, unencrypted LDAP. `You should not be using this.` Denoted using the URI schema `ldap://`. Unencrypted LDAP uses port TCP/389.
    | LDAP with TLS (StartTLS) | The standardized way of protecting LDAP with TLS. Unfortunately it uses the same URI schema as unencrypted LDAP (`ldap://) and the same port, TCP/389.
    | LDAPS (LDAP over SSL/TLS) | A non-standard way of doing LDAP over an established TLS connection. Upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation). LDAPS is often denoted using the URI schema `ldaps://`, and uses port TCP/636.
    | UPN | In Microsoft Active Directory, a User Principal Name (UPN) is a username and domain in an email address format. In a UPN, the username is followed by a separator "at sign" (@) followed by the active directory's internet domain. [More](https://www.techtarget.com/whatis/definition/User-Principal-Name-UPN)</sup> |
    | DN | Distinguished name. The LDAP API references an LDAP object by its distinguished name (DN). A DN is a sequence of relative distinguished names (RDN) connected by commas. [More](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ldap/distinguished-names) |
  13. Kagee revised this gist Feb 13, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -97,6 +97,6 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    | LDAP (the protocol) | The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services. Directory services play an important role in developing intranet and Internet applications by allowing the sharing of information about users, systems, networks, services, and applications throughout the network. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) |
    | LDAP (unencrypted) | Raw, unencrypted LDAP. `You should not be using this.` Denoted using the URI schema `ldap://`. Unencrypted LDAP uses port TCP/389.
    | LDAP with TLS (StartTLS) | The standardized way of protecting LDAP with TLS. Unfortunately it uses the same URI schema as unencrypted LDAP (`ldap://) and the same port, TCP/389.
    | LDAPS (LDAP over SSL/TLS) | A non-standard way of doing LDAP over an established TLS connection. Upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation). LDAPS is often denoted using the URI schema `ldaps://`, and uses port TCP/636. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
    | LDAPS (LDAP over SSL/TLS) | A non-standard way of doing LDAP over an established TLS connection. Upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation). LDAPS is often denoted using the URI schema `ldaps://`, and uses port TCP/636.
    | UPN | In Microsoft Active Directory, a User Principal Name (UPN) is a username and domain in an email address format. In a UPN, the username is followed by a separator "at sign" (@) followed by the active directory's internet domain. [More](https://www.techtarget.com/whatis/definition/User-Principal-Name-UPN)</sup> |
    | DN | Distinguished name. The LDAP API references an LDAP object by its distinguished name (DN). A DN is a sequence of relative distinguished names (RDN) connected by commas. [More](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ldap/distinguished-names) |
  14. Kagee revised this gist Feb 13, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -97,6 +97,6 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    | LDAP (the protocol) | The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services. Directory services play an important role in developing intranet and Internet applications by allowing the sharing of information about users, systems, networks, services, and applications throughout the network. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) |
    | LDAP (unencrypted) | Raw, unencrypted LDAP. `You should not be using this.` Denoted using the URI schema `ldap://`. Unencrypted LDAP uses port TCP/389.
    | LDAP with TLS (StartTLS) | The standardized way of protecting LDAP with TLS. Unfortunately it uses the same URI schema as unencrypted LDAP (`ldap://) and the same port, TCP/389.
    | LDAPS | A non-standard way of doing LDAP over an established TLS connection. Commonly known as "LDAP over SSL/TLS". Upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation). LDAPS is often denoted using the URI schema `ldaps://`, and uses port TCP/636. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
    | LDAPS (LDAP over SSL/TLS) | A non-standard way of doing LDAP over an established TLS connection. Upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation). LDAPS is often denoted using the URI schema `ldaps://`, and uses port TCP/636. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
    | UPN | In Microsoft Active Directory, a User Principal Name (UPN) is a username and domain in an email address format. In a UPN, the username is followed by a separator "at sign" (@) followed by the active directory's internet domain. [More](https://www.techtarget.com/whatis/definition/User-Principal-Name-UPN)</sup> |
    | DN | Distinguished name. The LDAP API references an LDAP object by its distinguished name (DN). A DN is a sequence of relative distinguished names (RDN) connected by commas. [More](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ldap/distinguished-names) |
  15. Kagee revised this gist Feb 13, 2023. 1 changed file with 10 additions and 2 deletions.
    12 changes: 10 additions & 2 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -17,7 +17,7 @@ Ugly diff hack to render text as red using Github's markdown parser
    * [Example data](#example_data)
    * [Test LDAP connection and credentials](#ldap_test)
    * [Login flow explanation](#login_flow)
    * [Terminology](terminology)
    * [Terminology](#terminology)

    # Assumptions and limitations <a name="assump_limit"/>
    * MISP is running on a Debian-based (i.e Ubuntu) system.
    @@ -91,4 +91,12 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    12. If the user data of found, and a user exists in the MISP DB with that identification (mail, upn, other), the user will be logged inn.
    13. If the user is not found in the DB, a new user will be configured with the default role and organization. (ldapDefaultOrg and ldapDefaultRoleId)

    # Terminology <a name="terminology"/>
    # Terminology <a name="terminology"/>
    | Term | Explanation |
    |-----------------------------|---------------------------------------------------------------|
    | LDAP (the protocol) | The Lightweight Directory Access Protocol (LDAP) is an open, vendor-neutral, industry standard application protocol for accessing and maintaining distributed directory information services. Directory services play an important role in developing intranet and Internet applications by allowing the sharing of information about users, systems, networks, services, and applications throughout the network. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) |
    | LDAP (unencrypted) | Raw, unencrypted LDAP. `You should not be using this.` Denoted using the URI schema `ldap://`. Unencrypted LDAP uses port TCP/389.
    | LDAP with TLS (StartTLS) | The standardized way of protecting LDAP with TLS. Unfortunately it uses the same URI schema as unencrypted LDAP (`ldap://) and the same port, TCP/389.
    | LDAPS | A non-standard way of doing LDAP over an established TLS connection. Commonly known as "LDAP over SSL/TLS". Upon connect, the client and server establish TLS before any LDAP messages are transferred (without a StartTLS operation). LDAPS is often denoted using the URI schema `ldaps://`, and uses port TCP/636. [More](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol)
    | UPN | In Microsoft Active Directory, a User Principal Name (UPN) is a username and domain in an email address format. In a UPN, the username is followed by a separator "at sign" (@) followed by the active directory's internet domain. [More](https://www.techtarget.com/whatis/definition/User-Principal-Name-UPN)</sup> |
    | DN | Distinguished name. The LDAP API references an LDAP object by its distinguished name (DN). A DN is a sequence of relative distinguished names (RDN) connected by commas. [More](https://learn.microsoft.com/en-us/previous-versions/windows/desktop/ldap/distinguished-names) |
  16. Kagee revised this gist Feb 13, 2023. 1 changed file with 55 additions and 22 deletions.
    77 changes: 55 additions & 22 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,36 +1,66 @@
    # Important
    The ApacheSecureAuth / LDAP login code in MISP is a __3rd party contribution__ and untested (__including security__) by the MISP-project team. However, you are free to enable it and report back to the developers if you run into any issues.

    # Assumptions and limitations
    <!---
    Ugly diff hack to render text as red using Github's markdown parser
    -->
    ```diff
    - The ApacheSecureAuth / LDAP login code in MISP is a
    - 3rd party contribution and untested (including security)
    - by the MISP-project team. However, you are free to enable
    - it and report back to the developers if you run into any issues.
    ```


    # Table of Contents
    * [Assumptions and limitations](#assump_limit)
    * [Requirements](#requirements)
    * [Example data](#example_data)
    * [Test LDAP connection and credentials](#ldap_test)
    * [Login flow explanation](#login_flow)
    * [Terminology](terminology)

    # Assumptions and limitations <a name="assump_limit"/>
    * MISP is running on a Debian-based (i.e Ubuntu) system.
    * The general "Login flow explanation" etc. is the same for other systems, but for i.e. RedHat-based distroes some paths and commands must be changed.
    * MISP is running behind a Apache 2.4 or newer webserver.
    * You are connecting to a AD LDAP server. (Should also work with Samba AD LDAP)
    * We assume MISP is installed in `/var/www/MISP`

    # Before starting, you should have the following
    # Requirements <a name="requirements"/>
    Before starting, you should have the following access and data. You can see examples on required data in [Example data](#example_data).

    __MISP Server:__
    * Terminal (ssh) access to the server MISP is running on
    * sudo ("root") access to the server MISP is running on
    * sudo (root) access to the server MISP is running on
    * The server MISP is running on must be able to connect to the AD LDAP/LDAPS oirt
    __Active Directory:__
    * The domain name of the AD domain
    * A hostname for connecting to AD via LDAP
    * Information on wheter you should connect using LDAP+STARTTLS (recommended, uses port 389), LDAP over TLS ("LDAPS", uses port 636), or unencrypted LDAP (uses port 389)
    * A service user (read-only is enough) for the AD LDAP you are connecting to.
    * The DN and password for this service user
    * The DN, UPN and password for this service user
    * The DN for a group that will be used to control MISP access
    * A test user for testing the MISP login
    * This user should be a member of the access group, either directly or via other nested groups.

    # Example data
    # Example data <a name="example_data"/>
    In this guide we will use the following example data

    | Item | Value |
    |-----------------------------|--------------------------------------------------|
    | Domain Netbios name | `EXAMPLE` |
    | Domain name | `example.com` |
    | Hostname of AD server(s) | `ad.example.com` |
    | AD Service account DN | `CN=svc_misp,OU=Service Users,DC=example,DC=com` |
    | AD Service account UPN | `srv_misp@example.com` |
    | AD Service account password | `ServiceUserPassword1234` |
    | Example user username | `user101` |
    | Example user DN | `user101@exampleuser` |
    | Example user UPN | `user101@example.com` |
    | Example user password | `MySecretPassword1234` |

    # Test LDAP connection and credentials
    | Item | Value |
    |-----------------------------|---------------------------------------------------------------|
    | Domain Netbios name | `EXAMPLE` |
    | Domain name | `example.com` |
    | Hostname of AD server(s) | `ad.example.com` |
    | MISP Access group | `CN=R_MISP_Access,OU=Misp,OU=Access Groups,DC=example,DC=com` |
    | AD Service account DN | `CN=svc_misp,OU=Service Users,DC=example,DC=com` |
    | AD Service account UPN | `srv_misp@example.com` |
    | AD Service account password | `ServiceUserPassword1234` |
    | Example user username | `user101` |
    | Example user DN | `CN=Example User,OU=Users,DC=example,DC=com` |
    | Example user UPN | `user101@example.com` |
    | Example user password | `MySecretPassword1234` |

    # Test LDAP connection and credentials <a name="ldap_test"/>

    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=example,dc=com' '(uid=<your username>)' '*'`

    @@ -42,7 +72,8 @@ When your first try fail, ldapsearch just LOVES to return the impressively unhel

    * `ldapsearch -d 9 -D 'CN=some_service_user,OU=Service Users,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' '(uid=<your username>)' '*'`

    # Login flow explanation

    # Login flow explanation <a name="login_flow"/>

    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config (possibly somewhere like `/etc/apache2/sites-enabled/misp.conf`). Step 8 to 13 happens in the MISP code, and is configured in the normal MISP config.php. (possibly somewhere like `/var/www/MISP/app/Config/config.php`)

    @@ -58,4 +89,6 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    10. Once the MISP code sees a request to misp.domain/user/login that has this HTTP request header set, it will buypass the normal MISP login form.
    11. The MISP code will connect to AD over LDAP suing the settings configurd in ApacheSecureAuth.*. Depending on the values and searches configured there, it will retrieve information on the users, for example their configured email address (from the AD "mail" field) or some other attribute that will be user in the MISP email field (i.e. userprincipalname)
    12. If the user data of found, and a user exists in the MISP DB with that identification (mail, upn, other), the user will be logged inn.
    13. If the user is not found in the DB, a new user will be configured with the default role and organization. (ldapDefaultOrg and ldapDefaultRoleId)
    13. If the user is not found in the DB, a new user will be configured with the default role and organization. (ldapDefaultOrg and ldapDefaultRoleId)

    # Terminology <a name="terminology"/>
  17. Kagee revised this gist Feb 13, 2023. 1 changed file with 3 additions and 0 deletions.
    3 changes: 3 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,3 +1,6 @@
    # Important
    The ApacheSecureAuth / LDAP login code in MISP is a __3rd party contribution__ and untested (__including security__) by the MISP-project team. However, you are free to enable it and report back to the developers if you run into any issues.

    # Assumptions and limitations
    * MISP is running on a Debian-based (i.e Ubuntu) system.
    * The general "Login flow explanation" etc. is the same for other systems, but for i.e. RedHat-based distroes some paths and commands must be changed.
  18. Kagee revised this gist Feb 13, 2023. 1 changed file with 15 additions and 0 deletions.
    15 changes: 15 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -11,6 +11,21 @@
    * A service user (read-only is enough) for the AD LDAP you are connecting to.
    * The DN and password for this service user

    # Example data
    In this guide we will use the following example data

    | Item | Value |
    |-----------------------------|--------------------------------------------------|
    | Domain Netbios name | `EXAMPLE` |
    | Domain name | `example.com` |
    | Hostname of AD server(s) | `ad.example.com` |
    | AD Service account DN | `CN=svc_misp,OU=Service Users,DC=example,DC=com` |
    | AD Service account UPN | `srv_misp@example.com` |
    | AD Service account password | `ServiceUserPassword1234` |
    | Example user username | `user101` |
    | Example user DN | `user101@exampleuser` |
    | Example user UPN | `user101@example.com` |
    | Example user password | `MySecretPassword1234` |

    # Test LDAP connection and credentials

  19. Kagee revised this gist Feb 13, 2023. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -14,15 +14,15 @@

    # Test LDAP connection and credentials

    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' '(uid=<your username>)' '*'`
    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=example,dc=com' '(uid=<your username>)' '*'`

    When ldapsearch asks for a password, enter the password for the some_service_user-user. This is the user we are trying to connect as, as spesified with -D.

    Now, it is *probably* going to fail. If you get your ldapsearch to work on the first try i owe you a pint of beer/soda.

    When your first try fail, ldapsearch just LOVES to return the impressively unhelpful error message `Can't contact LDAP server (-1)`. Add `-d 9` (debug level 9) to the command line to get more useful error messages.

    * `ldapsearch -d 9 -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' '(uid=<your username>)' '*'`
    * `ldapsearch -d 9 -D 'CN=some_service_user,OU=Service Users,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' '(uid=<your username>)' '*'`

    # Login flow explanation

  20. Kagee revised this gist Feb 11, 2023. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -14,15 +14,15 @@

    # Test LDAP connection and credentials

    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' 'uid=<your username>' '*'`
    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' '(uid=<your username>)' '*'`

    When ldapsearch asks for a password, enter the password for the some_service_user-user. This is the user we are trying to connect as, as spesified with -D.

    Now, it is *probably* going to fail. If you get your ldapsearch to work on the first try i owe you a pint of beer/soda.

    When your first try fail, ldapsearch just LOVES to return the impressively unhelpful error message `Can't contact LDAP server (-1)`. Add `-d 9` (debug level 9) to the command line to get more useful error messages.

    * `ldapsearch -d 9 -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' 'uid=<your username>' '*'`
    * `ldapsearch -d 9 -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' '(uid=<your username>)' '*'`

    # Login flow explanation

  21. Kagee revised this gist Feb 11, 2023. 1 changed file with 2 additions and 0 deletions.
    2 changes: 2 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -16,6 +16,8 @@

    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' 'uid=<your username>' '*'`

    When ldapsearch asks for a password, enter the password for the some_service_user-user. This is the user we are trying to connect as, as spesified with -D.

    Now, it is *probably* going to fail. If you get your ldapsearch to work on the first try i owe you a pint of beer/soda.

    When your first try fail, ldapsearch just LOVES to return the impressively unhelpful error message `Can't contact LDAP server (-1)`. Add `-d 9` (debug level 9) to the command line to get more useful error messages.
  22. Kagee revised this gist Feb 11, 2023. 1 changed file with 7 additions and 1 deletion.
    8 changes: 7 additions & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -14,7 +14,13 @@

    # Test LDAP connection and credentials

    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com:389' -b 'dc=ad,dc=example,dc=com' 'uid=<your username>' '*'`
    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' 'uid=<your username>' '*'`

    Now, it is *probably* going to fail. If you get your ldapsearch to work on the first try i owe you a pint of beer/soda.

    When your first try fail, ldapsearch just LOVES to return the impressively unhelpful error message `Can't contact LDAP server (-1)`. Add `-d 9` (debug level 9) to the command line to get more useful error messages.

    * `ldapsearch -d 9 -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com' -b 'dc=ad,dc=example,dc=com' 'uid=<your username>' '*'`

    # Login flow explanation

  23. Kagee revised this gist Feb 11, 2023. 1 changed file with 18 additions and 0 deletions.
    18 changes: 18 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,3 +1,21 @@
    # Assumptions and limitations
    * MISP is running on a Debian-based (i.e Ubuntu) system.
    * The general "Login flow explanation" etc. is the same for other systems, but for i.e. RedHat-based distroes some paths and commands must be changed.
    * MISP is running behind a Apache 2.4 or newer webserver.
    * You are connecting to a AD LDAP server. (Should also work with Samba AD LDAP)
    * We assume MISP is installed in `/var/www/MISP`

    # Before starting, you should have the following
    * Terminal (ssh) access to the server MISP is running on
    * sudo ("root") access to the server MISP is running on
    * A service user (read-only is enough) for the AD LDAP you are connecting to.
    * The DN and password for this service user


    # Test LDAP connection and credentials

    * `ldapsearch -D 'CN=some_service_user,OU=Service Users,DC=ad,DC=example,DC=com' -W -H 'ldap://ad.example.com:389' -b 'dc=ad,dc=example,dc=com' 'uid=<your username>' '*'`

    # Login flow explanation

    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config (possibly somewhere like `/etc/apache2/sites-enabled/misp.conf`). Step 8 to 13 happens in the MISP code, and is configured in the normal MISP config.php. (possibly somewhere like `/var/www/MISP/app/Config/config.php`)
  24. Kagee revised this gist Feb 11, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,6 @@
    # Login flow explanation

    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config (possibly somewhere like `/etc/apache2/sites-enabled/misp.conf`). Step 8 to 13 happens in the misp code, and is configured in the normal MISP config.php
    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config (possibly somewhere like `/etc/apache2/sites-enabled/misp.conf`). Step 8 to 13 happens in the MISP code, and is configured in the normal MISP config.php. (possibly somewhere like `/var/www/MISP/app/Config/config.php`)

    1. User visits misp.domain.
    2. user is forwarded to misp.domain/user/login.
  25. Kagee revised this gist Feb 11, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,6 +1,6 @@
    # Login flow explanation

    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config. Step 8 to 13 happens in the misp code, and is configured in the normal MISP config.php
    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config (possibly somewhere like `/etc/apache2/sites-enabled/misp.conf`). Step 8 to 13 happens in the misp code, and is configured in the normal MISP config.php

    1. User visits misp.domain.
    2. user is forwarded to misp.domain/user/login.
  26. Kagee revised this gist Feb 11, 2023. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -6,7 +6,7 @@ Everything from step 3 to 7 is part of what the webserver does, and must be conf
    2. user is forwarded to misp.domain/user/login.
    3. Webserver has been configured to require LDAP authentication and possibly authorization on that URL.
    4. The webserver will return a http 401 unauthorized to the users browser, with information about how to authorize.
    5. With Apache and LDAP, the default will trigger the users browser to pop up a standard "HTTP Basic Auth" popup box where the user can enter their AD credentials.
    5. With Apache and LDAP, the default will trigger the users browser to pop up a standard ["HTTP Basic Auth"](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication) popup box where the user can enter their AD credentials.
    6. The browser will reload misp.domain/user/login, but also transmit the username and password the user supplied in step 5. (Unencrypted, so using https is important).
    7. The webserver will connect to AD over LDAP using the configured ad service account. It will then try to authenticate the user using the supplied username and password, and potentially check that the user is in a required group (authorization). Is this step fails, go to step 4.
    8. If step 7 is successful, the webserver will start the PHP process, and render misp.domain/user/login using the MISP source code. It will transmit the username as part of the request (either just username or username@ad.domain depending on setting) in a HTTP request header, quite often called REMOTE_USER or HTTP_REMOTE_USER.
  27. Kagee revised this gist Feb 11, 2023. 1 changed file with 3 additions and 3 deletions.
    6 changes: 3 additions & 3 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -2,16 +2,16 @@

    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config. Step 8 to 13 happens in the misp code, and is configured in the normal MISP config.php

    1. User visits MiSP.domain.
    1. User visits misp.domain.
    2. user is forwarded to misp.domain/user/login.
    3. Webserver has been configured to require LDAP authentication and possibly authorization on that URL.
    4. The webserver will return a http 401 unauthorized to the users browser, with information about how to authorize.
    5. With Apache and LDAP, the default will trigger the users browser to pop up a standard "HTTP Basic Auth" popup box where the user can enter their AD credentials.
    6. The browser will reload misp.domain/user/login, but also transmit the username and password the user supplied in step 5. (Unencrypted, so using https is important).
    7. The webserver will connect to AD over LDAP using the configured ad service account. It will then try to authenticate the user using the supplied username and password, and potentially check that the user is in a required group (authorization). Is this step fails, go to step 4.
    8. If step 7 is successful, the webserver will start the PHP process, and render misp.domain/user/login using the MISP source code. It will transmit the username as part of the request (either just username or username@ad.domain depending on setting) in a HTTP request header, quite often called REMOTE_USER or HTTP_REMOTE_USER.
    9.The correct header name must be configured in ApacheSecureAuth.apaceEnv (I think the default here is REMOTE_USER)
    10. Once the MISP code sees a request to misp.domain/user/login that has this HTTP request header set, it will disable the normal MISP login form.
    9. The correct header name must be configured in ApacheSecureAuth.apaceEnv (I think the default here is REMOTE_USER)
    10. Once the MISP code sees a request to misp.domain/user/login that has this HTTP request header set, it will buypass the normal MISP login form.
    11. The MISP code will connect to AD over LDAP suing the settings configurd in ApacheSecureAuth.*. Depending on the values and searches configured there, it will retrieve information on the users, for example their configured email address (from the AD "mail" field) or some other attribute that will be user in the MISP email field (i.e. userprincipalname)
    12. If the user data of found, and a user exists in the MISP DB with that identification (mail, upn, other), the user will be logged inn.
    13. If the user is not found in the DB, a new user will be configured with the default role and organization. (ldapDefaultOrg and ldapDefaultRoleId)
  28. Kagee created this gist Feb 11, 2023.
    17 changes: 17 additions & 0 deletions MISP and LDAP using the ApacheSecureAuth module.md
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,17 @@
    # Login flow explanation

    Everything from step 3 to 7 is part of what the webserver does, and must be configured in the webserver config. Step 8 to 13 happens in the misp code, and is configured in the normal MISP config.php

    1. User visits MiSP.domain.
    2. user is forwarded to misp.domain/user/login.
    3. Webserver has been configured to require LDAP authentication and possibly authorization on that URL.
    4. The webserver will return a http 401 unauthorized to the users browser, with information about how to authorize.
    5. With Apache and LDAP, the default will trigger the users browser to pop up a standard "HTTP Basic Auth" popup box where the user can enter their AD credentials.
    6. The browser will reload misp.domain/user/login, but also transmit the username and password the user supplied in step 5. (Unencrypted, so using https is important).
    7. The webserver will connect to AD over LDAP using the configured ad service account. It will then try to authenticate the user using the supplied username and password, and potentially check that the user is in a required group (authorization). Is this step fails, go to step 4.
    8. If step 7 is successful, the webserver will start the PHP process, and render misp.domain/user/login using the MISP source code. It will transmit the username as part of the request (either just username or username@ad.domain depending on setting) in a HTTP request header, quite often called REMOTE_USER or HTTP_REMOTE_USER.
    9.The correct header name must be configured in ApacheSecureAuth.apaceEnv (I think the default here is REMOTE_USER)
    10. Once the MISP code sees a request to misp.domain/user/login that has this HTTP request header set, it will disable the normal MISP login form.
    11. The MISP code will connect to AD over LDAP suing the settings configurd in ApacheSecureAuth.*. Depending on the values and searches configured there, it will retrieve information on the users, for example their configured email address (from the AD "mail" field) or some other attribute that will be user in the MISP email field (i.e. userprincipalname)
    12. If the user data of found, and a user exists in the MISP DB with that identification (mail, upn, other), the user will be logged inn.
    13. If the user is not found in the DB, a new user will be configured with the default role and organization. (ldapDefaultOrg and ldapDefaultRoleId)