User Privileges and Authentication
Creation and management of multiple users and roles is available in the Enterprise Edition only.
Overview
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
Users and Credentials
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.
Enabling and Using User Authentication
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.
User authorization for the browser-based GraphStudio UI is in development.
GSQL Authentication
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.
REST++ Authentication
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.
Enabling REST++ Authentication
The token authentication of REST++ can be turned on by using the following commands:
Creating Tokens
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.
Using Tokens
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.
Roles and Privileges
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 have no 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, 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.
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 User | x | x | - | - | - | - | - |
User Management | Drop User [Note 1] | 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 | - | |
Create/Drop/Show/ Refresh Token (Deprecated) | 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 | - | - |
Note 1: Prior to v3.0.5, Admin users could DROP USER.
Commands not listed above are by default accessible with at least observer).
Creating and Managing Users
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.
Quoted Usernames
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.
CREATE USER
Required privilege: superuser, admin Create a new user. GSQL will prompt for the user name and password.
DROP USER
Required privilege: superuser, admin Delete the listed users.
The command takes effect with no warning and cannot be undone.
SHOW USER
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.
GRANT/REVOKE ROLE
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.
Managing Credentials
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.
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 or create a token, the user must supply their password.
ALTER PASSWORD
Required privilege: any
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 revise any user's password. For example, to change hermione's password, the command is ALTER PASSWORD hermione .
CREATE / SHOW / DROP SECRET
These commands create and manage a user's secrets, unique strings which can serve as a user's credentials in certain circumstances. A user can have multiple secret strings. Each time that CREATE SECRET is executed, a new secret string is created. Therefore, when running DROP SECRET, the user must specify which secret is to be dropped. The following example shows a series of commands: log into the GSQL shell with a password, create two secrets, one for each of two graphs, then drop one of the secrets.
CREATE / SHOW / DROP / REFRESH TOKEN (deprecated)
The TOKEN commands in GSQL are deprecated. The recommended procedure to create tokens is to use the REST++ endpoint GET /requesttoken.
These commands create and manage a user's tokens, unique strings which can be used as credentials when making a REST++ request. In fact, tokens are the only credentials that can be used for REST++ requests. In order to create a token, a user must first have a secret. A user can have multiple tokens, but each token is associated with its secret. Each token is given a lifetime and expiration date when it is created; the default lifetime is 1 month. However, the clock can be reset, giving 1 month from the current time, by using the REFRESH TOKEN command.
The following example shows a series of commands: log into the GSQL shell, create a second secret, create a token for one secret, create another token for another secret, and drop one token.
Creating and Managing Proxy Groups
Proxy groups are used for LDAP Authentication. The CREATE / SHOW / DROP GROUP commands require the superuser or admin privilege.
CREATE GROUP
Required privilege: superuser, admin Create a proxy group whose membership is defined as those users who have an attribute satisfying the rule <attributename>=<value>.
After a group has been defined, roles can be granted to (or revoked from) the group, as in the example below:
SHOW GROUP
Required privilege: superuser, admin. Display information about a group.
DROP GROUP
Required privilege: superuser, admin.
Delete the named group definition. The users in the group will lose this proxy association but are otherwise unaffected.
Last updated
