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.

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:
$ 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.

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
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 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/gsqlserver/gsql/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.

Proxy groups cannot be exported.However, performing a backup and restore will 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.