User Management

This page explains the procedures for various user management tasks under TigerGraph’s role-based access control(RBAC) model.

Create a user

You can run the CREATE USER command to create a user.

Username Rules for v3.9.3 and above

v3.9.3 expanded the variety of characters users can access while creating a username from previous versions.

A username is treated as a STRING in GSQL, regardless of the syntax structure, format, or characters used.

Usernames may contain any Unicode characters except the following:

May not contain these characters: \r, \n, \0, \b, \t, \a, \v.
May not contain any SPACE.

In the GSQL client, backquotes ( ` ) must be used as a delimiter to enclose usernames which is not a valid email and does not follow the pattern [a-zA-Z_][a-zA-Z0-9]*. Delimiters are not stored internally.

Username Rules for v3.9.2 and below

For v3.9.2 and below please follow these guidelines when creating a username.

Usernames must match a regex pattern of [a-zA-Z_][a-zA-Z0-9]*, or be an email. You may also use non-ascii characters, such as Chinese and Kanji characters.

Additionally, usernames may not contain the following characters:

\, (, ), [, ], :, <, >, ;, ,, @, \r, \n, \f, \t, \\, \0, \b.
A username may not start with a dot ( . ) or have multiple dots ( … or a.b..c… ) in a sequence.

Backquotes ( ` ) must be used as a delimiter to enclose usernames which do not follow the pattern [a-zA-Z_][a-zA-Z0-9]*. Delimiters are not stored internally.

Syntax

CREATE USER

Required privilege

WRITE_USER

Procedure

From the GSQL shell, run the CREATE USER command:
```
GSQL > CREATE USER
```

Enter the user information in the prompts that follow:

Example 1: Create user

User Name : user1
New Password : ************
Re-enter Password : ************
The user "user1" is created.

Example 2: Create user with email

User Name : a@b.com
New Password : ************
Re-enter Password : ************
The user "a@b.com" is created.

Example 3: Create user with special characters (Only v3.9.3)

User Name : `:"/.,@#$%^*()_+=-`
New Password : ************
Re-enter Password : ************
The user ":"/.,@#$%^*()_+=-" is created.

Non-Interactive Mode

Run the command like this to run create user in non-interactive mode.

Example:

GSQL > create user -u user1 -p pass1

for special case use ““ username““ to include the username

View roles assignments and login attempts

The SHOW USER command displays the role assignments, as well as the login attempts, of the current user. If the current user hsa the READ_USER privilege

Syntax

SHOW USER

Required privilege

READ_USER for displaying roles of other users

Procedure

From the GSQL shell, run the SHOW USER command:

GSQL > SHOW USER
- Name: testUser
    - Global Roles: superuser
    - LastSuccessLogin: Thu Sep 22 12:43:07 UTC 2022
    - NextValidLogin: Thu Sep 22 12:43:07 UTC 2022 (1)
    - FailedAttempts: 0
    - ShowAlterPasswordWarning: false

1	The next time the user is allowed to attempt login. For more information, see Configuring Login Protection

If the user running the command has the READ_USER privilege, information on all users is displayed. Otherwise, only the current user’s information is displayed.

View privileges of a user

Users with the READ_USER privilege in a scope can view the RBAC privileges of the users in that scope.

Syntax

SHOW PRIVILEGE ON USER <username> (, <username>)*

Required privilege

READ_USER

Procedure

From the GSQL shell, run the SHOW PRIVILEGE ON USER command :
```
GSQL > SHOW PRIVILEGE ON USER tigergraph
```

The above command will show the privileges of user tigergraph:

User: "tigergraph"
  - Global Privileges:
    READ_SCHEMA
    WRITE_SCHEMA
    READ_LOADINGJOB
    EXECUTE_LOADINGJOB
    WRITE_LOADINGJOB
    CREATE_QUERY
    READ_DATA
    WRITE_DATA
    WRITE_DATASOURCE
    READ_ROLE
    WRITE_ROLE
    READ_USER
    WRITE_USER
    READ_PROXYGROUP
    WRITE_PROXYGROUP
    READ_FILE
    WRITE_FILE
    DROP_GRAPH
    EXPORT_GRAPH
    CLEAR_GRAPHSTORE
    DROP_ALL
    ACCESS_TAG

