---
title: "Lightweight Directory Access Protocol (LDAP)"
description: "This page describes TigerGraph's support for integrating with LDAP systems."
component: "tigergraph-server"
version: "4.3"
module: "user-access"
html_url: "/tigergraph-server/4.3/user-access/ldap"
canonical_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/ldap"
markdown_url: "https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/ldap.md"
---

[View as HTML](https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/ldap)

# Lightweight Directory Access Protocol (LDAP)

TigerGraph supports LDAP authentication by allowing a TigerGraph user to log in using an LDAP username and credentials. This page provides instructions on how to configure LDAP, map LDAP users to GSQL users, as well as specific instructions for integration with Active Directory (AD).

TigerGraph LDAP authentication supports any LDAP server that follows the LDAPv3 protocol. StartTLS/SSL connection is also supported.

> [!NOTE]
> Some LDAP servers are configured to require a client certificate upon connection. Client certificates are not supported in TigerGraph LDAP authentication.

## LDAP configuration parameters

TigerGraph uses the following parameters for LDAP configuration.

| Name | Description | Example |
| --- | --- | --- |
| Security.LDAP.AdminDN | Configure the DN of LDAP user who has read access to the base DN specified above. Empty if everyone has read access to LDAP data. Default value is empty; | `nan` |
| Security.LDAP.AdminPassword | Configure the password of the admin DN specified above. Needed only when `Security.LDAP.AdminDN` is specified. Default value is empty. If the value provided is a path to a script, the parameter will be set to the output of the script. | `secret` |
| Security.LDAP.BaseDN | Configure LDAP search base DN, the root node to start the LDAP search for user authentication. | `nan` |
| Security.LDAP.Enable | Enable LDAP authentication: default false | `false` |
| Security.LDAP.GroupFilter | list of group objects on LDAP server used to retrieve group hierarchy information, default value: (objectClass=group) | (objectClass=group) |
| Security.LDAP.GroupHierarchyRefreshIntervalMin | Refresh time in minutes of ldap group hierarchy information. default 240 | 60 |
| Security.LDAP.Hostname | Configure LDAP server hostname: default localhost | `localhost` |
| Security.LDAP.Port | Configure LDAP server port: default 389 | `389` |
| Security.LDAP.SearchFilter | Configure LDAP search filter. Only objects that satisfy the conditions in the filter | `(objectClass=*)` |
| Security.LDAP.Secure.Protocol | Enable SSL/StartTLS for LDAP connection \[none/ssl/starttls\]: default none | `none` |
| Security.LDAP.Secure.TrustAll | Configure to trust all LDAP servers (unsafe): default false | `false` |
| Security.LDAP.Secure.TruststoreFormat | Configure the truststore format \[JKS/PKCS12\]: default JKS | `JKS` |
| Security.LDAP.Secure.TruststorePassword | Configure the truststore password: default `changeit`. | `changeit` |
| Security.LDAP.Secure.TruststorePath | Configure the truststore absolute path for the certificates used in SSL: default empty. If the value provided is a path to a script, the parameter will be set to the output of the script. | `nan` |
| Security.LDAP.UsernameAttribute | Configure the username attribute name in LDAP server: default uid | `uid` |

## Configure TigerGraph to use LDAP

To enable and configure LDAP, run the following command:

Configure LDAP:

```console
$ gadmin config entry ldap
```

This prompts the user to enter the values for the LDAP configuration parameters.

1. Set `Security.LDAP.Enable` to true. This configures TigerGraph to use LDAP for authentication.
2. For `Security.LDAP.Hostname` and `Security.LDAP.Port`, provide the hostname and port of the LDAP server.
3. For `Security.LDAP.BaseDN`, provide the base distinguished name (DN), which specifies root node to start the search for matching entries.  
   * If you are not sure what value to use for this parameter, use the domain root portion of your DN. For example, if your DN is `CN=Joe,CN=Users,DC=example,DC=com`, use `DC=example,DC=com` for your base DN.  
   * To find the DN of a user, you can open a command prompt and run the command `dsquery user -name <username>`, and replace `<username>` with the full name of the user.
4. For `Security.LDAP.SearchFilter`, specify a search filter for objects you want to include in the search. Setting the search filter to `objectClass=user` only includes user objects. Setting the search filter to `objectClass=*` includes all objects.
5. For `Security.LDAP.UsernameAttribute`, specify the attribute of the entities on the LDAP server to use as the database username. If you are using AD, set this parameter to `sAMAccountName`.
6. For `Security.LDAP.AdminDN`, provide the DN of a user who has read access to the specified base DN.
7. For `Security.LDAP.Secure.Protocol`, specify the encryption protocol for LDAP connection. You must specify the same protocol as your LDAP server.  
   * Set the value to `none` if your LDAP server does not use any encryption protocol. This is the default configuration.  
   * For SSL, set the value to `ssl`.  
   * For StartTLS, set the value to `starttls`.
8. If you are using either SSL or StartTLS, you need to provide a truststore, specify its format and provide its password.  
   * For `Security.LDAP.Secure.TruststorePath`, provide the absolute path to the truststore used in SSL.  
   * For `Security.LDAP.Secure.TruststoreFormat`, specify your truststore format. Supported formats include `JKS/PKCS12`.  
   * For `Security.LDAP.Secure.TruststorePassword`, specify the password to your truststore.
9. `Security.LDAP.Secure.TrustAll` should be set to false in any production environment as this overrides SSL/TLS settings and makes TigerGraph trust all LDAP servers. However, you can set this parameter to true in a development for testing purposes.

An example configuration is shown below.

