User 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 platform offers three options for credentials:

  • A username-password pair used to log in to GSQL and make HTTP requests.

  • A token - a unique 32-character string with an expiration date, used for REST++ requests. See the full API Authentication documentation for details.

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

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

Like any other GSQL commands, the user must supply credentials to run these commands. In order to create a secret, the user must supply their password.

Passwords

Users can change their own password with the ALTER PASSWORD command. If the user has the WRITE_USER privilege, they can change the password of another user.

ALTER PASSWORD [<user1>]

If a username is not provided, the command changes the password of the current user. To change the password of another user, specify the username of the user whose password you wish to change:

Example: User changing his/her own password
<user1>:GSQL > ALTER PASSWORD
Password: *******
New Password : ************
Re-enter Password : ************
Password has been changed.
Example: Admin changing another user’s password
tigergraph:GSQL > ALTER PASSWORD <user1>
Password: *******
New Password : ************
Re-enter Password : ************
Password has been changed.

Secrets

Secrets are unique strings that serve as a user’s credentials in certain circumstances. A user can have multiple secret strings. Each secret binds to the user who creates it only and inherits all permissions and privileges from the owner.

As of version 4.1.0, secrets are no longer bound to specific graphs and tokens.

Create a secret

Use GSQL Command:

CREATE SECRET [<alias>]

Use the CREATE SECRET command to generate a secret for the current user and graph. It is optional to provide an alias for the secret.

The system will generate a random alias for the secret if the user does not provide an alias for that secret. Randomly generated aliases begin with AUTO_GENERATED_ALIAS_ and include a random 7-character string.

Use GSQL Rest API:

POST /gsql/v1/secrets?userName=<user>&value=<secret content>&alias=<alias>

Use the POST method to call secrets API to create secrets.

  • Case 1: The userName parameter is optional. If not specified, the secret is created for default user who logins.

  • Case 2: The alias parameter is optional. If not specified, a random 7-character string begin with AUTO_GENERATED_ALIAS_ will be generated.

  • Case 3: The value parameter is optional, if not specified, a randomly 32-character string will be generated.

Required privilege

No privilege is required to create secrets for oneself. The superuser role is needed to create secrets for other users.

List secrets

Use GSQL Command:

SHOW SECRET

Use SHOW SECRET to list all secrets of the current user. The secrets will be masked and only the first and last three characters of the secrets will be shown. The alias of the secret and the graph that the secret is associated with will also be listed:

GSQL > SHOW SECRET
    - Secret: s7s****3k5
      - Alias: HH
      - GraphName: Hogwarts
    - Secret: 75j****9i2
      - Alias: LL
      - GraphName: London

Use GSQL Rest API:

GET :14240/gsql/v1/secrets?userName=<user>

or

GET :14240/gsql/v1/secrets/<alias>

Use the GET method to call secrets API to show secrets.

  • Case 1: userName is optional, if userName is not specified, it shows secrets for default user who logins.

The API response will contain the secrets in plain text.

Required privilege

No privilege is required to create secrets for oneself. The superuser role is needed to create secrets for other users.

Drop secret

Use GSQL Command:

DROP SECRET <secret> or <alias>

Use the DROP SECRET command to drop a secret. Since a user can have multiple secrets, the secret to drop must be specified in the command. You can specify a secret either by the secret string itself or by its alias.

Use GSQL Rest API:

DELETE :14240/gsql/v1/secrets?userName=<user>  payload {“secrests” : [<secret1>, <secret2>, …]}

or

DELETE :14240/gsql/v1/secrets?userName=<user>  payload {“secrests” : [<alias1>, <alias2>, …]}

or

DELETE :14240/gsql/v1/secrets/<alias>

Use the DELETE method to call secrets API to drop secrets. The payload can be a list of secrets or alias of secrets or use alias as path variable.

  • Case 1: userName is optional, if userName is not specified, it drops secrets for default user who logins.

Required privilege

No privilege is required to create secrets for oneself. The superuser role is needed to create secrets for other users.