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'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.

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.

  1. username-password pair

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

  1. To enable user authentication for GSQL: change the password of the tigergraph user to something other than tigergraph.

  2. 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.

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.

Running one GSQL command or command line, with username, graph name, and password
$ gsql [-u username] [-p pasword] [-g gname] <commmand>
Password: ********

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.

Examples: entering with interactive shell
$ gsql
Password for tigergraph: ********
Welcome to GSQL Shell version: 1.2
GSQL > SHOW USER
Users:
- Name: tigergraph
- Roles: admin, observer
GSQL > EXIT
$ gsql -u frank
Password for frank: ******
Welcome to GSQL Shell version: 1.2
GSQL > SHOW USER
- Name: frank
- Secret: *************************
- Roles: designer, observer
GSQL > EXIT

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:

Enabling REST++ OAuth Authentication
gadmin config set RESTPP.Factory.EnableAuth true
gadmin config apply
gadmin restart restpp nginx gui -y

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.

Example: REST++ Request to Generate a Token
curl -X GET 'localhost:9000/requesttoken?secret=jiokmfqqfu2f95qs6ug85o89rpkneib3&lifetime=1000000'

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:

curl GSQL request, with authorization token in header
curl -X GET -H "Authorization: Bearer <token>" 'http://localhost:9000/query/graphname/queryname?param1=val1&param2=val2'

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

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

-

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

-

-

Commands not listed above are by default accessible with at least observer).

Creating and Managing Users

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

User Management Commands
CREATE USER
DROP USER <user1>,...<userN>
SHOW USER
ALTER PASSWORD [<user1>]
GRANT ROLE admin [ON GRAPH <gname>] TO <user1>,...<userN>
REVOKE ROLE admin [ON GRAPH <gname>] FROM <user1>,...<userN>

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.

tigergraph:GSQL > CREATE USER
User Name : `name@tigergraph.com`

CREATE USER

Required privilege: superuser, admin Create a new user. GSQL will prompt for the user name and password.

Example: Create user
tigergraph:GSQL > CREATE USER
User Name : frank
New Password : ************
Re-enter Password : ************
The user "frank" is created.

DROP USER

Required privilege: superuser, admin Delete the listed users.

DROP USER <user1>,...<userN>

The command takes effect with no warning and cannot be undone.

Example: Drop two users
tigergraph:GSQL > DROP USER hermione, jk
Password: *********
The user "hermione" is dropped.
The user "jk" is dropped.

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.

Example: admin user showing profile information for all users
tigergraph:GSQL > SHOW USER
Users:
- Name: tigergraph
- Roles: admin, observer
- Name: frank
- Secret: ************************
- Token: j13nv837thrr19u0ahjr8m0is2ded6kk expire at: 2017-09-13 15:18:05
- Roles: designer, observer
- Name: jk
- Roles: observer
- Name: hermione
- Roles: observer

GRANT/REVOKE ROLE

GRANT ROLE <rolename> [ON GRAPH <gname>] TO <user1>,...<userN>
REVOKE ROLE <rolename> [ON GRAPH <gname>] FROM <user1>,...<userN>

Required privilege: superuser, admin Grant a role (or revoke a role) for a user, which add s (or removes) privileges.

The ON GRAPH clause is required unless the role being granted/revoked is superuser.

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.

Example: Granting and Revoking Roles
GSQL > GRANT ROLE queryreader ON GRAPH Hogwarts TO jk,hermione
Role "queryreader" is successfully granted to user(s): jk, hermione
GSQL > REVOKE ROLE queryreader ON GRAPH Hogwarts FROM hermione
Role "queryreader" is successfully revoked from user(s): hermione
GSQL > GRANT ROLE querywriter ON GRAPH London TO hermione,jk
Role "querywriter" is successfully granted to user(s): hermione, jk
GSQL > GRANT ROLE superuser to hermione
Role "superuser" is successfully granted to user(s): hermione
GSQL > SHOW USER
Users:
* - Name: tigergraph
- Roles: superuser
- Name: hermione
- Roles: superuser
- GraphName: London
- Roles: querywriter
- Name: jk
- Roles:
- GraphName: Hogwarts
- Roles: queryreader
- GraphName: London
- Roles: querywriter

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.

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.

  1. user name and password pair.

  2. 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.

