From e8f583c947eb61b8a0cc3e95745b72082ab8a3ba Mon Sep 17 00:00:00 2001 From: melaniekung Date: Mon, 26 Feb 2024 13:29:46 -0800 Subject: [PATCH] Update LDAP extension documentations. --- admin-manual/customization/authentication.rst | 242 +++++++++--------- dev-manual/env/compose.rst | 46 ++++ 2 files changed, 173 insertions(+), 115 deletions(-) diff --git a/admin-manual/customization/authentication.rst b/admin-manual/customization/authentication.rst index 8a7242c0..d124a582 100644 --- a/admin-manual/customization/authentication.rst +++ b/admin-manual/customization/authentication.rst @@ -22,7 +22,7 @@ protocols. * :ref:`ldap-enabling` .. SEEALSO:: - + * :ref:`customization-config-files` * :ref:`log-in` * :ref:`read-only-mode` @@ -45,20 +45,20 @@ For more information on how to do this, see :ref:`Manage AtoM configuration files `. The first thing to do is to activate the ``arCasPlugin``. This can be done by -by adding the plugin name to the ``$plugins`` array in +by adding the plugin name to the ``$plugins`` array in ``config/ProjectConfiguration.class.php``. .. IMPORTANT:: - While the plugin could technically be enabled by an :term:`administrator` - logging in and enabling it in the :term:`user interface` via |gears| + While the plugin could technically be enabled by an :term:`administrator` + logging in and enabling it in the :term:`user interface` via |gears| **Admin > Plugins**, doing so would require authenticating locally without CAS enabled - and the additional configuration file changes described below - will not yet be in place. + will not yet be in place. For security best practices, we recommend a system administrator enable - the plugin using the method described above, so no local authentication - accounts are stored in AtoM when the intention is to use CAS. + the plugin using the method described above, so no local authentication + accounts are stored in AtoM when the intention is to use CAS. Next, configure the CAS settings (CAS version, server name, server port, server path, and server SSL certificate) in the ``arCasPlugin``'s ``app.yml`` config @@ -73,21 +73,21 @@ and password ``django-cas-ng``. While CAS server SSL validation can be disabled for development, we strongly discourage doing so in a production environment. -For further information and additional configuration options, see the -:ref:`customization-config-files` documentation - specifically: +For further information and additional configuration options, see the +:ref:`customization-config-files` documentation - specifically: * :ref:`cas-app-yml` -Next, change the default login module to ``cas`` in +Next, change the default login module to ``cas`` in ``apps/qubit/config/settings.yml``. -Finally, change the user class to ``casUser`` in +Finally, change the user class to ``casUser`` in ``apps/qubit/config/factories.yml``. .. TIP:: Whenever you make changes to AtoM's configuration files, remember to clear - the cache and restart PHP-FPM to apply the changes. See: + the cache and restart PHP-FPM to apply the changes. See: * :ref:`maintenance-clear-cache` * :ref:`troubleshooting-restart-php-fpm` @@ -126,8 +126,8 @@ that are properly configured with an ``attribute_value`` and a valid .. NOTE:: - When this option is enabled, any changes that an administrator makes in - AtoM to a user's group membership will not persist and be overwritten on + When this option is enabled, any changes that an administrator makes in + AtoM to a user's group membership will not persist and be overwritten on the next CAS login. :ref:`Back to top ` @@ -139,43 +139,55 @@ Enabling LDAP authentication .. _LDAP: https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol -AtoM can also be configured to authenticate users using (`LDAP`_ ), an "open, -vendor-neutral, industry standard application protocol for accessing and -maintaining distributed directory information services over an Internet -Protocol (IP) network" (Wikipedia). When this is enabled, users attempting to -log in will use the credentials associated with their LDAP account, instead -of local account credentials, when :ref:`logging in ` to AtoM. +.. IMPORTANT:: + + LDAP authentication requires the ``php-ldap`` extension that will need to be + installed manually. -Enabling LDAP authentication in AtoM requires manually editing a few AtoM -configuration files. For more general information on how to do this, see -:ref:`Manage AtoM configuration files `. -First, we'll need to make a small change in the ``config/factories.yml`` -configuration file. You can open this file with ``nano`` or another text editor -to make the changes. Starting from AtoM's root installation directory, run: +AtoM can also be configured to authenticate users using `LDAP`_ , an "open, +vendor-neutral, industry standard application protocol for accessing and +maintaining distributed directory information services over an Internet +Protocol (IP) network" (Wikipedia). When this is enabled, users attempting to +log in will use the credentials associated with their LDAP account, instead +of local account credentials, when :ref:`logging in ` to AtoM. + +Enabling LDAP authentication in AtoM requires manually installing an additional +PHP extension and editing a few AtoM configuration files. For more general information +on how to do this, see :ref:`Manage AtoM configuration files `. + +First, install the PHP extension for LDAP: + +.. code-block:: bash + + sudo apt-get install php-ldap + +Next, we'll need to make a small change in the ``config/factories.yml`` +configuration file. You can open this file with ``nano`` or another text editor +to make the changes. Starting from AtoM's root installation directory, run: .. code-block:: bash sudo nano config/factories.yml -.. IMPORTANT:: +.. IMPORTANT:: - If you are making these changes on an AtoM installation **after** it has + If you are making these changes on an AtoM installation **after** it has already been installed and configured, then the file you should modify will be - found at ``apps/qubit/config/factories.yml``. + found at ``apps/qubit/config/factories.yml``. - During the final configuration steps of the installation process, AtoM will - copy the default values from the original ``config/factories`` version into + During the final configuration steps of the installation process, AtoM will + copy the default values from the original ``config/factories`` version into a new ``apps/qubit/config/factories.yml`` version, which will take precedence - going forward. If your AtoM installation is already complete, this second one + going forward. If your AtoM installation is already complete, this second one will be the file you'll want to change. - If you're not sure, check for a file at ``apps/qubit/config/factories.yml`` - while making changes. If it exists, make the changes in this file. Note that - applying the changes in both files will work fine as well. + If you're not sure, check for a file at ``apps/qubit/config/factories.yml`` + while making changes. If it exists, make the changes in this file. Note that + applying the changes in both files will work fine as well. -In the file you'll find the following section: +In the file you'll find the following section: .. code-block:: bash @@ -184,33 +196,33 @@ In the file you'll find the following section: param: timeout: 1800 # Session timeout in seconds -Change the ``myUser`` value to ``ldapUser``: +Change the ``myUser`` value to ``ldapUser``: .. code-block:: bash user: class: ldapUser -Exit and save your changes, and the clear the application cache and restart +Exit and save your changes, and the clear the application cache and restart PHP-FPM. * :ref:`maintenance-clear-cache` * :ref:`troubleshooting-restart-php-fpm` -After doing so, a new configuration section will be available in |gears| -**Admin > Settings**, where you can define your LDAP authentication settings: +After doing so, a new configuration section will be available in |gears| +**Admin > Settings**, where you can define your LDAP authentication settings: .. image:: images/ldap-config.* :align: center :width: 90% :alt: An image of the LDAP authentication settings -The **Host** field expects the hostname or IP address of the LDAP server. +The **Host** field expects the hostname or IP address of the LDAP server. -The **Port** field should be the port on which your LDAP server will listen for -connections. The industry standard default port for LDAP connections is ``389`` -- by default, AtoM will populate this field with ``389``. Try this if you're not -sure what port your LDAP server is using. +The **Port** field should be the port on which your LDAP server will listen for +connections. The industry standard default port for LDAP connections is ``389`` +- by default, AtoM will populate this field with ``389``. Try this if you're not +sure what port your LDAP server is using. Base DN and Bind Lookup Attribute - overview -------------------------------------------- @@ -218,99 +230,99 @@ Base DN and Bind Lookup Attribute - overview These two elements are what AtoM will use to determine which LDAP entry the authentication attempt should be compared against. -The **Base DN** will provide AtoM with the common parts of an LDAP entry on -your server that won't change per user - basically, where to look in the LDAP -directory tree to find general user information. +The **Base DN** will provide AtoM with the common parts of an LDAP entry on +your server that won't change per user - basically, where to look in the LDAP +directory tree to find general user information. -Every LDAP entry consists of a set of attributes. LDAP entries are stored in a -tree-like directory structure, so the information provided in this field should -give AtoM enough information to find the subdirectory that contains your unique -users. Configuring this field in AtoM will require an understanding of how your -LDAP server is configured. +Every LDAP entry consists of a set of attributes. LDAP entries are stored in a +tree-like directory structure, so the information provided in this field should +give AtoM enough information to find the subdirectory that contains your unique +users. Configuring this field in AtoM will require an understanding of how your +LDAP server is configured. -Every LDAP entry will have a Distinguished Name (**DN**) that uniquely identifies -that entry and its position in the directory information tree (DIT) hierarchy, -similar to the path to a file on a filesystem. +Every LDAP entry will have a Distinguished Name (**DN**) that uniquely identifies +that entry and its position in the directory information tree (DIT) hierarchy, +similar to the path to a file on a filesystem. -Each LDAP DN is composed of zero or more elements called relative distinguished -names (RDNs), and each RDN is composed of at least one attribute-value pairs. -There are several commonly used attributes, such as: +Each LDAP DN is composed of zero or more elements called relative distinguished +names (RDNs), and each RDN is composed of at least one attribute-value pairs. +There are several commonly used attributes, such as: * **cn**: Common name. For example, "John Doe" * **sn**: Surname. For example, "Doe" -* **uid**: User ID. Because a DN indicates directory location, it's possible a - DN may change over the lifetime of the entry, for example if an entry is moved - within the directory's information tree hierarchy. Including a unique ID for - each entry means this can be used in a DN. For example, ``jdoe01``. -* **dc**: Domain component. For example, If the base domain name of the LDAP - server is found at ``ldap.example.com``, then the domain components for an +* **uid**: User ID. Because a DN indicates directory location, it's possible a + DN may change over the lifetime of the entry, for example if an entry is moved + within the directory's information tree hierarchy. Including a unique ID for + each entry means this can be used in a DN. For example, ``jdoe01``. +* **dc**: Domain component. For example, If the base domain name of the LDAP + server is found at ``ldap.example.com``, then the domain components for an entry might be ``dc=ldap,dc=example,dc=com`` with each part of the full domain - being one domain component. -* **mail**: Email address associated with the entry. For example, + being one domain component. +* **mail**: Email address associated with the entry. For example, `` john.doe@example.com``. -* **ou**: Organizational unit. Typically represents a directory used in your - LDAP directory hierarchy, such as ``Users``. -* **userPassword**: the password associated with the particular user defined in - the LDAP entry. +* **ou**: Organizational unit. Typically represents a directory used in your + LDAP directory hierarchy, such as ``Users``. +* **userPassword**: the password associated with the particular user defined in + the LDAP entry. -There are a number of other attribute key-value pairs often used as well for -capturing additional information about the entry and its location in the +There are a number of other attribute key-value pairs often used as well for +capturing additional information about the entry and its location in the directory tree, but those listed above include the elements we need to configure -AtoM's Base DN. +AtoM's Base DN. -Meanwhile, the **Bind Lookup Attribute** setting in AtoM will specify which -attribute should be used to uniquely identify the user. This attribute value -will tell AtoM which LDAP attribute to compare against the value entered into -the "Email" field in AtoM's login panel. While the Base DN values will be -common to all LDAP entries, the attribute selected for Lookup should be unique. -An example: +Meanwhile, the **Bind Lookup Attribute** setting in AtoM will specify which +attribute should be used to uniquely identify the user. This attribute value +will tell AtoM which LDAP attribute to compare against the value entered into +the "Email" field in AtoM's login panel. While the Base DN values will be +common to all LDAP entries, the attribute selected for Lookup should be unique. +An example: .. code-block:: bash dn: uid=jdoe01,ou=atomUsers,dc=example,dc=com - ^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + ^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Lookup Base DN When authenticating a user, AtoM will use the Base DN and Bind Lookup Attribute values together to identify the relevant target LDAP entry that is used for validating the authentication attempt. This means: -* Whatever is set as the Bind Lookup Attribute in AtoM's settings should match - what users logging in with LDAP will enter into the AtoM login panel's - "Email" field. +* Whatever is set as the Bind Lookup Attribute in AtoM's settings should match + what users logging in with LDAP will enter into the AtoM login panel's + "Email" field. * Whatever password a user enters into the AtoM login panel's "Password" field - should match the ``userPassword`` value in their LDAP directory entry. + should match the ``userPassword`` value in their LDAP directory entry. Configuring the Base DN and Bind Lookup Attribute settings ---------------------------------------------------------- -The **Base DN** setting in AtoM *must* include any ``ou`` (organizational unit) -directory component that target users are contained in on the LDAP server, plus +The **Base DN** setting in AtoM *must* include any ``ou`` (organizational unit) +directory component that target users are contained in on the LDAP server, plus any domain components (``dc``) required to find the information. AtoM will use -this to be able to find where individual LDAP entries are stored within the +this to be able to find where individual LDAP entries are stored within the LDAP server's directory tree. each attribute key/value pair should be entered -separated by commas, with no spaces between them. +separated by commas, with no spaces between them. -For example, if the target LDAP server has user accounts in an -Organizational Unit called "atomUsers" on a server with a domain of -``example.com``, then the Base DN setting in AtoM would be entered as: +For example, if the target LDAP server has user accounts in an +Organizational Unit called "atomUsers" on a server with a domain of +``example.com``, then the Base DN setting in AtoM would be entered as: .. code-block:: bash - ou=atomUsers,dc=example,dc=com + ou=atomUsers,dc=example,dc=com The **Bind Lookup Attribute** should be whatever attribute in your LDAP entries -will be globally unique, unlikely to change, and used to identify individual -users. If you want the login experience to match AtoM's current expectations +will be globally unique, unlikely to change, and used to identify individual +users. If you want the login experience to match AtoM's current expectations (using an email address in the username field) and your LDAP server is configured to use **mail** attributes for every user, then you would enter ``mail`` into -this field. +this field. If ``mail`` is not used in your LDAP server, ``uid`` is a good option, as this -typically shouldn't change even if the entry moves in the LDAP directory tree. +typically shouldn't change even if the entry moves in the LDAP directory tree. Barring that, ``cn`` could be used. Whatever is picked will define what type of -information end users attempting to authenticate in AtoM should enter into the -login panel's "Email" field. +information end users attempting to authenticate in AtoM should enter into the +login panel's "Email" field. .. image:: images/ldap-config-example.* :align: center @@ -325,27 +337,27 @@ After configuring the LDAP settings ----------------------------------- Once configured, users registered on the LDAP server should now be able to -authenticate with their LDAP credentials to log into AtoM. +authenticate with their LDAP credentials to log into AtoM. -When a user authenticates for the first time, a new AtoM user is created in the +When a user authenticates for the first time, a new AtoM user is created in the database. However, by default, this user is **not assigned to any user groups**, -and will therefore only have the base permissions of the Authenticated user -group. An :term:`administrator` can modify the user permissions after the -new user has been created using AtoM's permissions module - for more information, -see: +and will therefore only have the base permissions of the Authenticated user +group. An :term:`administrator` can modify the user permissions after the +new user has been created using AtoM's permissions module - for more information, +see: * :ref:`edit-user-permissions` * :ref:`manage-user-accounts` -.. IMPORTANT:: +.. IMPORTANT:: If switching to LDAP authentication *after* creating and configuring local - user accounts in AtoM, the most secure method to transition will likely be to - **delete** the local user accounts and let the LDAP authentication create new - ones, so that no passwords are stored in AtoM and no duplicate accounts exist. + user accounts in AtoM, the most secure method to transition will likely be to + **delete** the local user accounts and let the LDAP authentication create new + ones, so that no passwords are stored in AtoM and no duplicate accounts exist. The following points summarize how AtoM will attempt to validate authentication - attempts when there are existing user accounts: + attempts when there are existing user accounts: * As a first step, AtoM will check if a local account matches the user credentials if no LDAP match is found. This can allow users with existing @@ -357,10 +369,10 @@ see: This means that if the lookup attribute configured is **not** ``mail``, then a new account could be created, leaving the user with both a local user account and a newly created user account. - * If no local account match is found, AtoM will create a new default user, + * If no local account match is found, AtoM will create a new default user, whose only initial permissions in AtoM will be those of the Authenticated - :term:`user group`. No password will be stored in AtoM with this method, - since the LDAP server handles authentication. This is the default behavior - in AtoM when LDAP is enabled and no user accounts are present. + :term:`user group`. No password will be stored in AtoM with this method, + since the LDAP server handles authentication. This is the default behavior + in AtoM when LDAP is enabled and no user accounts are present. -:ref:`Back to top ` \ No newline at end of file +:ref:`Back to top ` diff --git a/dev-manual/env/compose.rst b/dev-manual/env/compose.rst index 4f3cf7f8..d0930801 100644 --- a/dev-manual/env/compose.rst +++ b/dev-manual/env/compose.rst @@ -90,6 +90,12 @@ It's time to use Docker Compose in order to provision our containers: latest version before creating the containers. It has to be based on Alpine v3.8 or higher to be able to install some packages. +.. note:: + + To enable LDAP Authentication with docker, jump to :ref:`Enable LDAP Authentication + with Docker `. + + .. code-block:: bash # Create and start containers. This may take a while the first time you run @@ -195,6 +201,46 @@ stop and remove related containers, network and volumes by running: docker-compose down --volumes +.. _ldap-auth-docker: + +Enable LDAP Authentication with Docker +====================================== + +.. code-block:: bash + + # Create and start containers. This may take a while the first time you run + # it because all the images have to be downloaded (e.g. percona, memcached) + # and the AtoM image has to be built. + # + # Launch AtoM with auth-network for openldap container. + docker-compose -f docker/docker-compose.dev.yml -f docker/docker-compose.auth-network.yml up -d + +There should be seven docker containers running, and getting the following warning +message is normal: ``WARNING: Some networks were defined but are not used by any +service: auth-network`` + +Check that auth-network exists by running: + +.. code-block:: bash + + docker network ls + +To get the host IP of your openldap container from ``auth-network``, run the following: + +.. code-block:: bash + + docker inspect auth-network + +You should see a container named ``openldap_openldap_1`` with an ``IPv4Address`` value. This +value will be used as the Host value in your LDAP authentication settings page. +For more information on enabling LDAP Authentication, see :ref:`Enable LDAP Authentiation `. + +.. note:: + + If you make changes to ``config/factories.yml`` after starting docker, you will + need to restart your ``atom_worker`` container by running ``docker compose restart + atom_worker`` for changes to take place. + Connect to AtoM ===============