LDAP Authentication v2.1

LDAP Authentication


The




Lightweight Directory Access Protocol




(


LDAP


) is an industry-standard

protocol



for accessing and maintaining



directory information services across a

network.

Typically, LDAP servers are used to provide centralized user authentication service. The Tigergraph system supports LDAP authentication by allowing a TigerGraph user to log in using an LDAP username and credentials. During the authentication process, the GSQL server connects to the LDAP server and requests the LDAP server to authenticate the user.

Supported Features

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

SASL authentication is not yet supported. Some LDAP server are configured to require a client certificate upon connection. Client certificate is not yet supported in GSQL LDAP authentication.

Mapping Users From LDAP to GSQL

In order to manage the user roles and privileges, the TigerGraph GSQL server employs two concepts—proxy user and proxy group.

Proxy User

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

Proxy Group

A proxy group is a GSQL user group that is used to manage a group of proxy users who share similar properties/attributes in LDAP.

An existing LDAP user can log in to GSQL only when the user matches at least one of the existing proxy groups’ criteria. Once the criteria are satisfied, a proxy user will be created for the LDAP user. The roles and privileges of the proxy user are

at least

as permissive as the proxy group(s) he belongs 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.

Configure GSQL LDAP Authentication

To configure a TigerGraph system to use LDAP, there are two main configuration steps:

  1. Configure the LDAP Connection.
  2. Configure GSQL Proxy Groups and Users.

In order to choose and specify your LDAP configuration settings, you must understand some basic LDAP concepts.  One reference for LDAP concepts is

Basic LDAP Concepts



.

Step 1 – Configure the LDAP Connection

To enable and configure LDAP, run three commands.

  1. Configure LDAP:

    gadmin –configure ldap

    The gadmin program will then prompt the user for the settings for several LDAP configuration parameters.

  2. Apply the configration:

    gadmin config-apply

  3. Restart the gsql server:

    gadmin restart gsql -y

An example configuration is shown below.


Example of gadmin –configure ldap
$ gadmin –configure ldap
# Enable LDAP authentication: default false
security.ldap.enable [False]: true
True

# Configure LDAP server hostname: default localhost
security.ldap.host [ldap.tigergraph.com]: ldap.tigergraph.com
ldap.tigergraph.com

# Configure LDAP server port: default 389
security.ldap.port [389]: 389
389

# Configure LDAP search base DN, the root node to start the LDAP search for user authentication: must specify
security.ldap.base_dn [dc=tigergraph,dc=com]: dc=tigergraph,dc=com
dc=tigergraph,dc=com

# Configure LDAP search base DN, the root node to start the LDAP search for user authentication.
security.ldap.search_filter [(objectClass=*)]:
(objectClass=*)

# Configure the username attribute name in LDAP server: default uid
security.ldap.username_attribute [uid]: uid
uid

# 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
security.ldap.admin_dn [cn=Manager,dc=tigergraph,dc=com]: cn=Manager,dc=tigergraph,dc=com
cn=Manager,dc=tigergraph,dc=com

# Configure the password of the admin DN specified above. Needed only when admin_dn is specified: default empty
security.ldap.admin_password [secret]: secret
secret

# Enable SSL/StartTLS for LDAP connection [none/ssl/starttls]: default none
security.ldap.secure.protocol [starttls]: none
none

# Configure the truststore path for the certificates used in SSL: default empty
security.ldap.secure.truststore_path [/tmp/ca_server.pkcs12]:
/tmp/ca_server.pkcs12

# Configure the truststore format [JKS/PKCS12]: default JKS
security.ldap.secure.truststore_format [pkcs12]:
pkcs12

# Configure the truststore password: default changeit
security.ldap.secure.truststore_password [test]:
test

# Configure to trust all LDAP servers (unsafe): default false
security.ldap.secure.trust_all [False]: false

Below is an explanation of each configuration parameter.

security.ldap.enable

Set to “true” to enable LDAP; “false” to disable LDAP.

security.ldap.host

Hostname of LDAP server.

security.ldap.port

Port of LDAP server.

security.ldap.base_dn

Base DN (Distinguished Name), in order for GSQL to perform the LDAP search.

security.ldap.search_filter

A search filter is optional. When configured, the search is only performed for the LDAP entries that satisfy the filter. The filter must strictly follow LDAP filter format, i.e., the condition must be wrapped by parentheses, etc. A description of the different types of filters is avaiable at

LDAP Filters



. The official specification for LDAP filters is available at

https://docs.ldap.com/specs/rfc4515.txt

.

security.ldap.username_attribute

This specifies the LDAP attribute to search when the GSQL server looks up the usernames in the LDAP server upon login. For example, in the configuration shown above, when a user logs in with the “-u john” option, the GSQL server will search the “uid” attribute in LDAP to find “john” and check the credentials only after “john” is found.

security.ldap.admin_password & security.ldap.admin_dn

These options are needed when the LDAP server is not publicly readable. In this case, the admin DN and corresponding password need to be specified in order for the GSQL server to connect to the LDAP server.

security.ldap.secure.protocol

When set to “none”, TigerGraph uses insecure LDAP connection. This can be changed to a secure connection protocol: “starttls” or “ssl”.

security.ldap.secure.truststore_path & security.ldap.secure.truststore_password

When starttls or ssl is used, a truststore path as well as its password needs to be configured.

security.ldap.secure.truststore_format

Currently, the TigerGraph system supports two trustore formats: pkcs12 and jks.

security.ldap.secure.trust_all

When specified, the GSQL server will blindly trust any LDAP sever.

Step 2 – Configure GSQL Proxy Groups and Users

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

Configure Proxy Group

A GSQL proxy group is created by the CREATE GROUP command with a given proxy rule. For example, assume 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”. Different roles can then be assigned to the proxy group. An example is shown below. When a user logins, the GSQL server searches for the user’s entry in the LDAP directory. If the user’s LDAP entry matches the proxy rule of an existing proxy group, a proxy user is created to which the user will login in.


CREATE GROUP command
# create a proxy group
CREATE GROUP developers PROXY “role=engineering” // Any user in LDAP with role=engineer is proxied to the group ‘developers’

# grant role to proxy group
GRANT ROLE querywriter ON GRAPH computerNet TO developers

The SHOW GROUP command will display information about a group. The DROP GROUP command deletes the definition of a group.


SHOW GROUP and DROP GROUP commands
# show the current groups
SHOW GROUP

# delete a proxy group
DROP GROUP developers


Only users with the admin and superuser role can create, show, or drop a group.

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.