User Privileges and Authentication

1
Mo
EM
Last updated last month

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

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 .

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.

  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.

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

Starting with version 1.2 which can support multiple graphs, the user also needs t o specify a graph in order to run any commands pertaining to a particular graph. For command line mode, the graph can be specified with the -g option:

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: jiokmfqqfu2f95qs6ug85o89rpkneib3
- 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 --configure RESTPP.Authentication
gadmin config-apply
gadmin restart restpp nginx vis -y

Creating Tokens 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:

  • 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

v1.2 adds the superuser role and shifts some privileges, to provide a more logical foundation for multiple graphs. Roles are now granted on a per-graph basis. Please pay careful attention to the table of 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.

Command Type

Operations

superuser

admin

designer

querywriter

queryreader

observer

Status

Ls

x

x

x

x

x

x

User Management

Create/Drop User

x

x

Show User

x

x

x

x

x

x

Alter (Change) Password

x

x

x

x

x

x

Grant/Revoke Role

x

x

Create/Drop/Show Secret,

x

x

x

x

x

Create/Drop/Show/Refresh Token (Deprecated)

x

x

x

x

x

Schema Design

Create/Drop Vertex/Edge/Graph

x

Clear Graph Store

x

Drop All

x

Use Graph

x

x

x

x

x

x

Create/Run Global Schema_Change Job

x

x

x

x

x

x

Create/Run Global Schema_Change Job

x

Create/Run Schema_Change Job

x

x

x

Loading and Querying

Create/Drop Loading Job

x

x

x

Create/Install/Drop Query

x

x

x

x

Typedef

x

x

x

x

Offline to Online Job Translation

x

x

x

x

Run Query

x

x

x

x

x

Run Loading Job

x

x

x

x

x

Data Modification

Upsert/Delete/Select Commands

x

x

x

x

= new operation = Prior to TigerGraph 1.2, admin and designer could perform this operation.

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.

An admin user is similar to a superuser whose scope is limited to a designated graph. An admin can create and manage other users for that graph alone.

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>

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

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

Required privilege: superuser, admin Delete the listed users.

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: 3ridhimp5icllq04qgt0r1fgddv1hf9e
- Token: j13nv837thrr19u0ahjr8m0is2ded6kk expire at: 2017-09-13 15:18:05
- Roles: designer, observer
- Name: jk
- Roles: observer
- Name: hermione
- Roles: observer

ALTER PASSWORD

ALTER PASSWORD [<user1>]

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.

GRANT/REVOKE ROLE

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

Required privilege: superuser, admin Grant a role (or revoke a role) for a user, which adds (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.

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 > SHOW USER
Users:
* - Name: tigergraph
- Roles: superuser
- Name: hermione
- Roles:
- 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.

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

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

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:

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

SHOW GROUP

SHOW GROUP <groupname>

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

DROP GROUP

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.

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.

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.

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.

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: 4sjmn1q13vp2klqb7v3t151vac9db2am
- 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: 4sjmn1q13vp2klqb7v3t151vac9db2am
- 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: 75j8kf75g545mgc24mefsjm1iic7m9i2
- Alias: LL
- GraphName: London

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

Example of CREATE / SHOW / REFRESH / DROP TOKEN commands
$ gsql -u jk -g London
Password for jk : *******
GSQL > CREATE SECRET
The secret: mv88grasoidc7fenk1ffl6hnll8f2apf has been created for user "jk".
GSQL > SHOW SECRET
- Secret: 33bt4o86c33nauhhipaenh9pluun86po
- GraphName: London
- Secret: mv88grasoidc7fenk1ffl6hnll8f2apf
- GraphName: London
GSQL > CREATE TOKEN
Secret : 33bt4o86c33nauhhipaenh9pluun86po
The access token: kn1hlp1a6b9lugq2mkqohsd8i0ht2tt3 is created and it will expire at 2018-05-03 18:39:19.
GSQL > SHOW TOKEN
- Secret: 33bt4o86c33nauhhipaenh9pluun86po
- Token: kn1hlp1a6b9lugq2mkqohsd8i0ht2tt3 expire at: 2018-05-03 18:39:19
- GraphName: London
- Secret: mv88grasoidc7fenk1ffl6hnll8f2apf
- GraphName: London
GSQL > CREATE TOKEN
Secret : mv88grasoidc7fenk1ffl6hnll8f2apf
The access token: ieec6odigmja01rkt3qmq0nar4iufsvq is created and it will expire at 2018-05-03 18:39:49.
GSQL > SHOW TOKEN
- Secret: 33bt4o86c33nauhhipaenh9pluun86po
- Token: kn1hlp1a6b9lugq2mkqohsd8i0ht2tt3 expire at: 2018-05-03 18:39:19
- GraphName: London
- Secret: mv88grasoidc7fenk1ffl6hnll8f2apf
- Token: ieec6odigmja01rkt3qmq0nar4iufsvq expire at: 2018-05-03 18:39:49
- GraphName: London
GSQL > DROP TOKEN kn1hlp1a6b9lugq2mkqohsd8i0ht2tt3
Token kn1hlp1a6b9lugq2mkqohsd8i0ht2tt3 has been removed.
GSQL > SHOW TOKEN
- Secret: 33bt4o86c33nauhhipaenh9pluun86po
- Alias: LL
- GraphName: London
- Secret: mv88grasoidc7fenk1ffl6hnll8f2apf
- Token: ieec6odigmja01rkt3qmq0nar4iufsvq expire at: 2018-05-03 18:39:49
- GraphName: London