Private Cloud: LDAP and AD authentication

How it works
Prerequisites
Setting up LDAP or AD
Debugging
Restrictions

You can integrate Private Cloud Pro or Enterprise with the existing LDAP or Active Directory server and use that server as the source of user data.

This simplifies:

Authentication
Filling in user profiles
Allocation of access permissions between users in your company

How it works

Authentication via the LDAP server (when enabled) works the following way:

The user attempts to authenticate in Private Cloud, using their email or username and password.
The Private Cloud instance authorizes itself on the LDAP server, using credentials of the service account.
Using the filter expression from the configuration file, the instance identifies the user in the LDAP database by email or username and retrieves their distinguished name (dn).
Then, the instance tries to authenticate the user in LDAP by sending their dn and password.
If the user is successfully authenticated, the instance identifies their user groups using dn in a filter expression specified in the configuration file.
If any of the user’s groups are specified as the Cloud user or administrator group in the configuration file, the user authenticates and logs in to Private Cloud successfully.
A record for the user appears in the internal database of Private Cloud, and their user profile fields are populated by the data specified in the LDAP server database. Users originating from LDAP are marked as such within the database.

The procedure for Active Directory is the same, except the 2^nd step is omitted. The Private Cloud instance searches for user data, using the credentials provided by the user. Also, Active Directory uses a different configuration file.

Prerequisites

For authentication schemes involving an existing LDAP server, create a separate account for the Private Cloud instance. This account must have read access to the LDAP database. This allows Cloud to identify users and assign groups to them properly.

As mentioned earlier, Active Directory configurations don’t need you to create a service account for Private Cloud.

Setting up LDAP or AD

To prepare the connection

Go to the /home/alcadm/alc/controller/conf directory on the machine that serves the controller component.
Open the registration.json file.
Modify the value of the enterprise field in the providers object by adding the necessary providers:
- anylogic — enables user management functionality of AnyLogic Cloud
- ldap — enables the authentication via the LDAP server associated with the Private Cloud instance; the server should be specified in ldap.json
- ad — enables the authentication via the Active Directory server associated with the Private Cloud instance; the server should be specified in ad.json
The order in which the providers are listed matters! The instance first tries to identify the user in the first provider listed and switches to the next one only then.
Consider the following example configurations:
Regular (AnyLogic Cloud only)
```
{
  "enabled" : true,
  "enableGuestAccess" : true,
  "providers": {
    "enterprise": "anylogic"
  }
```
Enables the built-in authentication functionality only. Users should sign up and log in via Cloud forms.
AnyLogic Cloud + LDAP
```
{
  "enabled" : true,
  "enableGuestAccess" : true,
  "providers": {
    "enterprise": "anylogic, ldap"
  }
```
Upon an authentication attempt, Cloud will first try to authorize the user by comparing their credentials against the records in its internal database. If the user is not found (or marked as a previously logged-in LDAP user), the instance will establish a connection to the LDAP server and try to locate them there.
AnyLogic Cloud + AD
```
{
  "enabled" : true,
  "enableGuestAccess" : false,
  "providers": {
    "enterprise": "anylogic, ad"
  }
```
Upon an authentication attempt, Cloud will first try to authorize the user by comparing their credentials against the records in its internal database. If the user is not found (or marked as a previously logged-in Active Directory user), the instance will establish a connection to the Active Directory server and try to locate them there.
The enableGuestAccess option defines whether the unauthorized users will be able to view public models. If false, this feature is disabled.
LDAP only
```
{
  "enabled" : false,
  "enableGuestAccess" : false,
  "providers": {
    "enterprise": "ldap"
  }
```
With this configuration, Cloud won’t try to locate the user in its internal database and will perform a lookup in the LDAP database immediately instead.
With the value of the enabled option set as above, users can’t use the signup and login forms to create profiles and authenticate.
The enableGuestAccess option defines whether the unauthorized users will be able to view public models. If false, this feature is disabled.
AD only
```
{
  "enabled" : false,
  "enableGuestAccess" : false,
  "rootDn": "dc=example,dc=com",
  "providers": {
    "enterprise": "ad"
  }
```
With this configuration, Cloud will not attempt to locate the user in its internal database, but will immediately look up the user in the AD database.
If the value of the enabled option is set as above, users will not use the signup and login forms to create profiles and authenticate.
The enableGuestAccess option determines whether the unauthorized users will be able to view public models. If set to false, this feature is disabled.
The rootDn option in this configuration specifies the root distinguished name. You must use it in the rare case that the authenticating user’s username contains a domain name that is different from the Active Directory server’s domain name.
Save the registration.json file and close it.
Depending on the type of server you have listed in registration.json, open ldap.json or ad.json.

