User Privileges and Authentication

Version 2.2 - 2.3 Copyright © 2019 TigerGraph. All Rights Reserved.

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 nam e 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. 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).

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

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

A user must have a secret before they create a token. Secrets are generated in GSQL (see CREATE SECRET below). The special endpoint GET /requesttoken is used to create a token. The endpoint has two parameters:

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:

Roles and Privileges

The TigerGraph system includes six 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.

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

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.

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.

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.

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.

ALTER 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 revise any user's password. For example, to change hermione's password, the command is ALTER PASSWORD hermione .

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.

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.

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 3 months from the date of creation.

The following set of commands are used to create and manage passwords, authentication secrets, and authentication tokens.

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)

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 3 months. However, the clock can be reset, giving 3 months 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.