Configure LDAP Server Authentication for MATLAB Job Scheduler

Since R2023a

Configure MATLAB^® Job Scheduler to use your company Lightweight Directory Access Protocol (LDAP) server to authenticate user credentials. Follow these instructions to configure LDAP server authentication when you integrate MATLAB Job Scheduler with your cluster.

Prerequisites

If this is the first time you are integrating MATLAB Job Scheduler with your cluster, see this page for the most common configuration options: Install for MATLAB Job Scheduler with Network License Manager.

In these instructions, matlabroot refers to the location of your installed MATLAB Parallel Server™ software. Where you see this term used in these instructions, substitute the path with the location of your installation.

Edit MATLAB Job Scheduler Parameter File

To configure LDAP server authentication, you must edit the mjs_def file on your headnode before installing the mjs service and starting MATLAB Job Scheduler. You can find this file in these locations:

matlabroot\toolbox\parallel\bin\mjs_def.bat on Windows^® operating systems
matlabroot/toolbox/parallel/bin/mjs_def.sh on Linux^® operating systems

To learn more about the parameters in the mjs_def file, see Define MATLAB Job Scheduler Startup Parameters.

Use these parameters to configure your company's LDAP server with your MATLAB Job Scheduler cluster. Edit the parameters in the mjs_def file with the required values.

Parameter	Description	Values
`SECURITY_LEVEL`	Security level for the cluster. To learn more about security levels and other parameters, see Set MATLAB Job Scheduler Cluster Security.	`Level 2` or `Level 3`
`ADMIN_USER`	Username of the cluster administrator. `ADMIN_USER` must be a valid username in the LDAP server. Note When you start the job manager, the `mjs` service must authenticate the cluster administrator against the LDAP server to proceed. You must provide the LDAP server password of the cluster administrator when the mjs service prompts you.	Valid username in the LDAP server
`USE_LDAP_SERVER_AUTHENTICATION`	Option to use an LDAP server to authenticate user credentials.	`true`
`LDAP_URL`	URL of the LDAP server. Note Security Considerations: Use LDAP over SSL (LDAPS) to encrypt communication between the LDAP server and clients. For additional LDAPS configuration steps, see Configure LDAP over SSL (LDAPS).	Specify the LDAP_URL as: ldaps://HOST:PORT If you have not configured your LDAP server over SSL, specify the URL as: ldap://HOST:PORT
`LDAP_SECURITY_PRINCIPAL_FORMAT`	Format of a security principal (user) for your LDAP server.	Common formats include: `cn=[username],ou=Users,dc=domain,dc=com` `[username]@domain.com`
`LDAP_SYNCHRONIZATION_INTERVAL_SECS`	Frequency at which the cluster synchronizes with the LDAP server.	Positive number corresponding to the number of seconds between synchronizations. Default value is 1800 seconds. To synchronize the cluster with the LDAP server every time the cluster requires user authentication, set this parameter to `0`.

Configure LDAP over SSL (LDAPS)

When you use an LDAP server configured over SSL, you must add the LDAPS SSL certificate to the Java^® certificate trust store of your MATLAB Parallel Server installation. The mjs service validates the certificate against the LDAPS server to establish an encrypted connection.

The LDAPS SSL certificate must be formatted using PEM. For details about PEM, see:

These instructions show how to get an SSL certificate and add it to the Java certificate trust store.

Connect to LDAP Server to Get Server SSL Certificate

You can use the openssl toolkit with the s_client command to get the LDAP server SSL diagnostic information.

For example, to get the SSL diagnostic information from the LDAP server my.LDAP.Server.com at port 636, run this command in a Linux or Windows command window:

echo | openssl s_client -connect my.LDAP.Server.com:636 > myLDAPServer.com.cert.pem

The command generates the myLDAPServer.com.cert.pem file, which contains the LDAP server SSL diagnostic information. Edit the myLDAPServer.com.cert.pem file so that it contains only this text:

-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----

Add Certificate to Java Certificate Trust Store

The default Java certificate trust store is in these folders:

matlabroot\sys\java\jre\win64\jre\lib\security\cacerts on Windows operating systems
matlabroot/sys/java/jre/glnxa64/jre/lib/security/cacerts on Linux operating systems

To add the SSL certificate to the Java certificate trust store of your MATLAB Parallel Server installation, use the keytool key and certificate management utility. The keytool utility is available with your MATLAB Parallel Server installation at these locations:

matlabroot\sys\java\jre\win64\jre\bin on Windows operating systems
matlabroot/sys/java/jre/glnxa64/jre/bin on Linux operating systems

For more information, see keytool.

Before you import the server certificate to the Java certificate trust store, you must first make the cacerts file writable. For example, on a Linux host, run these commands:

cd matlabroot/sys/java/jre/glnxa64/jre/lib/security
chmod +w cacerts

Import the server certificate to the Java certificate trust store of the MATLAB Parallel Server installation. The default password for the keytool that comes with your MATLAB installation is changeit. You must enter the password when the keytool prompts you for a password.

matlabroot/sys/java/jre/glnxa64/jre/bin/keytool -import -keystore cacerts -file /path/to/server/certificate/myLDAPServer.com.cert.pem

Start MATLAB Job Scheduler and Test LDAP Server Authentication

To start MATLAB Job Scheduler, see Start mjs Service, MATLAB Job Scheduler, and Workers (Command-Line).

You can connect to MATLAB Job Scheduler cluster and validate the cluster profile. You need your LDAP login username and password to access the cluster. For instructions that show how to validate your new MATLAB Job Scheduler cluster, see Connect MATLAB Client to MATLAB Parallel Server Cluster.