LDAP configuration for a Model Manager server using Apache Directory Studio

Problem Description

I want to configure External Authentication for a Model Manager server using Lightweight Directory Access Protocol (LDAP) authentication, to allow users to log in with their domain accounts, but it's not clear how to fill in the LDAP Login Module configuration fields.

Solution

The LDAP Login Module, as an External Authentication configuration for a Model Manager server, works by verifying the given username and password against user credentials stored in an LDAP directory, for example Windows Active Directory.

This solution shows how to specify the configuration settings for the LDAP login module using the free Apache Directory Studio™ tool to prepare the configuration. Further information is available in the Model Manager Server Manual page for External Authentication and the Java® documentation for LdapLoginModule.

Using Apache Directory Studio to prepare the configuration

Setting up Apache Directory Studio

1. Download a suitable Apache Directory Studio archive from https://directory.apache.org/studio/downloads.html and extract it to some convenient location on your computer.
2. Download a Java 11 runtime archive, for example from https://adoptium.net/temurin/releases/?package=jre&version=11, and extract it within the Apache Directory Studio folder.
3. Rename the extracted Java runtime folder (inside the Apache Directory Studio folder) to jre to allow Apache Directory Studio to find it.

Connecting to the LDAP server

1. Launch Apache Directory Studio.
   • Ideally you should run Apache Directory studio on the computer where the Model Manager server is installed, so that the tool uses the same network interface as the server. If this is not possible, for example if running GUI tools is not allowed on the server computer, see Connecting through an SSH tunnel below.
2. In the LDAP menu select New Connection
3. In the New LDAP Connection dialog box:
   • Write some descriptive text for the connection in the Connection name field, say "My Connection".
   • The Hostname field should be the hostname of the LDAP server. Use a fully qualified hostname if you will use SSL encryption (LDAPS), to ensure that the server identity matches its certificate.
   • The Port field should be the TCP port to connect to on the LDAP server. The default port number is 389 for LDAP and 636 for LDAPS, but for Windows Active Directory servers it is recommended to instead use port 3268 for LDAP and port 3269 for LDAPS to access the global catalog.
   • For the Encryption method, pick either No encryption (LDAP) or Use SSL encryption (LDAPS) as these are the two methods supported by the LDAP login module. Ensure that the port number is compatible with the encryption method.
4. Click Check Network Parameter to verify that the LDAP server can be connected, then Next.
   • If you get a warning about an invalid certificate due to unknown issuer, choose to trust it if it is a known self signed certificate. In this case, you might also need to perform the steps under Trusting LDAP server certificates below to ensure that it is trusted by the Model Manager server.
5. Enter a username and a password for authenticating against the LDAP server. You might need to add a domain prefix (username@example.com) or suffix (EXAMPLE\username). Make a note of the username format used here, as it will be the format used for the Authentication identity field in the LDAP Login Module on the External Authentication page in the Model Manager server.
6. Click Check Authentication to verify that you can authenticate, then Finish.

Optional: Connecting through an SSH tunnel

If you run Apache Directory Studio on a different computer than the one where Model Manager server is installed, you can use an SSH tunnel to be able to connect to the LDAP server as if the tool was running on and connecting from the Model Manager server computer's network interface. This requires being able to connect to the Model Manager server computer using an SSH client with local tunneling enabled:

1. Open a Command Prompt (Windows) or Terminal (Linux/macOS) on the computer where you will run Apache Directory Studio.
2. Run ssh -L8888:ldaphostname:ldapport username@serverhostname, where 8888 is an arbitrary local port, ldaphostname:ldapport is the hostname and port of the LDAP server, and username@serverhostname is the hostname of the Model Manager server computer and the username to use to connect to it.
3. If the SSH connection succeeds, perform the steps under Connecting to the LDAP server above but fill in localhost as Hostname in the New LDAP Connection dialog box and 8888 as Port. For the Encryption method, use the same settings as you would have used if connecting directly from the Model Manager server computer.
4. The connection to localhost:8888 will be tunneled to serverhostname from which a connection to ldaphostname:ldapport is made.
5. The tunnel is open as long as the SSH connection is open, so keep the ssh command running until you are finished using Apache Directory Studio.

Tunneling the connection from the tool through the server computer is advantageous if you suspect that a firewall could block connections from the Model Manager server to the LDAP server. The blocked connection would then be detected already in the Check Network Parameter step, allowing you to first troubleshoot and fix the firewall configuration.

Locating the user provider folder

