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; |
|
Security.LDAP.AdminPassword |
Configure the password of the admin DN specified above.
Needed only when |
|
Security.LDAP.BaseDN |
Configure LDAP search base DN, the root node to start the LDAP search for user authentication. |
|
Security.LDAP.Enable |
Enable LDAP authentication: default 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 |
|
Security.LDAP.Port |
Configure LDAP server port: default 389 |
|
Security.LDAP.SearchFilter |
Configure LDAP search filter. Only objects that satisfy the conditions in the filter |
|
Security.LDAP.Secure.Protocol |
Enable SSL/StartTLS for LDAP connection [none/ssl/starttls]: default none |
|
Security.LDAP.Secure.TrustAll |
Configure to trust all LDAP servers (unsafe): default false |
|
Security.LDAP.Secure.TruststoreFormat |
Configure the truststore format [JKS/PKCS12]: default JKS |
|
Security.LDAP.Secure.TruststorePassword |
Configure the truststore password: default |
|
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. |
|
Security.LDAP.UsernameAttribute |
Configure the username attribute name in LDAP server: default uid |
|
Configure TigerGraph to use LDAP
To enable and configure LDAP, run the following command:
$ gadmin config entry ldap
This prompts the user to enter the values for the LDAP configuration parameters.
-
Set
Security.LDAP.Enable
to true. This configures TigerGraph to use LDAP for authentication. -
For
Security.LDAP.Hostname
andSecurity.LDAP.Port
, provide the hostname and port of the LDAP server. -
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
, useDC=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.
-
-
For
Security.LDAP.SearchFilter
, specify a search filter for objects you want to include in the search. Setting the search filter toobjectClass=user
only includes user objects. Setting the search filter toobjectClass=*
includes all objects. -
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 tosAMAccountName
. -
For
Security.LDAP.AdminDN
, provide the DN of a user who has read access to the specified base DN. -
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
.
-
-
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 includeJKS/PKCS12
. -
For
Security.LDAP.Secure.TruststorePassword
, specify the password to your truststore.
-
-
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
commandCREATE 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.
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