User Privileges and Authentication, LDAP, Single Sign-on
Loading...
Loading...
Loading...
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.
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.
In order to manage the user roles and privileges, the TigerGraph GSQL server employs two concepts—proxy user and proxy group.
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.
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.
To configure a TigerGraph system to use LDAP, there are two main configuration steps:
Configure the LDAP Connection.
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 https://www.ldap.com/basic-ldap-concepts .
To enable and configure LDAP, run three commands.
Configure LDAP:
The gadmin program will then prompt the user for the settings for several LDAP configuration parameters.
2.Apply the configuration:
3.Restart the gsql server:
An example configuration is shown below.
Below is an explanation of each configuration parameter.
Set to "true" to enable LDAP; "false" to disable LDAP.
Hostname of LDAP server.
Port of LDAP server.
Base DN (Distinguished Name), in order for GSQL to perform the LDAP search.
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 available at https://www.ldap.com/ldap-filters . The official specification for LDAP filters is available at https://docs.ldap.com/specs/rfc4515.txt .
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.
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.
When set to "none", TigerGraph uses insecure LDAP connection. This can be changed to a secure connection protocol: "starttls" or "ssl".
When starttls or ssl is used, a truststore path as well as its password needs to be configured.
Currently, the TigerGraph system supports two trustore formats: pkcs12 and jks.
When specified, the GSQL server will blindly trust any LDAP sever.
This section explains how to configure a GSQL proxy group in order to allow LDAP user authentication.
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.
The SHOW GROUP command will display information about a group. The DROP GROUP command deletes the definition of a group.
Only users with the admin and superuser role can create, show, or drop a group.
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.
Admin_dn is the "distinguished name" of an LDAP entry. In LDAP, "distinguished name" is often abbreviated as dn. When configuring this field, a dn entry with read permission on the ldap directory is expected. Configuring a dn with no read permission will result in an error. Not configuring this field will likely result in an error since the LDAP server is typically not publicly readable. Please note that only the dn field will be accepted for this entry. All other entries will result in an authentication error. The corresponding password for the configured dn should also be set correctly in the configured entry "security.ldap.admin_password ".
It depends on what type of protocol your LDAP server uses. SSL/TLS is very common in enterprise use today. When SSL is used, the port is typically 636 instead of default port 389.
You need to configure the truststore when SSL/TLS is used in the LDAP server. The truststore's path, password, and format need to be configured accordingly. We support two formats—JKS and PKCS12. The JKS is Java KeyStore. The corresponding certificates for the LDAP server need to be imported to the JKS for successful authentication. Different truststore formats are typically interchangeable.
This might be the case if SSL/TLS is enabled from the LDAP server side but you don't have a certificate. You can set "security.ldap.secure.trust_all" to true to bypass the SSL/TLS certificate checking.
"Parameter error" means some of the 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.
Congratulations! 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. See documents for creating a proxy group here.
Creation and management of multiple users and roles is available in the Enterprise Edition only.
The TigerGraph platform provides a complete and robust feature set to manage and control user privilege and authentication of GSS operations:
Creation and management of multiple TigerGraph users
Granting to each user a role on a particular graph, each role entailing a set of privileges
Oauth 2.0-style user authentication
Extensible framework, so that additional security- and user- related capabilities can be added in future releases
TigerGraph users exist only with the TigerGraph platform; they are different than operating system users . When the system is first installed, an initial user is automatically created. The default name for this initial user is tigergraph , with password tigergraph . This user has full administrative privilege and can create additional users and can set their privileges (see Roles and Privileges ). For simplicity, we will refer to this initial superuser as the tigergraph user.
If user authentication is enabled (see the section Enabling and Using User Authentication), the TigerGraph system will execute a requested operation only if the requester provides credentials for a user who has the privilege to perform the requested operation.
The TigerGraph system offers two options for credentials.
username-password pair
a token: a unique 32-character string which can be used for REST++ requests, with an expiration date.
When the TigerGraph platform is first installed, user authentication is disabled. The installation process creates a gsql superuser who has the name tigergraph and password tigergraph. As long as user tigergraph's password is tigergraph, gsql authentication remains disabled. This is designed for user convenience in single-user configurations or installations which do not require security, such as demo and training installations. The behavior is compatible with early TigerGraph versions which did not support multiple roles or multiple graphs.
Because there are two ways to access the TigerGraph system, either through the GSQL shell or through REST++ requests, there are two steps needed to set up a secure system with user authentication for both points of entry:
To enable user authentication for GSQL: change the password of the tigergraph user to something other than tigergraph.
To enable Oauth 2 authentication for REST++, use the gadmin program to configure the RESTPP.Authentication parameter. See details below.
More details about each of these two steps are below.
To enable user authentication for GSQL: change the password of the tigergraph user to something other than tigergraph. See ALTER PASSWORD below.
To run a single GSQL command or command file, the user must provide their username and password. The graph also needs to be specified. To specify the username in the command line, use the -u option. The user can also provide their password with the -p option. If the password is not provided on the command line, the system will then prompt the user for their password, so this method is only appropriate for interactive use. If -u not used, then the system will assume that the request is coming from the default tigergraph user. It will then prompt for tigergraph's password (assuming GSQL authentication is enabled). Note that if -u is not used and authentication is disabled, then the system simply responses to all requests, as it did in earlier versions (unprotected administrative mode).
Use the -g parameter to specify which graph on which to operate.
To enter the GSQL interactive shell, simply omit the <command> from the command line. The user does not need to provide credentials again inside the shell. The example below show s two users entering the shell with their passwords. T he user does not need to specify a graph to enter the interactive shell.
The REST++ server implements OAuth 2.0-style authorization as follows: Each user can create one or more secrets (unique pseudorandom strings). Each secret is associated with a particular user and the user's privileges for a particular graph. Anyone who has this secret can invoke a special REST endpoint to generate authorization tokens (other pseudorandom strings). An authorization token can then be used to perform TigerGraph database operations via other REST endpoints. According to OAuth 2.0 protocol, each token will expire after a certain period of time. The TigerGraph default lifetime for a token is 1 month.
Each REST++ request should contain an authorization token in the HTTP header. The REST++ server reads the header. If the token is not valid, REST++ will refuse to run the query and instead will return an authentication error.
The token authentication of REST++ can be turned on by using the following commands:
A user must have a secret before they create a token. Secrets are generated in GSQL (see CREATE SECRET below). The endpoint GET /requesttoken
is used to create a token. The endpoint has two parameters:
secret (required): the user's secret
lifetime (optional): the lifetime for the token, in seconds. The default is one month, approximately 2.6 million seconds.
Once REST++ authentication is enabled, a token should always be included in the HTTP header. If you are using curl to format and submit your REST++ requests, then use the following syntax:
When you use the RUN QUERY command in the GSQL language, this triggers a curl command within the GSQL system. GSQL will automatically use (and generate, if necessary) a token in the curl request for an authorized user.
Authorization for gadmin
Currently, authorization for the gadmin program comes from Linux, and is not related GSQL authorization. In short, only the Linux TigerGraph user can run gadmin.
Details: During installation, the user selects a name and password for the TigerGraph Linux user. The default user and password are tigergraph and tigergraph, respectively. This user is a Linux user; the installer will create a Linux account if needed. Only the TigerGraph Linux user can run gadmin. This Linux user is unrelated to the TigerGraph default user mentioned in the GSQL Authentication section.
The TigerGraph system includes seven predefined roles — superuser, admin, designer, querywriter, queryreader, and observer. Each role has a fixed and logical set of privileges to perform operations. These roles form a hierarchy, with superuser being at the top. Broadly speaking,
An observer (formerly "public") can log on, view the schema and other catalog details for its designated graph, and change their own password.
A queryreader has all observer privileges, and can also run existing loading jobs and queries for its designated graph.
A querywriter has all queryreader privileges, and can also create queries and run data-manipulation commands on its designated graph.
A designer (formerly "architect") has all querywriter privileges, and can modify the schema, create loading jobs for its designated graph.
A globaldesigner has all designer privileges, and can create global schema as well as create objects. Additionally, this role will have the ability to delete graph created by the same user, but will not have the ability to run ‘Clear graph store’ command.
An admin has all designer privileges, and can also create or drop users and grant or revoke roles for its designated graph. That is, an admin can control the existence and privileges of other users on its graph.
A superuser automatically has admin privileges on all graphs, and can also create global vertex and edge types, create multiple graphs, and clear the database.
The detailed permissions for each role are listed in the following table. Except for the superuser and globaldesigner, the scope of privilege is always limited to one's own graph. In some cases, the behavior of the operation depends on one's privilege level. More detailed descriptions of the User Management commands are given later in this document. For details about the Graph Definition, Loading, Querying, and Modification commands, see the GSQL Language Reference documents.
Commands not listed above are by default accessible with at least observer).
The TigerGraph installation process creates one user called tigergraph who has the superuser role. The superuser role has full privilege to perform any action, included creating or removing other users, and assigning roles to the other users. An superuser can create other superusers, who would also have full privilege.
The user tigergraph is permanent. It cannot be dropped by another admin user.
Most of the commands in this section, can be run only by a superuser or an admin user. The exception is SHOW USER. Any user can display their own profile.
If a username contains more than ASCII alphanumeric characters, it is recommended that the name be enclosed in backquote characters, to ensure that the name is treated as a literal string. This applies to the CREATE/DROP USER and GRANT/REVOKE ROLE commands.
Required privilege: superuser, admin Create a new user. GSQL will prompt for the user name and password.
Required privilege: superuser, admin Delete the listed users.
The command takes effect with no warning and cannot be undone.
Required privilege: any Display user's name, role, secret, and token. Non-admin/superuser users see only their own information. Admin/superuser users see information for all users.
Required privilege: superuser, admin Grant a role (or revoke a role) for a user, which add s (or removes) privileges.
The example below grants the queryreader role to two users, revokes it from one of the them (jk), and then grants the querywriter role to both users.
Even if user is granted superuser role, all previous granted roles for the specific user are still displayed.
When user authentication is enabled, the TigerGraph system will execute a requested operation only if the requester provides credentials for a user who has the privilege to perform the requested operation.
The TigerGraph system offers two options for credentials.
user name and password pair.
a token: a unique 32-character string which can be used for REST++ requests. A token expires 1 month from the date of creation by default
The following set of commands are used to create and manage passwords, authentication secrets, and authentication tokens.
Like any other GSQL commands, the user must supply credentials to run these commands. In order to create a secret, the user must supply their password.
Required privilege: any, to change one's own password superuser/admin: to change another user's password
When an admin/superuser user creates a new user, the admin/superuser user sets the user's initial password. Afterward, a user can change their own password.
Moreover, an admin/superuser user can change any user's password. For example, to change hermione's password, the command is ALTER PASSWORD hermione.
The Single Sign-On (SSO) feature in TigerGraph enables you to use your organization's identity provider (IDP) to authenticate users to access TigerGraph GraphStudio and Admin Portal UI.
Currently we have verified the following identity providers which support SAML 2.0 protocol:
For supporting additional IDPs, please inquire sales@tigergraph.com and submit a feature request.
In order to use Single Sign-On , you need to perform four steps :
Configure your identity provider to create a TigerGraph application.
Provide information from your identity provider to enable TigerGraph Single Sign-On .
Create user groups with proxy rules to authorize Single Sign-On users.
Change the password of the tigergraph user to be other than the default, if you haven't done so already.
We assume you already have TigerGraph up and running , and you can access GraphStudio UI through a web browser using the URL:
http://tigergraph-machine-hostname:14240
If you enabled SSL connection, change http to https. If you changed the nginx port of the TigerGraph system, replace 14240 with the port you have set.
Here we provide detailed instructions for identity providers that we have verified. Please consult your IT or security department for how to configure the identity provider for your organization if it is not listed here.
After you finish configuring your identity provider, you will get an Identity Provider Single Sign-On URL , Identity Provider Entity Id , and an X.509 certificate file idp.cert . You need these 3 things to configure TigerGraph next.
After logging into Okta as the admin user, click Admin button at the top-right corner.
Click Add Applications in the right menu.
Click Create New App button in the left toolbar.
In the pop up window, choose SAML 2.0 and click Create .
Input TigerGraph (or whatever application name you want to use) in App Name , and click Next . Upload a logo if you like.
Enter the Assertion Consumer Service URL / Single sign on URL , and SP Entity ID .
Both are URLs in our case. You need to know the hostname of the TigerGraph machine. If you can visit GraphStudio UI through a browser, the URL contains the hostname. It can be either an IP or a domain name.
The Assertion Consumer Service URL , or Single sign on URL, is
http://tigergraph-machine-hostname:14240/sso/saml/acs
The SP entity id URL is:
http://tigergraph-machine-hostname:14240/sso/saml/meta
Scroll to the bottom for Group Attribute Statements. Usually you want to grant roles to users based on their user group. You can give a name to your attribute statement; here we use group . For filter, we want to return all group attribute values of all users, so we use Regex .* as the filter. Click Next after you set up everything.
In the final step, choose whether you want to integrate your app with Okta or not. Then click Finish .
Now your Okta identity provider settings are finished. Click View Setup Instructions button to gather information you will need to setup TigerGraph Single Sign-On.
Here you want to save Identity Provider Single Sign-On URL and Identity Provider Issuer (usually known as Identity Provider Entity Id ). Download the certificate file as okta.cert, rename it as idp.cert , and put it somewhere on the TigerGraph machine. Let's assume you put it under your home folder: /home/tigergraph/idp.cert. If you installed TigerGraph in a cluster, you should put it on the machine where the GSQL server is installed (usually it's the machine whose alias is m1).
Finally, return to previous page, go to the Assignments tab, click the Assign button, and assign people or groups in your organization to access this application.
After logging into Auth0, click Clients in the left navigation bar, and then click CREATE CLIENT button.
In the pop-up window, enter TigerGraph (or whatever application name you want to use) in the Name input box. Choose Single Page Web Application , and then click the CREATE button.
Click Clients again. In the Shown Clients list, click the settings icon of your newly created TigerGraph client.
Scroll down to the bottom of the settings section, and click Show Advanced Settings .
Click the Certificates tab and then click DOWNLOAD CERTIFICATE. In the chooser list, choose CER. Rename the downloaded file as idp.cert , and put it somewhere on the TigerGraph machine. Let's assume you put it under your home folder: /home/tigergraph/idp.cert. If you installed TigerGraph in a cluster, you should put it on the machine where the GSQL server is installed ( usually it's the machine whose alias is m1 ).
Click the Endpoints tab, and copy the text in the SAML Protocol URL text box. This is the Identity Provider Single Sign-On URL that will be used to configure TigerGraph in an upcoming step.
Scroll up to the top of the page, click the Addons tab, and switch on the toggle at the right side of the SAML2 card.
In the pop-up window, enter the Assertion Consumer Service URL in the Application Callback URL input box:
http://tigergraph-machine-hostname:14240/sso/saml/acs
Scroll down to the end of the settings JSON code, click the DEBUG button, and log in as any existing user in your organization in the pop-up login page.
If login in successfully, the SAML response will be shown in decoded XML format. Scroll down to the attributes section. Here you will see some attribute names, which you will use to set proxy rules when creating groups in an upcoming configuration step.
Return to the previous pop-up window and click the Usage tab. Copy the Issuer value. This is the Identity Provider Entity Id that will be used to configure TigerGraph in an upcoming step.
Click the Settings tab, scroll to the bottom of the pop-up window, and click the SAVE button. Close the pop-up window.
According to the SAML standard trust model, a self-signed certificate is considered fine. This is different from configuring a SSL connection, where a CA-authorized certificate is considered mandatory if the system goes to production.
There are multiple ways to create a self-signed certificate. One example is shown below.
First, use the following command to generate a private key in PKCS#1 format and a X.509 certificate file. In the example below, the Common Name value should be your server hostname (IP or domain name).
Second, convert your private key from PKCS#1 format to PKCS#8 format:
Finally, change the certificate and private key file to have permission 600 or less. (The tigergraph user can read or write the file; no other user has any permission.)
From a TigerGraph machine, run the following command: gadmin config entry Security.SSO.SAML
Answering the questions is straightforward; an example is shown below.
Since v2.3, the requirements for the Security.SSO.SAML.SP.Hostname parameter changed. The url must be a full url, starting with protocol (such as http) and ending with port number.
Since v3.1, the requirements for the Security.SSO.SAML.SP.X509Cert and Security.SSO.SAML.SP.PrivateKey parameter changed. The value must be the content of the X.509 certificate and private key respectively.
The reason we change Security.SSO.SAML.ResponseSigned to false is because some identity providers (e.g., Auth0) don't support signed assertion and response at the same time. If your identity provider supports signing both, we strongly suggest you leave it as true.
After making the configuration settings, apply the config changes, and restart gsql.
In order to authorize Single Sign-On users, you need create user groups in GSQL with proxy rules and grant roles on graphs for the user groups.
In TigerGraph Single Sign-On, we support two types of proxy rules. The first type is nameid equations; the second type is attribute equations. Attribute equations are more commonly used because usually user group information is transferred as attributes to your identity provider SAML assertions. In the Okta identity provider configuration example, it is transferred by the attribute statement named group . By granting roles to a user group, all users matching the proxy rule will be granted all the privileges of that role. In some cases if you want to grant one specific Single Sign-On user some privilege, you can use a nameid equation to do so.
For example, if you want to create a user group SuperUserGroup that contains the user with nameid admin@your.company.com only, and grant superuser role to that user, you can do so with the following command:
Suppose you want to create a user group HrDepartment which corresponds to the identity provider Single Sign-On users having the group attribute value "hr-department", and want to grant the queryreader role to that group on the graph HrGraph:
Don't forget to enable User Authorization in TigerGraph by changing the password of the default superuser tigergraph to other than its default value. If you do not change the password, then every time you visit the GraphStudio UI, you will automatically log in as the superuser tigergraph.
Now you have finished all configurations for Single Sign-On. Let's test it.
Visit the GraphStudio UI in your browser. You should see a Login with SSO button appear on top of the login panel:
If after redirecting back to GraphStudio, you return to the login page with the error message shown below, that means the Single Sign-On user doesn't have access to any graph. Please double check your user group proxy rules, and roles you have granted to the groups.
If your Single Sign-On fails with error message show below, that means either some configuration is inconsistent between TigerGraph and your identity provider, or something unexpected happened.
You can check your GSQL log to investigate. First, find your GSQL log file with the following:
Then, grep the SAML authentication-related logs:
TigerGraph's role-based access control system naturally extends to a multiple graph system: A user is granted a role on a particular graph. The superuser role (new in TigerGraph 1.2) is defined for administration of the entire unified supergraph.
A superuser can create and manage users globally, including creating admin users for local graphs. An admin can create and manage users with their local graph.
The ON GRAPH clause is required unless the role being granted/revoked is superuser.
A user can have more than one role. For example, jk can be a queryreader on the Hogwarts graph and a querywriter on the London graph.
Clicking the button will navigate to your identity provider's login portal. If you have already logged in there, you will be redirected back to GraphStudio immediately. After about 10 seconds, the verification should finish, and you are authorized to use GraphStudio. If you haven't login at your identity provider yet, you will need to log in there. After logging in successfully, you will see your Single Sign-On username when you click the User icon at the upper right of the GraphStudio UI.
Focus on the latest errors. Usually the text is self-descriptive. Follow the error message and try to fix TigerGraph or your identity provider's configuration. If you encounter any errors that are not clear, please contact .
Command Type
Operations
super- user
admin
global-designer
designer
query- writer
query- reader
observer
Status
Ls
x
x
x
x
x
x
x
User Management
Create/Drop User
x
x
-
-
-
-
-
Show User
x
x
x
x
x
x
x
Alter (Change) Password
x
x
x
x
x
x
x
Grant/Revoke Role
x
x
-
-
-
-
-
Create/Drop/Show Secret
x
x
x
x
x
x
-
Schema Design
Create/Drop Vertex/Edge/Graph
x
-
x
-
-
-
-
Clear Graph Store
x
-
-
-
-
-
-
Drop All
x
-
-
-
-
-
-
Use Graph
x
x
x
x
x
x
x
Use Global
x
x
x
x
x
x
x
Create/Run Global Schema_Change Job
x
-
x
-
-
-
-
Create/Run Schema_Change Job
x
x
x
x
-
-
-
Loading and Querying
Create/Drop Loading Job
x
x
x
x
-
-
-
Create/Interpret/ Install/Drop Query
x
x
x
x
x
-
-
Typedef
x
x
x
x
x
-
-
Offline to Online Job Translation
x
x
x
x
x
-
-
Run Query
x
x
x
x
x
x
-
Run Loading Job
x
x
x
x
x
x
-
Data Modification
Upsert/Delete/ Select Commands
x
x
x
x
x
-
-