1. When connected to the LDAP server, go to the LDAP Browser view and expand the DIT node to browse the directory tree.
2. Locate a suitable top-level folder in the organization that contains in its subtree all of the users that should be able to log in. If users span multiple branches of the directory, pick a folder near the top of the tree to cover all locations.
3. Right-click that folder and do Advanced > Copy URL and save this URL somewhere to use for the User provider field on the External Authentication page.

Generating the user filter

1. Find a typical user in the directory, who should be allowed to log in. This can be done by manually browsing, or by using the Navigate > Go to DN feature if you know the distinguished name of the user (for example DN=John Smith).
2. In the list of attributes for the user, select the objectClass attribute with value user.
3. Then, with Ctrl pressed, scroll down to find and select a suitable attribute containing the username of the user (for example sAMAccountName for Active Directory).
4. Finally, look if there are any memberOf attributes that represent mandatory group memberships for logging in to the server and Ctrl select them as well.
5. With all relevant attributes selected, right-click and do Advanced > Copy AND Search Filter and save this filter somewhere to use as template for the User filter field on the External Authentication page.

Note: If you cannot locate a typical user in the directory, you can also try proceeding using one of these common user filters:

• Active Directory: (&(sAMAccountName={USERNAME})(objectclass=user))
• OpenLDAP: (&(uid={USERNAME})(objectClass=inetOrgPerson))

Optional: Generating filters for optional group memberships

Perform the following for any other group memberships that are not mandatory, but that you want to map to user groups for access control in the Model Manager server.

1. Similar to generating the user filter above, find a representative user that has the optional group memberships and select its attributes.
2. Generate a search filter and save it to use for the User filter field in additional optional LDAP login module instances on the External Authentication page.

Configuring the Model Manager server

Configuring external authentication

1. Log in to the Model Manager server web interface as a root administrator.
2. Go to Administration > System > External Authentication and click Edit.
3. Add an LDAP login module and set its Control flag to Requisite, meaning that it is required and the authentication chain stops if this login module doesn't succeed.
4. In the User provider field, enter the URL copied under Locating the user provider folder above.
5. In the User filter field, enter the search filter copied under Generating the user filter but replace the real username in this search filter with the string token {USERNAME}. For example, if the copied search filter is (&(objectClass=user)(sAMAccountName=john)), write (&(objectClass=user)(sAMAccountName={USERNAME})). The LDAP login module will replace the token with the username of the user trying to log in when searching for user credentials.
6. In the Authentication identity field, enter the username format you used under Connecting to the LDAP server but replace the real username with the string token {USERNAME}. For example, if you log in as zoe@example.com, write {USERNAME}@example.com. The LDAP login module will replace the token with the username of the user trying to log in when authenticating against the LDAP server.
7. If you used encryption in Apache Directory Studio, as will be seen by the user provider URL starting with ldaps://, leave Use SSL set to Enabled, otherwise switch it to Disabled. It's recommended to use encryption to not send usernames and password unencrypted to the LDAP server.
8. Click Test and use a known set of user credentials to verify that the authentication works. If possible, test both with user credentials that should have access and with those that are valid but shouldn't have access.
   • If SSL is enabled and you get an exception chain ending with a SunCertPathBuilderException exception with message unable to find valid certification path to requested target, see Trusting LDAP server certificates below to ensure that the server certificate is trusted.
9. Click Save and verify that users can log in.

Optional: Mapping a default Model Manager user group

Perform these steps if you want all users logging in with the external authentication configuration entered in Configuring external authentication to be assigned a specific Model Manager user group.

1. Edit the external authentication configuration and fill in a unique identifier for the group to assign in the Authorization identity field. For example, if the group is called engineering you can fill in engineering-user-group.
2. Add a group mapping with the Principal name set to the unique identifier (for example engineering-user-group) and a mapped group with Group Name engineering.
3. Save the configuration, and verify that a user logging in using the external authentication has the mapped group show up on the My Account page (available in the Account menu in the top right corner of the Model Manager server web page).

Optional: Mapping optional Model Manager user groups

Perform these steps if you generated search filters under Generating filters for optional group memberships above and want to use them to map optional external group memberships to Model Manager server user groups.

