×

☰ Table of Contents

TigerGraph Docs : Managing User Privileges and Authentication

Version 1.0
Document updated:

Copyright © 2015-2017 TigerGraph, Inc. All Rights Reserved .
For technical support on this topic, contact support@tigergraph.com with a subject line beginning with "Authentication"



Authentication Overview

The TigerGraph platform introduces several new features to manage and control user privilege and authentication of GSQL language operations:

  • Creation and management of multiple GSQL users
  • Assignment of users to standard roles, each role entailing a set of privileges
  • Oauth 2.0-style user authorization and authentication
  • Extensible framework, so that additional security- and user- related capabilities can be added in future releases

Users and Credentials

A new feature is the existence of TigerGraph users .  These user accounts exist only with the TigerGraph platform; they are different than Linux users . When the system is first installed, one user called tigergraph is automatically created, with password tigergraph . This user has full administrative privilege and can create additional users and can set their privileges (see Roles and Privileges ).

If user authentication is enabled (see 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 three options for credentials.

  1. username-password pair
  2. a secret: a unique 32-character string which can be used in place of username-password
  3. a token:  a unique 32-character string which can be used for REST++ requests.  A token expires 3 months from the date of creation.

Enabling and Using User Authentication

When the TigerGraph platform is first installed, user authentication is disabled. The installation process creates a gsql admin user with 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 do not require security, such as demo and training installations. The behavior is compatible with earlier TigerGraph versions which did not support user management and privileges.

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 visual User Interface 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 either their password or their secret. To use the secret, use the -s option:

Running one GSQL command or command line, with secret string credentials
$ gsql -s <secret> <commmand>

To use the username & password, use the -u option.  The system will then prompt the user for their password, so this method is only appropriate for interactive use.  If neither -u nor -s is 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 or -s is not used, and authentication is disabled, then the system simply responses to all requests, as it did in early versions (unprotected administrative mode).

Running one GSQL command or command line, with username and password
$ gsql [-u username] <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 shows (1) the tigergraph user entering the shell with their password, and (2) another user (frank) entering the shell with his secret.

Examples: entering with interactive shell
$ gsql Password: ******** Welcome to GSQL Shell version: 0.8.1 Type 'help' for help. tigergraph:GSQL > SHOW USER Users: - Name: tigergraph - Roles: admin, public tigergraph:GSQL > EXIT $ gsql -s jiokmfqqfu2f95qs6ug85o89rpkneib3 Welcome to GSQL Shell version: 0.8.1 Type 'help' for help. frank:GSQL > SHOW USER - Name: frank - Secret: jiokmfqqfu2f95qs6ug85o89rpkneib3 - Roles: architect, public frank:GSQL > EXIT


REST++ Authentication

The REST++ server implements OAuth 2.0-style authorization as follows: Each user can create one or more secrets (a unique pseudorandom string), and can use this secret to generate authorization tokens (other pseudorandom strings). We set our string lengths to be 32 characters. According to OAuth 2.0 protocol, each token will expire after a certain period of time. In our case, we set it to 3 months.

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:

Enabling REST++ OAuth Authentication
gadmin --configure RESTPP.Authentication gadmin config-apply gadmin restart restpp -y


Once authentication is turned on, 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 -XGET -H "Authorization: Bearer <token>" 'http://localhost:9000/query/test1?mem=123'


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 five predefined roles--- admin , architect , querywriter , queryreader , and public. Each role has a fixed and logical set of privileges to perform operations. These five roles form a hierarchy, with admin being at the top.  Broadly speaking,

  • A public user can log on and change their own password.
  • A queryreader has all public privileges, and can also run existing loading jobs and queries.
  • A querywriter has all queryreader privileges, and can also create queries and run data-manipulation commands on an existing graph.
  • An architect has all querywriter privileges, and can also create a graph schema, create loading jobs, and clear an existing graph.
  • An admin has all architect privileges, and can also create or drop users and grant or revoke roles.  That is, only an admin can control the existence and privileges of other users.

The detailed permissions for each role are listed in the following table.

Command Types Operations admin architect querywriter queryreader public
User Management Commands create/drop/show user x



change any password x



change own password x x x x x
grant/revoke user with roles x



create/drop/show/refresh secret/token x x x x
DDL create/drop vertex/edge/graph x x



create/run schema change job x x


create/install/drop query x x x

create/drop loading jobs x x


run query x x x x

run loading job

x x x x
clear graph store x x


drop all x x


offline to online job translation x x x

Typedef x x x

ls x x x x x
DML upsert/delete/select commands x x x

Commands not listed above are by default accessible by anyone (public).

Creating and Managing Users

The TigerGraph installation process creates one user called tigergraph who has the admin role.  The admin role has full privilege to perform any action, included creating or removing other users, and assigning roles to the other users.  An admin can create other admin users, 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 only be run by 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 TO <user1>,...<userN> REVOKE ROLE admin FROM <user1>,...<userN>

CREATE USER

Required privilege: 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: admin
Delete the listed users.

The command takes effect with no warning and cannot be undone. A future revision may add a confirmation step before deleting the user(s).


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 users see only th eir o wn information.  Admin users see information for all users.

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

ALTER PASSWORD

ALTER PASSWORD [<user1>]

When an admin user creates a new user, the admin 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 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> TO <user1>,...<userN> REVOKE ROLE <username> FROM <user1>,...<userN>

Required privilege: admin
Grant a role (or revoke a role) from a user, w hich 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 jk.

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

A user can have more than one role. This may be important for future revisions with more complex role definitions.


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 three options for credentials.

  1. user name and password pair
  2. a secret: a unique 32-character string which can be used in place of user & password
  3. 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 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 be used in place of user name & password. 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 command: log into the GSQL shell with a password, create two secrets, drop one secret, log out, and then log back in using the secret.

Example of CREATE / SHOW / DROP SECRET commands
$ gsql -u jk Password : ******* Welcome to GSQL Shell version: 0.8.1 Type 'help' for help. jk:GSQL > SHOW USER - Name: jk - Roles: public, querywriter jk:GSQL > CREATE SECRET The secret: smrdumohrfpoc8qndih1ro3um8fp6frb has been created for user "jk". jk:GSQL > SHOW USER - Name: jk - Secret: smrdumohrfpoc8qndih1ro3um8fp6frb - Roles: public, querywriter jk:GSQL > CREATE SECRET The secret: a82cannl2sqvlhgag3m7av29erbfppm has been created for user "jk". jk:GSQL > SHOW SECRET - Secret: smrdumohrfpoc8qndih1ro3um8fp6frb - Secret: a82cannl2sqvlhgag3m7av29erbfppm jk:GSQL > DROP SECRET smrdumohrfpoc8qndih1ro3um8fp6frb Secret smrdumohrfpoc8qndih1ro3um8fp6frb has been removed. jk:GSQL > SHOW SECRET - Secret: a82cannl2sqvlhgag3m7av29erbfppm jk:GSQL > EXIT [tigergraph@localhost DEMO]$ gsql -s a82cannl2sqvlhgag3m7av29erbfppm Welcome to GSQL Shell version: 0.8.1 Type 'help' for help. jk:GSQL > SHOW USER - Name: jk - Secret: a82cannl2sqvlhgag3m7av29erbfppm - Roles: public, querywriter

CREATE / SHOW / DROP / REFRESH TOKEN

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 expires 3 months after it is created.  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 with a secret, create a token for one secret, create another token for another secret, drop one token, and refresh the other token.

Example of CREATE / SHOW / REFRESH / DROP TOKEN commands
$ gsql -s a82cannl2sqvlhgag3m7av29erbfppm Welcome to GSQL Shell version: 0.8.1 Type 'help' for help. jk:GSQL > CREATE SECRET The secret: d91cag2rs3drrf2m2711s30mngngqqvu has been created for user "jk". jk:GSQL > SHOW SECRET - Secret: a82cannl2sqvlhgag3m7av29erbfppm - Secret: d91cag2rs3drrf2m2711s30mngngqqvu jk:GSQL > CREATE TOKEN Secret : a82cannl2sqvlhgag3m7av29erbfppm The access token: pb9n4l8au7ramhs6td0tncrk58q32paq is created and it will expire at 2017-09-14 02:45:59. jk:GSQL > SHOW TOKEN - Secret: a82cannl2sqvlhgag3m7av29erbfppm - Token: pb9n4l8au7ramhs6td0tncrk58q32paq expire at: 2017-09-14 02:45:59 - Secret: d91cag2rs3drrf2m2711s30mngngqqvu jk:GSQL > CREATE TOKEN Secret : d91cag2rs3drrf2m2711s30mngngqqvu The access token: m0rpujel5nfdrrqvoumu41bdvtmse6at is created and it will expire at 2017-09-14 02:46:15. jk:GSQL > SHOW TOKEN - Secret: a82cannl2sqvlhgag3m7av29erbfppm - Token: pb9n4l8au7ramhs6td0tncrk58q32paq expire at: 2017-09-14 02:45:59 - Secret: d91cag2rs3drrf2m2711s30mngngqqvu - Token: m0rpujel5nfdrrqvoumu41bdvtmse6at expire at: 2017-09-14 02:46:15 jk:GSQL > DROP TOKEN m0rpujel5nfdrrqvoumu41bdvtmse6at Token m0rpujel5nfdrrqvoumu41bdvtmse6at has been removed. jk:GSQL > SHOW TOKEN - Secret: a82cannl2sqvlhgag3m7av29erbfppm - Token: pb9n4l8au7ramhs6td0tncrk58q32paq expire at: 2017-09-14 02:45:59 - Secret: d91cag2rs3drrf2m2711s30mngngqqvu jk:GSQL > REFRESH TOKEN pb9n4l8au7ramhs6td0tncrk58q32paq Token pb9n4l8au7ramhs6td0tncrk58q32paq is successfully refreshed. jk:GSQL > SHOW TOKEN - Secret: a82cannl2sqvlhgag3m7av29erbfppm - Token: pb9n4l8au7ramhs6td0tncrk58q32paq expire at: 2017-09-14 02:47:34 - Secret: d91cag2rs3drrf2m2711s30mngngqqvu