# LDAP Integration

HEAVY.AI supports LDAP authentication using an IPA Server or Microsoft Active Directory.

You can configure HEAVY.AI Enterprise edition to map LDAP roles 1-to-1 to HEAVY.AI roles. When you enable this mapping, LDAP becomes the main authority controlling user roles in HEAVY.AI.

{% hint style="info" %}
LDAP mapping is available only in HEAVY.AI Enterprise edition.
{% endhint %}

HEAVY.AI supports five configuration settings that allow you to integrate with your LDAP server.

| Parameter               | Description                                                                                                                         | Example                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ldap-uri`              | LDAP server host or server URI.                                                                                                     | `ldap://myLdapServer.myCompany.com`                                                               |
| `ldap-dn`               | LDAP distinguished name (DN).                                                                                                       | `uid=$USERNAME,cn=users,cn=accounts, dc=myCompany,dc=com`                                         |
| `ldap-role-query-url`   | Returns the role names a user belongs to in the LDAP.                                                                               | `ldap://myServer.myCompany.com/uid=$USERNAME, cn=users, cn=accounts,dc=myCompany,dc=com?memberOf` |
| `ldap-role-query-regex` | Applies a regex filter to find matching roles from the roles in the LDAP server.                                                    | `(MyCompany_.*?),`                                                                                |
| `ldap-superuser-role`   | Identifies one of the filtered roles as a superuser role. If a user has this filtered ldap role, the user is marked as a superuser. | `MyCompany_SuperUser`                                                                             |

## Obtaining Credential Information

To find the `ldap-role-query-url` and `ldap-role-query-regex` to use, query your user roles. For example, if there is a user named kiran on the IPA LDAP server `ldap://myldapserver.mycompany.com`, you could use the following curl command to get the role information:

```bash
$ curl --user "uid=kiran,cn=users,cn=accounts,dc=mycompany,dc=com" 
"ldap://myldapserver.mycompany.com/uid=kiran,cn=users,cn=accounts,dc=mycompany,dc=com?memberOf"
```

When successful, it returns information similar to the following:

```bash
DN: uid=kiran,cn=users,cn=accounts,dc=mycompany,dc=com
memberOf: cn=ipausers,cn=groups,cn=accounts,dc=mycompany,dc=com
memberOf: cn=MyCompany_SuperUser,cn=roles,cn=accounts,dc=mycompany,dc=com
memberOf: cn=test,cn=groups,cn=accounts,dc=mycompany,dc=com
```

* `ldap-dn` matches the DN, which is `uid=kiran,cn=users,cn=accounts,dc=mycompany,dc=com`.
* `ldap-role-query-url` includes the LDAP URI + the DN + the LDAP attribute that represents the role/group the member belongs to, such as memberOf.
* `ldap-role-query-regex` is a regular expression that matches the role names. The matching role names are used to grant and revoke privileges in HEAVY.AI. For example, if we created some roles on an IPA LDAP server where the role names begin with *MyCompany\_* (for example, \_MyCompany\_\_Engineering, *MyCompany*\_Sales, \_MyCompany\_\_SuperUser), the regular expression can filter the role names using *MyCompany\_*.
* `ldap-superuser-role` is the role/group name for HEAVY.AI users who are superusers once they log on to the HEAVY.AI database. In this example, the superuser role name is *MyCompany*\_SuperUser.

{% hint style="warning" %}
Make sure that LDAP configuration appears before the `[web]` section of `heavy.conf`.
{% endhint %}

{% hint style="info" %}
Double quotes are not required for LDAP properties in `heavy.conf`. For example, both of the following are valid:

`ldap-uri = "ldap://myldapserver.mycompany.com"`\
`ldap-uri = ldap://myldapserver.mycompany.com`
{% endhint %}

## Setting Up LDAP with HEAVY.AI

To integrate LDAP with HEAVY.AI, you need the following:

* A functional LDAP server, with all users/roles/groups created (`ldap-uri`, `ldap-dn`, `ldap-role-query-url`, `ldap-role-query-regex`, and `ldap-superuser-role`) to be used by HEAVY.AI. You can use the `curl` command to test and find the filters.
* A functional HEAVY.AI server, version 4.1 or higher.

Once you have your server information, you can configure HEAVY.AI to use LDAP authentication.

1. Locate the `heavy.conf` file and edit it to include the LDAP parameter. For example:

   ```
   ldap-uri = "ldap://myldapserver.mycompany.com"
   ldap-dn = "uid=$USERNAME,cn=users,cn=accounts,dc=mycompany,dc=com"
   ldap-role-query-url = "ldap://myldapserver.mycompany.com/uid=$USERNAME,cn=users,cn=accounts,dc=mycompany,dc=com?memberOf"
   ldap-role-query-regex = "(MyCompany_.*?),"
   ldap-superuser-role = "MyCompany_SuperUser"
   ```
2. Restart the HEAVY.AI server:

   ```
   sudo systemctl restart heavyai_server
   sudo systemctl restart heavyai_web_server
   ```
3. Log on to `heavysql` as MyCompany user, or any user who belongs to one of the roles/groups that match the filter.