1. Edit the external authentication configuration and add another LDAP login module. Set the Control flag to Optional, meaning that authentication can succeed even if this module fails.
2. Fill in User provider and Authentication identity using the same values as under Configuring external authentication above.
3. Fill in the User filter field using the search filter for the optional group memberships, replacing the username with {USERNAME} as before.
4. Fill in the Authorization identity with a unique identifier for the optional group membership.
5. Add another group mapping for the optional group member ship, using the unique identifier as Principal name and the optional user group name as Group Name, similar to the instructions under Mapping a default Model Manager user group above.
6. Click Test to verify that the optional group is mapped if the user has a membership for it in the directory.
7. Repeat for any other optional user groups.
8. Save the configuration and verify that the optional user group mapping works.

If needed: Server certificate management

Trusting LDAP server certificates

If needed, follow the instructions below, based on the operating system that the Model Manager server is installed for, to ensure that the certificate of the LDAPS server is trusted by the Model Manager server.

You will first need to determine the root of the certificate chain of the LDAPS server, which will typically be a local CA certificate of your organization. If you don't already have it available as a file, see Retrieving the certificate chain of an LDAPS server below.

The certificate to trust can be put in any temporary location on the computer that runs the Model Manager server. After the certificate has been imported into the trust store, as described below, the certificate file is no longer used and can be removed from the temporary location.

On Windows (with a Model Manager server of version 6.2 and above)

Starting with version 6.2, the Model Manager server uses the built-in trust store of the Windows operating system so all you have to do is to import the root certificate into the Windows trust store.

1. Launch the built-in certlm.msc tool in Windows and navigate to the Trusted Root Certification Authorities > Certificates folder.
2. From the Action menu, choose Import and click Next to specify the file to import.
3. Click Browse or type the path to the certificate to import as a trusted root.
4. Click Next, Next and Finish, and verify that the certificate appears in the list.

On Linux® and macOS, or Windows (with a Model Manager server of version 6.1 and below)

On Linux and macOS systems (and prior to COMSOL version 6.2 also on Windows systems), the Model Manager server uses the trust store that comes with the Java runtime in the installation.

1. Find the path to the Java keytool that is included in the Model Manager server installation.
   • On Linux systems, the default path is /usr/local/comsol62/modelmanagerserver/java/glnxa64/jre/bin/keytool.
   • On macOS systems, the default path is /Applications/COMSOL62/ModelManagerServer/java/maci64/jre/bin/keytool
   • On Windows systems, the default path is C:\Program Files\COMSOL\COMSOL62\ModelManagerServer\java\win64\jre\bin\keytool.exe
   • Replace glnxa64 and maci64 with glnxarm64 and macarm64, respectively, on ARM64 based platforms.
2. Run keytool with arguments -importcert -cacerts -file myrootcert.pem -alias myrootcert, where the -file argument should point to the root certificate to import and -alias is the alias of the imported root certificate entry in the trust store.
   • You need to run the command with permissions to write to the installation directory.
   • The alias used must be unique within the keystore and does not have to match the filename. If you want to import multiple root certificates, pick a different alias for each one.
3. Enter the password of the Java cacerts file which is by default changeit.
4. Review the certificate information and answer yes if asked to import it.
   • If you get the error "Certificate not imported, alias already exists" the alias was already in use. Pick another alias, or use -delete -cacerts -alias myrootcert to delete the existing root certificate before importing the new one.

Note: There might be other COMSOL software installed on the system. Take care to locate the correct Model Manager server installation and run the keytool from the Java runtime of that installation. In particular, there's no need to trust the server certificate for the LDAP server in COMSOL Multiphysics installation.

Retrieving the certificate chain of an LDAPS server

The Java keytool is included in the Model Manager server installation, at the default paths given above under Trusting LDAP server certificates.

1. Run keytool with arguments -printcert -rfc -sslserver hostname:port, where hostname:port is the hostname and secure port of the LDAPS server.
   • If you get the error "No certificate from the SSL server", check that the hostname is correct and without ldaps:// prefix and that the port is the secure LDAPS port and not for example the non-secure LDAP port of the server.
2. The output should be blocks start start with -----BEGIN CERTIFICATE----- and end with -----END CERTIFICATE-----. Copy the last such block printed to the clipboard, which should typically correspond to the root of the certificate chain.
3. Paste the block in a text editor and save the file as myrootcert.pem to any temporary location.

Note: You should ensure that your connection to the LDAPS server is on a trusted network, as you could otherwise in theory retrieve the certificate chain from a malicious party in a man-in-the-middle attack. To reduce the risk of such an attack you should communicate with the server administrator over a trusted channel, after retrieving the certificate chain, to verify the root certificate fingerprint before trusting it.

Browse by Category