```console
Example of gadmin config entry ldap

$ gadmin config entry ldap

Security.LDAP.Enable [ false ]: Enable LDAP authentication: default false
New: true

Security.LDAP.Hostname [ localhost ]: Configure LDAP server hostname: default localhost
New: ldap.tigergraph.com

Security.LDAP.Port [ 389 ]: Configure LDAP server port: default 389
New: 389

Security.LDAP.BaseDN [  ]: Configure LDAP search base DN, the root node to start the LDAP search for user authentication: must specify
New: dc=tigergraph,dc=com

Security.LDAP.SearchFilter [ (objectClass=*) ]: Configure LDAP search base DN, the root node to start the LDAP search for user authentication.
New: (objectClass=*)

Security.LDAP.UsernameAttribute [ uid ]: Configure the username attribute name in LDAP server: default uid
New: uid

Security.LDAP.AdminDN [  ]: Configure the DN of LDAP user who has read access to the base DN specified above. Empty if everyone has read access to LDAP data: default empty
New: cn=Manager,dc=tigergraph,dc=com

Security.LDAP.AdminPassword [ secret ]: Configure the password of the admin DN specified above. Needed only when admin_dn is specified: default empty
New: secret

Security.LDAP.Secure.Protocol [ none ]: Enable SSL/StartTLS for LDAP connection [none/ssl/starttls]: default none
New: none

Security.LDAP.Secure.TruststorePath [  ]: Configure the truststore absolute path for the certificates used in SSL: default empty
New: /tmp/ca_server.pkcs12

Security.LDAP.Secure.TruststoreFormat [ JKS ]: Configure the truststore format  [JKS/PKCS12]: default JKS
New: PKCS12

Security.LDAP.Secure.TruststorePassword [ changeit ]: Configure the truststore password: default changeit
New: test

Security.LDAP.Secure.TrustAll [ false ]: Configure to trust all LDAP servers (unsafe): default false
New: false
[   Info] Configuration has been changed. Please use 'gadmin config apply' to persist the changes.
```

## Mapping Users From LDAP to TigerGraph

This section explains how to configure a GSQL proxy group to allow LDAP user authentication.

Proxy groups specify privileges for users who log in through LDAP. If the user's LDAP entry matches the proxy rule of an existing proxy group, a proxy user is created to which the user logs in.

For example, if there is an attribute called `role` in the LDAP directory, and `engineering` is one of the `role` attribute values, we can create a proxy group with the proxy rule `role=engineering`. All users with the `role` attribute whose value is `engineering` are matched to the proxy group and have the privileges granted to the proxy group.

### Configure proxy group

Run the `CREATE GROUP` command to create a proxy group with a proxy rule.

`CREATE GROUP` command

```gsql
CREATE GROUP developers PROXY "role=engineering" // Any user in LDAP with role=engineer is proxied to the group 'developers'
```

After creating the proxy group, you can [grant roles](https://www.tigergraph.com/docs/tigergraph-server/4.3/user-access/user-management.md) to the group to give the proxy group privileges.

### Group hierarchy

The attribute which indicates that the current DN is a child of another DN is `memberOf`. Group hierarchy can be defined by stating a membership rule `memberOf=<LDAP group Distinguished Name>`.

An example of a Distinguished Name (DN) is `CN=group1,OU=AADDC Users,DC=tigergraph,DC=com`.

For example, assume `UserA` belongs to `Subgroup1`, and `Subgroup1` is a child of `Group1` on the LDAP server for TigerGraph. If there is a proxy group `ProxyGroup1` whose rule is `memberOf=CN=Group1,OU=AADDC Users,DC=tigergraph,DC=com`, `UserA` can be authorized as a member of `ProxyGroup1`.

GSQL will update the group hierarchy information from the LDAP according to the parameter `Security.LDAP.GroupHierarchyRefreshIntervalMin` whose default value is 240.

The following API is provided to refresh the preloaded group hierarchy information. Only the superuser has privilege to execute this endpoint.

<http://host:14240/gsql/v1/ldap/refresh-group>

### Commands to manage proxy groups

* `SHOW GROUP` displays information about all groups.
* `DROP GROUP <group_name>` deletes the definition of a group.

#### Proxy users

A proxy user is a GSQL user created to correspond to an external LDAP user. When operating within GSQL, the external LDAP user's roles and privileges are determined by the proxy user.

Nothing needs to be configured for a proxy user. As long as the proxy rule matches, the proxy user will be automatically created upon login.

A proxy user is very similar to a normal user. The minor differences are that a proxy user cannot change their password in GSQL and that a proxy user comes with default roles inherited from the proxy group that they belong to.

It is also possible to change the roles of a specific proxy user independently. When the roles and privileges of a proxy group changes, the roles and privileges of all the proxy users belonging to this proxy group change accordingly.

> [!NOTE]
> Proxy groups are not included in a [Database Export](https://www.tigergraph.com/docs/tigergraph-server/4.3/backup-and-restore/database-import-export.md). They need to be recreated following an Import. However, [Backup and Restore](https://www.tigergraph.com/docs/tigergraph-server/4.3/backup-and-restore/index.md) do preserve all proxy groups present at the time of backup.

## Common errors

### Parameter error

"Parameter error" means some LDAP configurations are not set properly. Most often it is because admin\_dn, admin\_password, or the login username and password are not set correctly. Unfortunately, we cannot know exactly what field is wrong because the LDAP server side does not respond back with such detail

### Wrong username or password

If you are logging into a cluster, all nodes must have the certification file in the same place. If one node has the file under `/tmp/certificate/`, then all other nodes must have it in the same place to avoid this error.

### User does not match any proxy rule

This means the LDAP is working. However, TigerGraph cannot find a matching rule for the login user. Please create a proxy group for the user.