GSQL Commands for Managing Credentials
ALTER PASSWORD [user1]
CREATE SECRET [alias1]
SHOW SECRET
DROP SECRET <secret1>
CREATE TOKEN
SHOW TOKEN
DROP TOKEN <token1>
REFRESH TOKEN <token1>

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

ALTER PASSWORD [<user1>]

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.

ALTER PASSWORD [<user1>]
Example: Admin user changing his/her own password
herminone:GSQL > ALTER PASSWORD
Password: *******
New Password : ************
Re-enter Password : ************
Password has been changed.

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.

Example: Admin user changing his/her own password
herminone:GSQL > ALTER PASSWORD
Password: *******
New Password : ************
Re-enter Password : ************
Password has been changed.

Moreover, an admin/superuser user can revise any user's password. For example, to change hermione's password, the command is ALTER PASSWORD hermione.

Example: Admin user changing another user's password
tigergraph:GSQL > ALTER PASSWORD hermione
Password: *******
New Password : ************
Re-enter Password : ************
Password has been changed.

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.

A secret represents more than just the user's identity but also the user's role for a particular graph. If user's role is revoked, the secret becomes invalid.

The secret is masked when SHOW SECRET is used. The user must remember their secret when first running CREATE SECRET.

Example of CREATE / SHOW / DROP SECRET commands
$ gsql -u jk -g Hogwarts
Password for jk : *******
Welcome to GSQL Shell version: 1.2
GSQL > CREATE SECRET HH
The secret: 4sjmn1q13vp2klqb7v3t151vac9db2am has been created for user "tigergraph".
GSQL > SHOW SECRET
- Secret: *******************************
- Alias: HH
- GraphName: Hogwarts
GSQL > USE GRAPH London
Using graph 'London'
GSQL > CREATE SECRET LL
The secret: 75j8kf75g545mgc24mefsjm1iic7m9i2 has been created for user "tigergraph".
GSQL > SHOW SECRET
- Secret: *******************************
- Alias: HH
- GraphName: Hogwarts
- Secret: 75j8kf75g545mgc24mefsjm1iic7m9i2
- Alias: LL
- GraphName: London
GSQL > USE GRAPH Hogwarts
Using graph 'Hogwarts'
GSQL > DROP SECRET 4sjmn1q13vp2klqb7v3t151vac9db2am
Secret 4sjmn1q13vp2klqb7v3t151vac9db2am has been removed.
GSQL > SHOW SECRET
- Secret: *******************************
- Alias: LL
- GraphName: London

Creating Tokens

Once a user has a Secret, the Secret can be used to create an OAuth token. To create a token, use the REST endpoint GET /requesttoken, described in the earlier section REST++ Authentication. Note: The GSQL language command CREATE TOKEN was removed in TigerGraph 3.0 in favor of the RESTful method.

Creating and Managing Proxy Groups

CREATE GROUP

Proxy groups are used for LDAP Authentication and Single Sign On. The CREATE / SHOW / DROP GROUP commands require the superuser or admin privilege.

Required privilege: superuser, admin Create a proxy group whose membership is defined as those users who have an attribute satisfying the rule <attributename>=<value>.

CREATE GROUP <groupname> PROXY "<attributename>=<value>"

After a group has been defined, roles can be granted to (or revoked from) the group, as in the example below:

CREATE GROUP and GRANT ROLE example
CREATE GROUP developers PROXY "role=engineering"
GRANT ROLE querywriter ON GRAPH computerNet TO developers

SHOW GROUP

Required privilege: superuser, admin. Display information about a group.

SHOW GROUP <groupname>

DROP GROUP

Required privilege: superuser, admin. Display information about a group.

DROP GROUP <groupname>

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.

DROP GROUP <groupname>

Required privilege: superuser, admin. Delete the named group definition. The users in the group will lose this proxy association but are otherwise unaffected.