LDAP Authentication in MATLAB Online Server

In MATLAB^® Online Server™, you can configure authentication using a Lightweight Directory Access Protocol (LDAP) identity provider (IdP). For details about this protocol, see the LDAP website.

Prerequisites

MATLAB Online Server is installed. See Installation.
Your organization's IdP follows the LDAP protocol.
You have access to your IdP. To obtain access, contact your identity management administrator.
You are familiar with the MATLAB Online Server authentication workflow. See Configure User Authentication in MATLAB Online Server.

Open Configuration File

In a plain-text editor, open the authnz.yaml file, which configures information about your IdP.

<server-root>/overrides/<cluster-name>/<namespace-name>/authnz.yaml

<server-root> is the MATLAB Online Server installation folder.
<cluster-name> is the name of the Kubernetes^® cluster.
<namespace-name> is the namespace of the MATLAB Online Server deployment.

Sample path:

~/matlab_online_server/overrides/matlab-online-server/mathworks/authnz.yaml

Remove Local Accounts

If your configuration still includes local accounts (type: "local"), remove them from the authnz.yaml file or comment them out. For example:

identityProviders:
#  - id: "local"
#    type: "local"
#    accounts:
#      - subjectId: "admin"
#        displayName: "admin"
#        password: "password"
#        extra: {}

Security Considerations: Local user accounts are for testing purposes only and do not meet production security standards. Deploying them to production is not recommended.

Configure Identity Provider

In the identityProviders section, add the following structure and update the fields with information from your IdP. Commented-out fields are optional. Fields with values in angle brackets (<>) have no defaults.

identityProviders:
  - id: "<display name used identify IdP on server>"
    type: "ldap"
    host: "<LDAP host address>"
    port: <LDAP port number>
#   useStartTls: false
#   useSsl: false
    baseDn: "<starting point for LDAP search tree>"
    filter: "<LDAP search filter>"
    adminDn: "<admin account name>"
    adminPassword: "<admin account password>"
#   subjectAttributeMapping:
#     subjectId: "<username attribute in IdP>"
#     displayName: "<display name attribute in IdP>"
#     groups: "<user group attribute in IdP>"
#     extra:
#       email: "<user email attribute in IdP>"
#       uid: "<UNIX user ID attribute in IdP>"
#       gid: "<UNIX group ID attribute in IdP>"

Field	Default Value	Required or Optional	Description
`id`	`""`	Required	Display name that identifies the IdP in MATLAB Online Server microservices and log files.
`type`	`"ldap"`	Required	Type of IdP. To configure local user accounts, you must set `type` to `"ldap"`.
`host`	`""`	Required	LDAP host address. Example: `"ldapserver.yourcompany.com"`
`port`	`""`	Required	Port number for the LDAP host address. Example: `"389"` (for regular LDAP) Example: `"636"` (for secure LDAP)
`useStartTls`	`false`	Optional	Set whether your LDAP server requires using the `STARTTLS` command for connection. If you set `useStartTls` to true, then you must add the trusted certificates to the MATLAB Online Server trust store. See the Add Certificates to MATLAB Online Server Trust Store section.
`useSsl`	`false`	Optional	Set whether your LDAP server requires SSL for connection. If you set `useSsl` to true, then you must add the trusted certificates to the MATLAB Online Server trust store. See the Add Certificates to MATLAB Online Server Trust Store section.
`baseDn`	`""`	Required	Starting point for the search tree in your LDAP environment. Example: `"dc=ldap,dc=yourcompany,dc=com"`
`filter`	`""`	Required	LDAP search filter. Use the search filter to scan a subset of users from the LDAP database. This field allows you to reduce the scope of the LDAP search and control which organizational user may access MATLAB Online Server. You can leverage variable substitution to configure how the server provides the username to LDAP, for example: `"(CN={0})"`. Specify the search filter as `attribute=value`, for example, `CN=test*` matches all users that have a common name (CN) attribute that starts with `test`. Use parentheses to combine multiple filter expressions in an AND (&) or OR (\|) clause. For example, `"(&(CN={0})(department=foo))"` matches all users who are in department `foo`. The default search filter is `objectClass=organizationalPerson`. For more information on search filters, see LDAP filters on the LDAP website.
`adminDn`	`""`	Required	Administrator account that establishes the connection to the LDAP server. MATLAB Online Server uses this account to query the LDAP server for the directory of users. The account requires only read access to the directory and does not attempt to store information in the LDAP server. Example: `"cn=readonly"`
`adminPassword`	`""`	Required	Administrator account password that establishes the connection to the LDAP server.
`subjectAttributeMapping`	`{}`	Optional	Map of user-related attributes from your IdP to the corresponding YAML fields in MATLAB Online Server. The server uses these fields to look up information about the user for use across services on the cluster. Valid fields are as follows. Enclose each `subjectAttributeMapping` field value in quotes. subjectAttributeMapping: subjectId: "<IdP username attribute>" displayName: "<IdP display name attribute>" groups: "<IdP user group attribute>" extra: email: "<IdP user email attribute>" uid: "<IdP UNIX user ID attribute>" gid: "<IdP UNIX group ID attribute>" `subjectId` — Username or user ID attribute in IdP. When the server checks out a license, the value from this attribute appears in license server logs. `displayName` — User display name attribute in IdP. The value from this attribute appears in the MATLAB Online Server user interface. `groups` — Group attribute in IdP. Values from this attribute lists the groups that the user belongs to. You can use these values in the `allowedGroups` field of the `matlab-pool` YAML file to restrict MATLAB access to specific user groups. For details, see Configure Group-Based Authorization in MATLAB Online Server. `extra` — Additional IdP attributes that the server uses to configure user-specific storage folders on the network file system. `email` — User email address attribute in IdP `uid` — UNIX^® user ID attribute in IdP `gid` — UNIX group ID attribute in IdP Do not leave any field in the `extra` section empty. Either specify a value or remove the empty field. If your `extra` section is empty, omit the section entirely. For details on how to configure user storage by using these fields, see Configure File Storage for Users in MATLAB Online Server.