Grant a role to a user/proxy group

Syntax

GRANT ROLE <role_name1> (, role_name2)* [ON GRAPH <graph_name>]
  TO <username1>|<proxy_group_name1> (, <username2> | <proxy_group_name>2)*

Required privilege

WRITE_ROLE

Procedure

Start the GSQL shell and make sure you are using the correct graph
```
$ gsql
GSQL > USE GRAPH example_graph
```
From the GSQL shell, run the GRANT ROLE command. You can grant multiple roles to multiple users:
```
GSQL > GRANT ROLE role1 , role2 ON GRAPH example_graph TO user1, user2
```

The above command will grant roles role1 and role2 on graph example_graph to users user1 and user2.

Revoke a role from a user

Syntax

REVOKE ROLE <roleName1> (, <roleName2)* [ON GRAPH <graphName>]
        FROM <userName1> (, <userName2>)*

Required privilege

WRITE_ROLE

Procedure

Start the GSQL shell and make sure you are using the correct graph
```
$ gsql
GSQL > USE GRAPH example_graph
```
From the GSQL shell, run the REVOKE_ROLE command. You can revoke multiple roles from multiple users at the same time:
```
GSQL > REVOKE ROLE role1, role2 ON GRAPH example_graph
        FROM user1, user2
```

The above command will revoke roles role1 and role2 on graph example_graph from users user1 and user2.

Grant privileges to a user

Only users with the WRITE_USER privilege at the global level can grant RBAC privileges to other users.

Syntax

GRANT <privilegeName1> (, <privilegeName2>)* ON <privilegeObjects>
        [IN <privilegeScopes>]? TO <user_name1> (, <user_name2>)*

Required privilege

WRITE_USER

Example

To grant privileges to a user, run the GRANT PRIVILEGE command from the GSQL shell:
```
GSQL > GRANT WRITE ON ALL ROLES
        IN GRAPH example_graph TO user1 , user2
```

This command will allow user1 and user2 to modify roles on the graph example_graph. Specifically, they can create, modify, or delete roles for that graph. To see a full list of privileges and the command they allow users to run, see rbac-row-policy/rbac-row-policy.adoc#_object_based_privileges

Grant type-level privilege to a user

You can grant certain privileges (READ_DATA, CREATE_DATA, DELETE_DATA, UPDATE_DATA) on a type level to users. The privilege only applies to the specified types.

Syntax

GRANT <privilege_name1> (, <privilege_name2>)* ON VERTEX/EDGE <type_name> IN GRAPH <graph_name> TO <user_name> (, <user_name2>)*

Required privilege

WRITE_USER and the privilege being granted

Example

The following command grants the READ_DATA and CREATE_DATA privilege on vertex type Person to user1 and user2.

GRANT READ, CREATE ON VERTEX Person IN GRAPH G1 TO user1, user2

This allows user1 and user2 to read all attribute values of type Person vertices in graph G1. However, to insert new vertices, the user must also have UPDATE_DATA on all attributes of vertex type Person.

Grant attribute-level privilege to a user

You can grant certain privileges (READ_DATA, CREATE_DATA, UPDATE_DATA) on an attribute level to a user. The privilege only applies to the specified attributes of the specified type.

Syntax

GRANT <privilege_name1> (, <privilege_name2>)* ON VERTEX/EDGE <type_name> ATTRIBUTE <attribute_name> (, <attribute_name2>)* IN GRAPH <graph_name> TO <user_name> (, <user_name2>)*

from and to are edge attributes that represent the source vertex and target vertex of an edge. When you grant access to these attributes, from and to are case-sensitive. You must use lower-case to indicate these two attributes.

Required privilege

WRITE_USER and the privilege being granted

Example