{% hint style="warning" %}
When you use LDAP authentication, the default **admin** user and password **HyperInteractive** do not work unless you create the admin user with the same password on the LDAP server.
{% endhint %}

If your login fails, inspect `$HEAVYAI_STORAGE/mapd_log/heavyai_server.INFO` to check for any obvious errors about LDAP authentication.

Once you log in, you can create a new role name in `heavysql`, and then apply GRANT/REVOKE privileges to the role. Log in as another user with that role and confirm that GRANT/REVOKE works.

{% hint style="info" %}
If you refresh the browser window, you are required to log in and reauthenticate.
{% endhint %}

## Using LDAPS

To use LDAPS, HEAVY.AI must trust the LDAP server's SSL certificate. To achieve this, you must have the CA for the server's certificate, or the server certificate itself. Install the certificate as a trusted certificate.

### IPA on CentOS

To use IPA as your LDAP server with HEAVY.AI running on CentOS 7:

1. Copy the IPA server CA certificate to your local machine.

   ```
   scp root@myldapserver:/etc/ipa/ca.crt /etc/pki/ca-trust/source/anchors/ipa-ca.pem
   ```
2. Update the PKI certificates.

   ```
   update-ca-trust
   ```
3. Edit `/etc/openldap/ldap.conf` to add the following line.

   ```
   TLS_CACERT      /etc/pki/tls/certs/ca-bundle.crt
   ```
4. Locate the `heavy.conf` file and edit it to include the LDAP parameter. For example:

   ```
   ldap-uri = "ldaps://myldapserver.mycompany.com"
   ldap-dn = "uid=$USERNAME,cn=users,cn=accounts,dc=mycompany,dc=com"
   ldap-role-query-url = "ldaps://myldapserver.mycompany.com/uid=$USERNAME,cn=users,cn=accounts,dc=mycompany,dc=com?memberOf"
   ldap-role-query-regex = "(MyCompany_.*?),"
   ldap-superuser-role = "MyCompany_SuperUser"
   ```
5. Restart the HEAVY.AI server:

   ```
   sudo systemctl restart heavyaidb
   sudo systemctl restart heavyai_web_server
   ```

### IPA on Ubuntu

To use IPA as your LDAP server with HEAVY.AI running on Ubuntu:

1. Copy the IPA server CA certificate to your local machine.

   ```
   mkdir /usr/local/share/ca-certificates/ipa
   scp root@myldapserver:/etc/ipa/ca.crt /usr/local/share/ca-certificates/ipa/ipa-ca.pem
   ```
2. Rename `ipa-ca.crm` to `ipa-ca.crt` so that the certificates bundle update script can find it:

   ```
   mv /usr/local/share/ca-certificates/ipa/ipa-ca.pem /usr/local/share/ca-certificates/ipa/ipa-ca.crt
   ```
3. Update the PKI certificates:

   ```
   update-ca-certificates
   ```
4. Edit `/etc/openldap/ldap.conf` to add the following line:

   ```
   TLS_CACERT      /etc/ssl/certs/ca-certificates.crt
   ```
5. Locate the `heavy.conf` file and edit it to include the LDAP parameter. For example:

   ```
   ldap-uri = "ldaps://myldapserver.mycompany.com"
   ldap-dn = "uid=$USERNAME,cn=users,cn=accounts,dc=mycompany,dc=com"
   ldap-role-query-url = "ldaps://myldapserver.mycompany.com/uid=$USERNAME,cn=users,cn=accounts,dc=mycompany,dc=com?memberOf"
   ldap-role-query-regex = "(MyCompany_.*?),"
   ldap-superuser-role = "MyCompany_SuperUser"
   ```
6. Restart the HEAVY.AI server:

   ```
   sudo systemctl restart heavydb
   sudo systemctl restart heavyai_web_server
   ```

### Active Directory

1\. Locate the `heavy.conf` file and edit it to include the LDAP parameter.

**Example 1**:

```
ldap-uri = "ldap://myldapserver.mycompany.com"
ldap-dn = "cn=$USERNAME,cn=users,dc=qa-mycompany,dc=com"
ldap-role-query-url = "ldap:///myldapserver.mycompany.com/cn=$USERNAME,cn=users,dc=qa-mycompany,dc=com?memberOf"
ldap-role-query-regex = "(HEAVYAI_.*?),"
ldap-superuser-role = "HEAVYAI_SuperUser"
```

**Example 2**:

```
ldap-uri = "ldap://myldapserver.mycompany.com"
ldap-dn = "$USERNAME@mycompany.com"
ldap-role-query-url = "ldap:///myldapserver.mycompany.com/OU=MyCompany Users,dc=MyCompany,DC=com?memberOf?sub?(sAMAccountName=$USERNAME)"
ldap-role-query-regex = "(HEAVYAI_.*?),"
ldap-superuser-role = "HEAVYAI_SuperUser"
```

2\. Restart the HEAVY.AI server:

```
sudo systemctl restart heavyai_server
sudo systemctl restart heavyai_web_server
```

{% hint style="info" %}
Other LDAP user authentication attributes, such as userPrincipalName, are not currently supported.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heavy.ai/installation-and-configuration/security/ldap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.