Specify setting of your LDAP/AD configuration:

It is possible to specify that certain fields on the server are binary-encoded. To do that, add b: to the beginning of the JSON string, for example:

"providerSpecificUid" : "b:objectGUID"

Example configuration: ldap.json

This file contains the settings that are required by the LDAP server configuration. If you are unfamiliar with the X.500 directory standard and its implementation in LDAP, check out the section on the LDAP directory structure in Wikipedia.

{
  "serverAddress" : "ldap://ldap.example.com:389/dc=example,dc=com",
  "cloudUserDN" : "cn=admin,dc=example,dc=com",
  "cloudUserPassword" : "xxx",
  "userSearchBase" : "ou=users",
  "userSearchFilter" : "(mail={0})",
  "groupSearchBase" : "ou=groups",
  "groupSearchFilter" : "groups={0}",
  "cloudAdminGroupName" : "Cloud Admins",
  "cloudUserGroupName" : "Cloud Users",
  "mapping" : {
    "providerSpecificUid" : "entryUUID",
    "email" : "mail",
    "firstName" : "givenName",
    "lastName" : "sn",
    "company" : "",
    "personalPage" : "",
    "linkedIn" : "",
    "description" : ""
}

Field	Description	Example
serverAddress	The URL of the LDAP server.	ldap://ldap.example.com:389/dc=example,dc=com This LDAP server URL includes the scheme, the explicit address and port, and a distinguished name (DN) of an entry domain. The distinguished name in this example consists of multiple DCs — domain components.
cloudUserDN	The distinguished name (DN) of the service account. For most regular LDAP servers, you need to create a service account specifically for the Private Cloud instance so it would be able to access your LDAP database.	cn=admin, dc=company, dc=com This name consists of two DCs (domain components, dc) and the common name (cn) of the account.
cloudUserPassword	The password of the service account. For most regular LDAP servers, you need to create a service account specifically for the Private Cloud instance so it would be able to access your LDAP database.
userSearchBase	The organizational unit (a user group) which the Private Cloud instance processes to identify the authenticating user.	ou=users In this example, we will use a filter expression provided in userSearchFilter to look for the user in the users organizational unit.
userSearchFilter	The filtering expression for user identification. Upon an authentication attempt by the user, {0} is replaced with the username of this user.	(mail={0}) In this example, we are searching for the user by comparing the username (or email) they provided with the values of the mail attribute. The search takes place in user records belonging to the group specified in userSearchBase.
groupSearchBase	The organizational unit which the Private Cloud processes to identify groups the user belongs to.	ou=groups In this example, we will use a filter expression provided in groupSearchFilter to check whether the user is part of any LDAP groups belonging to the groups organizational unit.
groupSearchFilter	The filter expression for group identification. {0} is replaced by dn. The instance obtains the user’s dn after the successful identification of the user fueled by userSearchBase and userSearchFilter.	groups={0} In this example, we will check the groups listed in groupSearchBase for a user by their distinguished name (dn).
cloudAdminGroupName	The common name (cn) of the group whose members should have administrator permissions in the Private Cloud instance.	Cloud Administrators
cloudUserGroupName	The common name (cn) of the group whose members should be users of the Private Cloud instance.	Cloud Users

The mapping object

This is a JSON object that establishes a value mapping between LDAP-specific fields and Private Cloud fields. Upon authentication of the LDAP or AD user, their Cloud profile will be populated with information following this mapping.

Field	Description	Example
providerSpecificUid	Obligatory. Specifies the LDAP/AD field which value Private Cloud should use to unambiguously identify the LDAP user since other fields’ values can be modified from the LDAP server’s side.	entryUUID
email	Obligatory (the internal structure of Private Cloud user records implies that all users have unique emails). Specifies the LDAP/AD field that contains the user’s email.	mail
firstName	Optional. Specifies the LDAP/AD field that contains the user’s first name.
lastName	Optional. Specifies the LDAP/AD field that contains the user’s last name.
company	Optional. Specifies the LDAP/AD field that contains the name of the user’s company.
personalPage	Optional. Specifies the LDAP/AD field that contains the link to the user’s personal page.
linkedIn	Optional. Specifies the LDAP/AD field that contains the link to the user’s LinkedIn page.
description	Optional. Specifies the LDAP/AD field that contains supplementary information about the user.

The mapped fields will not be editable in Private Cloud: neither users (via their user profile page) nor administrators (via the administrator panel) will be able to modify their values from the Cloud side.

Example configuration: ad.json

This file contains the settings that are required by the Active Directory server configuration. If you are unfamiliar with the X.500 directory standard and its implementation in AD, consider checking out the section on AD directory structure in Wikipedia.

{
  "serverAddress" : "ldap://ad.example.com",
  "domain" : "domain.example.com",
  "cloudAdminGroupName" : "Administrators",
  "cloudUserGroupName" : "Cloud Users",
  "rootDn": "dc=example,dc=com",
  "mapping" : {
    "providerSpecificUid" : "b:objectGUID",
    "email" : "userPrincipalName",
    "firstName" : "givenName",
    "lastName" : "sn",
    "company" : "",
    "personalPage" : "",
    "linkedIn" : "",
    "description" : ""
  }
}

Field	Description	Example
serverAddress	The URL of the Active Directory server.	ldap://ad.example.com
domain	The Active Directory domain name.	domain.example.com
cloudAdminGroupName	The name of the group whose members should have administrator permissions in the Private Cloud instance.	Administrators
cloudUserGroupName	The name of the group whose members should be users of the Private Cloud instance.	Administrators
rootDn	The distinguished name of the root. Needs to be specified if the user name of the authenticating user is different from the Active Directory domain name.	dc=example,dc=com

The mapping object

Field	Description	Example
providerSpecificUid	Obligatory. Specifies the LDAP/AD field which value Private Cloud should use to unambiguously identify the LDAP user since other fields’ values can be modified from the LDAP server’s side.	entryUUID
email	Obligatory (the internal structure of Private Cloud user records implies that all users have unique emails). Specifies the LDAP/AD field that contains the user’s email.	mail
firstName	Optional. Specifies the LDAP/AD field that contains the user’s first name.
lastName	Optional. Specifies the LDAP/AD field that contains the user’s last name.
company	Optional. Specifies the LDAP/AD field that contains the name of the user’s company.
personalPage	Optional. Specifies the LDAP/AD field that contains the link to the user’s personal page.
linkedIn	Optional. Specifies the LDAP/AD field that contains the link to the user’s LinkedIn page.
description	Optional. Specifies the LDAP/AD field that contains supplementary information about the user.

Save and close the configuration file.
To apply changes you have made in JSON files, stop the controller and rest components by executing the following command in the Linux terminal on the machine that serves this component:
sudo docker stop controller rest
After that, start the controller component manually:
sudo docker start controller

After that, your users should be able to log in to the Private Cloud instance using their LDAP/AD credentials.

Debugging

To learn more about troubleshooting your Private Cloud / LDAP setup, see the corresponding section in the Private Cloud: Troubleshooting article.

Restrictions

Private Cloud supports integration with one LDAP server plus one AD server at a time.
When an external LDAP/AD authentication is enabled (that is, ldap or ad are listed in registration.json), the model sharing functionality is disabled for users that have not logged into the instance beforehand.

How can we improve this article?