Sample Configuration

identityProviders:
  - id: "ldap"
    type: "ldap"
    displayName: "LDAP"
    host: "ldap"
    port: 636
    useStartTls: true
    useSsl: true
    baseDn: "dc=matlabonlineserver,dc=mwcloudtest,dc=com"
    filter: "(uid={0})"
    adminDn: "cn=readonly,dc=matlabonlineserver,dc=mwcloudtest,dc=com"
    adminPassword: "readonly"
    subjectAttributeMapping:
      subjectId: "uid"
      displayName: "cn"
      groups: "groups"
      extra:
        uid: "uidNumber"

Add Certificates to MATLAB Online Server Trust Store

When you use LDAPS or LDAP with TLS, you must add certificates to the global trust store. MATLAB Online Server validates these certificates against the LDAP/LDAPS server to establish a secure connection.

You must add the certificate information, shown in the following table, to the authnz.yaml file.

In the authnz.yaml file, above the identityProviders section, add a top-level global section with the following structure. Then, update the fields with information about your trusted certificates.

global:
  tls:
    validateCertificate: true
    trustedCertificates: <server certificates>

Field Default Value Required or Optional Description

Field	Default Value	Required or Optional	Description
`validateCertificate`	`true`	Optional	Enable certificate verification for the `authnz` service while communicating with external identity providers. For example, when `useSSL= true` or `useTLS = true`, the `authnz` service validates the secure communication. If you disable this field, the communication is still through LDAPS, but the `authnz` service skips certificate verification.
`trustedCertificates`	`""`	Optional	Server certificates required for communicating with the external identity providers in the `authnz` service. The certificates must be formatted using PEM. For details on PEM, see: PEM format requirements for certificates and domain keys on the Broadcom^® website PEM, DER, CRT, and CER: X.509 Encodings and Conversions on the SSL website For example, when `useSSL = true` or `useTLS = true`, the server requires validating the secure communication using the specified certificates. If you do not specify the certificates, LDAPS communication fails.

validateCertificate

true

Optional

Enable certificate verification for the authnz service while communicating with external identity providers.

For example, when useSSL= true or useTLS = true, the authnz service validates the secure communication.

If you disable this field, the communication is still through LDAPS, but the authnz service skips certificate verification.

trustedCertificates

""

Optional

Server certificates required for communicating with the external identity providers in the authnz service.

The certificates must be formatted using PEM. For details on PEM, see:

PEM format requirements for certificates and domain keys on the Broadcom^® website
PEM, DER, CRT, and CER: X.509 Encodings and Conversions on the SSL website

For example, when useSSL = true or useTLS = true, the server requires validating the secure communication using the specified certificates.

If you do not specify the certificates, LDAPS communication fails.

Sample Configuration

global:
  tls:
    validateCertificate: true
    trustedCertificates: | 
          -----BEGIN CERTIFICATE-----
          MIIC5DCCAk2gAwIBAgIUZhnmeMmayNSTcAI2hgyxQt6GotUwDQYJKoZIhvcNAQEL
          ...
          VA/d/fQ+yxUjlDBc6ly/OwVFtIr0QykE
          -----END CERTIFICATE-----
          -----BEGIN CERTIFICATE-----
          BQAwgYMxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJNQTEPMA0GA1UEBwwGTmF0aWNr
          ...
          EdUg4pCYWUyFgGA/QCg4EniQEMN
          -----END CERTIFICATE-----

Deploy Configuration

To deploy your changes to the server, redeploy the authnz service. From the MATLAB Online Server root folder, run these commands.

./mosadm undeploy authnz
./mosadm deploy authnz

If your IdP configures single sign-on (SSO), your users can now sign in to MATLAB Online™ using their SSO credentials.

If you are configuring multiple IdPs, the server uses the first IdP listed in the identityProviders section as the default IdP. To authenticate users with a nondefault IdP, in the MATLAB Online URL you give to users, include an IdPId query parameter that specifies the ID value of the IdP. For example:

https://<domain-base>/matlabonline?idpId=<id>

where <domain-base> is the value of the DOMAIN_BASE property in your install.config file. For more information, see Configure Multiple Identity Providers.