The following command grants the READ_DATA privilege on the id and age attribute of the vertex type Person to example_user.

GRANT READ ON VERTEX person ATTRIBUTE id, age IN GRAPH G1 TO example_user

This allows the user example_user to read the id and age attribute values of Person vertices in graph G1. However, if the type Person has other attributes, such as an SSN attribute with their social security number, users who don’t have the READ_DATA privilege on that attribute are not able to access its attribute value.

The following command grants the READ_DATA privilege on the to attribute of the edge type Knows to example_user:

GRANT READ ON EDGE Knows ATTRIBUTE to IN GRAPH ldbc_snb TO example_user (1)

1	`to` must be lower-case.

Revoke privileges from a user

Users with the WRITE_USER privileges on global can revoke RBAC privileges from the users.

Syntax

REVOKE <privilegeName1> (, <privilegeName2>)* ON <privilegeObjects>
        [IN <privilegeScopes>]? FROM <user_name1> (, <user_name2>)*

Required privilege

WRITE_USER

Example

To revoke privileges from a user, run the REVOKE PRIVILEGE command from the GSQL shell:
```
GSQL > REVOKE WRITE ON ALL ROLES
        IN GRAPH example_graph TO user1
```

This will revoke the WRITE_ROLE privilege from the user user1 on graph example_graph.

Revoke type-level privileges

You can revoke certain privileges from the type level with the REVOKE PRIVILEGE command.

Revoking a privilege at the type does not affect privileges granted at higher levels (e.g., global or graph level). For instance, if a user has READ_DATA` on a vertex type globally, revoking this privilege at the type level will not prevent the user from accessing the vertex type.

Syntax

REVOKE <privilege_name1> (, <privilege_name2>)* ON VERTEX/EDGE <type_name> IN GRAPH <graph_name> FROM <user_name> (, <user_name2>)*

Required privilege

WRITE_USER

Example

The following command revokes the UPDATE_DATA privilege on type Friendship from user1, and user2:

REVOKE UPDATE ON EDGE Friendship IN GRAPH Social FROM user1, user2

Revoke attribute-level privileges

You can revoke certain privileges from the attribute level with the REVOKE PRIVILEGE command.

Revoking a privilege at the type does not affect privileges granted at higher levels (e.g., global, graph level or type level). For instance, if a user has READ_DATA` on a vertex type globally, revoking this privilege at the attribute level will not prevent the user from accessing the vertex attribute type.

Syntax

REVOKE <privilege_name1> (, <privilege_name2>)* ON VERTEX/EDGE <type_name>  ATTRIBUTE <attribute_name> (, <attribute_name>)* IN GRAPH <graph_name> FROM <user_name> (, <user_name2>)*

Required privilege

WRITE_ROLE and the privilege being granted

Example

The following command revokes CREATE_DATA and UPDATE_DATA on the startdata attribute from user1 and user2.

If the user doesn’t have these privileges, they are not able to create new edges of type Friendship.

REVOKE CREATE, UPDATE ON EDGE Friendship ATTRIBUTE startdata IN GRAPH Social FROM user1, user2

Change a user’s password

Users can change their own passwords used for login without needing any privilege. Users with the WRITE_USER privilege can change the passwords of other users.

Syntax

ALTER PASSWORD <username>

Required privilege

WRITE_USER for changing the password of a user other than the current user

Procedure

From the GSQL shell, run the following command. Replace username with the user whose password you want to change
```
GSQL > ALTER PASSWORD username
```
Enter the new password in the prompt that follows.

Non-Interactive Mode

Run the command like this to run alter password in non-Interactive Mode.

Example:

GSQL > alter password -u user1 -p pass2

Drop a user

Syntax

DROP USER <user1> (,<user2>)*

Required privilege

WRITE_USER

Procedure

From the GSQL shell, run the DROP USER command. You can drop multiple users in the same command.
```
GSQL > DROP USER user1, a@b.com, `:"/.,@#$%^*()_+=-`
```
GSQL will confirm that the users you entered have been dropped