Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Vertex-level Access Control (VLAC) allows database administrators to control data access on the vertex level by attaching tags to individual vertices on a graph (the base graph) and creating tag-based graphs. Tag-based graphs share the underlying data with the base graph but have their own sets of roles and privileges, which allows administrators to exercise fine-grained data access control without the vertex type boundary.
Figure 1 below illustrates two tag-based graphs built upon a base graph. The base graph contains vertices of person
type, and vertices of post
type. Two tags (A and B) are used to tag them. For example, vertex 1 and vertex 9 both have tag A. Vertex 3 and vertex 11 both have tag A and B. A tag-based graph named tagA
will only present to its users those base graph vertices that have tag A (the bottom-left graph). The other tag-based graph named tagB
will only present to its users those base graph vertices that have tag B (the bottom-right graph).
For users operating on a tag-based graph, tags are an invisible aspect that silently filters how they load and query data. A tag-based graph defines its view, and all data outside its view is invisible to it.
Sufficient privileges on the base graph or on the global scope are required to perform the steps described on this page.
ACCESS_TAG
Any operation involving tags
WRITE_SCHEMA
Create/run schema change jobs
Create tag-based graphs
READ_DATA, WRITE_DATA
Run queries that modify the graph
WRITE_LOADINGJOB
, EXECUTE_LOADINGJOB
Create/run loading jobs
Below is the basic workflow on using the VLAC to control data access for a database administrator:
Grant built-in roles to users on a tag-based graph
Define roles and grant them to users on a tag-based graph
There are three main options for tagging vertices.
Explicitly add/modify tags on existing data: A user with the privilege ACCESS_TAG
and WRITE_DATA
privileges on the base graph can create and run a DML query that sets tags on selected individual vertices.
Explicitly set tags when loading data into to a base graph: A user with EXECUTE_LOADINGJOB
, WRITE_LOADINGJOB
and ACCESS_TAG
privileges on the base graph can create and run a loading job that explicitly sets tags on the newly loaded base graph vertices.
Implicitly set tags when loading into a tag-based graph: A user with tag-based graph loading or insert privilege (e.g., a designer
or querywriter
) can create an ordinary loading or upsert job which inserts new vertices. The new vertices will be automatically tagged according to the tag-based graph's schema definition.
Users with data read and write privileges (e.g., the querywriter
and queryreader
built-in roles) can query and update the tag-based graph as they would do any other graph. The data filtering for querying or data tagging for insertion is applied automatically.
The rest of this tutorial will first describe tag management: creating and dropping tags, making vertex type taggable, and using tags to define tag-based graphs. Next, the three ways to tag vertices are described and illustrated. We summarize the privilege scheme of tag-based graphs in terms of GSQL's predefined roles. Finally, we give some use cases that can be solved by VLAC.
Features not yet supported:
DDL tag operations can only be done in GSQL. They are not yet supported in GraphStudio. This includes create/drop tags, create/alter vertices that are taggable, define a tag-based graph.
The privilege control for DDL operations (only admin and designer users should be able to explicitly manage tags) is not fully functional.
In summary, all necessary operations to set up VLAC graphs and users are supported in GSQL. Due to a known bug, standard users (with querywriter
and queryreader
roles) can run some DDL operations which they should not be able to.
We’ll use the graph socialNet as an example in the following sections.
A tag is a special attribute of a vertex, which appears as a string for input and output purposes. If a vertex type is declared to be taggable, then each vertex of that type can have one or more tags. The maximum number of different tags in a global graph is 64. All operations involving tags requires the user to have the ACCESS_TAG
privilege.
A tag name has to be defined via ADD TAG
before it can be used. Each base graph defines its own set of tags. However, there is a global maximum number of different tags, currently set at 64.
ADD TAG
can only be used inside a SCHEMA_CHANGE JOB
. An example is below:
Run ls
to see a list of defined tags:
The DROP TAG
command not only removes the given tag(s) from the catalog of available tags, but also deletes them from each vertex to which it is attached. You can drop multiple tags in one statement.
Like ADD TAG
, DROP TAG
also needs to be inside a SCHEMA_CHANGE JOB
:
You cannot drop a tag if it is used in the definition of a tag-based graph. You must drop the graph first.
When DROP TAG
is executed, the specified tags will be made invalid, and then the foreground process will complete. A background process will continue to run to remove the tags from all data. In the meantime, each dropped tag still takes up one of the 64 slots for tags. The slot(s) will become available once the background process finishes.
A tag-based graph is a filtered view of a base graph, where a base graph is a simple collection of vertex types and edge types, without any tag specifiers. A tag-based graph must include at least one taggable vertex type from the base graph.
A vertex type has to be taggable to accept tags. TAGGABLE
is a boolean property of a vertex type that can be set with CREATE VERTEX
initially or with ALTER VERTEX
in a schema change job:
The property TAGGABLE is false by default. To change this default, use the WITH
clause below when creating a vertex type:
To change a vertex type from taggable to untaggable, use WITH TAGGABLE="false".
You cannot make a vertex type untaggable if it is used in the definition of a tag-based graph.
Edge types are never tagged. See the next section to see how we determine which edges to include in the tag-based graph.
After a tag set and taggable vertex types have been created, we can use the tags to define a tag-based graph. For each vertex type we want to include, we may also specify a tag expression which must be satisfied for an individual vertex to be included.
Examples
Here is an example of creating a tag-based graph from the base graph socialNet
.
The interpretation is "Starting from the socialNet
graph, create a tag-based graph called vipNet
which includes person
vertices which are tagged 'vip
'. Also include all post
vertices and all friend
, posted
and liked
edges."
Edges do not have tag expressions. An edge will be included when both of its vertex endpoints are included (and its edge type is included in the tag graph schema).
To describe a combination of tags, use the &
operator to combine the tags:
The graph mixedNet
will only include the person
vertices having both the public
and vip
tags, and posts having all three of the public
, tech
and dummy
tags.
Same tag for all vertex types
If the desired tag-based graph is "anything in the base graph that has these tags", there is a convenient shortcut:
is the same as
General Syntax
The formal syntax for both the general form and the simplified form of creating a tag-based graph is shown below:
There are three main options for tagging vertices in the base graph.
Add tags on existing data with DML queries. For existing data, a user with base graph tagging privilege (e.g., an admin
or designer
) can create and run a DML query that sets tags on selected individual vertices.
Explicitly set tags when loading/inserting to a base graph. For new data, a user with base graph loading and tagging privilege (e.g., an admin
or designer
) can create and run a loading job that explicitly sets tags on the newly loaded vertices.
Implicitly set tags when loading/inserting into a tag-based graph. For new data, a user with tag-based graph loading or insert privilege (e.g., a designer
or querywriter
) can create an ordinary Loading or Upsert Job which inserts new vertices. The new vertices will be automatically tagged according to the tag-based graph's schema definition.
In GSQL, special vertex methods are provided to access and modify the tags of a vertex in a DML query (full list available on page Vertex Functions). These functions are only available for vertex aliases (defined in the FROM
clause of a SELECT
statement); they cannot be applied to vertex variables in other contexts.
There are 8 DML-level tag-access functions in the vertex-query block or edge-query block. Use the v.addTags()
function to tag a vertex.
READ_DATA
, WRITE_DATA
, WRITE_QUERY
, ACCESS_TAG
To add or modify tags, you should work at the base graph level.
Examples
addTags()
is shown below. This query will add tags to person vertices to achieve the same effect as a base graph loading job example in the previous section.
Use removeTags()
and removeAllTags()
to remove tags from vertices:
TAGS
clauseTags can be added to vertices at their loading time using a base graph loading job.
The LOAD
statement has an optional clause for explicit tagging of loaded data. The tagging clause has two keywords, TAGS
and BY:
TAGS(<tag_list>)
specifies the tags to be set.
BY
specifies how to merge tags if the targeted vertex exists in the graph
BY OR:
Add the given tags to the existing set of tags.
BY OVERWRITE:
Replace the existing tags with the given ones.
WRITE_LOADINGJOB
, EXECUTE_LOADINGJOB
, ACCESS_TAG
Example 1
Suppose we want to put the tags vip
and public
on the person
vertex data coming from a certain file. We have three files: persons1
, persons2
, persons3
.
Create and run three loading jobs:
Note that the TAGS
clause can specify a tag with a string literal ("vip"
) so every vertex gets the same tag, or with a token reference by position ($2
) or by name ($"label"
) from the source file, so each vertex gets a data-dependent tag. If the tag clause refers to a non-existent tag, the loading job will still run, but the data will not be loaded at runtime. The loading job log will report these non-loaded vertices.
Example 2
We have three post files: posts1
, posts2
, and posts3
.
We create and run the following loading jobs:
Loading data to a tag-based graph automatically tags each vertex with the tags specified in the graph's definition. For example, when loading to vipNet
, the person
vertices will automatically be tagged with vip
.
If you load data into a tag-based graph, these vertices are actually being added to the parent base graph. If two tag-based graphs have overlapping views (e.g. if the graph vipNet2
also includes person:vip
), then when one adds a vertex via the tag-based graph, the other tag-based graph may also see it.
Portability and Reusability: The same loading job works for socialNet
or any graph derived from socialNet
which contains person
. The difference is in the effect: running it with vipNet
will apply the vip
tag. Running it with a different tag-based graph would apply different tags. Users of a given tag-based graph automatically insert and query data for that tag-based graph.
Tagging Shared Data: The default behavior of GSQL loading is upsert: if you attempt to insert a vertex or edge which already exists (e.g., uses an existing ID), you will instead update the existing element with the new attribute values. If the attribute is a list or set, the new values will be added to the existing list/set. This applies to tags. If you attempt to load an existing vertex, the new tag(s) will be added to any existing tags. Loading a vertex that already exists extends the tag set with the guidance of the tag-graph schema.
The graph vipNet
only includes vertices with the tag vip
. We can verify this by running a simple query to return all person vertices in vipNet
:
The output of the query would be:
Users with global WRITE_SCHEMA
and ACCESS_TAG
privileges can create, modify and drop tags, as well as create tag-based graphs for all graphs.
Users with roles on the base graph that have the ACCESS_TAG
privilege (e.g.admin
and designer
roles) can create/drop tags, and tag vertices. Users that have both the ACCESS_TAG
privilege and WRITE_SCHEMA
privilege (e.g. admin
and designer
roles) can create/drop tag-based graphs of the base graph.
Users with roles that don't have the ACCESS_TAG
privilege on the base graph are able to access the base graph as their roles allow, but they do not have access to the tags on the base graph. They cannot see whether any vertex type on the graph is taggable or if there are tag-based graphs of the base graph.
Users with roles on the tag-based graphs of the base graph cannot access the base graph if they don't have a role with privileges for the base graph.
When a new tag-based graph is created, users with admin
or designer
roles will inherit their base graph role on the tag-based graph. Additionally, the creator of the tag-based graph becomes an admin of the tag-based graph.
Users who are given roles on a tag-based graph have the privileges on the tag-based graph that correspond to their roles, except they are not allowed to edit the tag-based graph's graph schema.
Problem
A user with admin
role on a graph wants to grant a group of users access to a selective set of vertices.
Solution
The base graph admin can do the following security setup.
Define a tag. In a schema change job, declare a tag T
for this application.
Mark vertex types as taggable. Identify the vertex types you want to give selective access for, and mark those vertex types as taggable in a schema change job.
Define a tag-based graph. Define a tag-based graph B
with the taggable vertex types, with T
as their tag expression.
Tag vertices. Write a DML query on the base graph and use the tag functions in the query to tag the vertices you want to include in the tag-based graph, and run the query.
Grant users permission to the tag-based graph. On the tag-based graph B, grant roles that have the appropriate privileges for graph B
to the target users.
Problem
You have a source file containing class annotations (tags) on vertex data. You want to grant users access to the vertices that have the annotation T1
. In the future, you also want the ability to give other users access to vertices based on the vertex class.
Solution
The base graph admin
user can do the following setup.
Define tags. Declare tags T1, T2, … Tn
for all the classes in your source file in a schema change job.
Mark vertex types as taggable. Identify the vertex types of the vertices in your source file that have class annotations, and mark those vertex types as taggable in a schema change job.
Define a tag-based graph. Define a tag-based graph B
with T1
as the tag expression.
Explicitly tag vertices during data loading. Write a base graph loading job, and in the loading job, use a TAGS() BY
clause to explicitly add tags to the ingested vertices.
Grant roles on the tag-based graph. On the tag-based graph B
, grant roles that have the appropriate privileges for the graph B
to target users.
Problem
An admin
user on a graph wants to give a group of users read/write access for a specific class of vertices. The users would be able to insert new vertices into the graph and query the data, and all the data they insert into the graph are tagged as the same class.
Solution
The base graph admin can do the following setup.
Define a tag. Declare a tag T
for this application in a schema change job.
Mark vertex types as taggable. Identify the vertex types to give selective access to, and mark the relevant vertex types as taggable in a schema change job.
Define a tag-based graph. Define a tag-based graph B
with T
as the tag expression.
Grant roles on the tag-based graph. On the tag-based graph, grant roles with the appropriate privileges to target users.
These group users operate (including delete/update/insert) on graph B
as if it is a normal graph. They can ingest new data, as well as operate on those vertices from the base graph that have the tag T
.
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.
Username and password pair.
API token: A unique 32-character string that can be used for REST++ requests. A token expires 1 month from the date of creation by default. Users can use their secrets or their username and password pair to generate a token.
The following set of commands are used to create and manage passwords and secrets.
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.
Users can change their own passwords with the ALTER PASSWORD
command. If the user has the WRITE_USER
privilege, they can change the password of another user.
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:
Secrets are unique strings that serve as a user's credentials in certain circumstances. A user can have multiple secret strings. Each secret is associated with one user and their role for one graph. If the role is revoked, the secret also becomes invalid.
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.
Beginning with TigerGraph 3.1.4, 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 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:
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.
Enabling user authentication on TigerGraph enforces access control, requiring users to identify themselves and ensuring that users can only perform actions allowed by their roles.
When the TigerGraph platform is first installed, user authentication is disabled. The installation process creates a gsql superuser who has the name tigergraph
and password tigergraph
. As long as this user's password is tigergraph
, GSQL authentication remains disabled.
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 secure your system with authentication enabled for both points of entry:
To enable user authentication for GSQL, change the password of the default user whose username tigergraph
to something other than tigergraph
.
Log in to the GSQL shell as the default user tigergraph
. Since authentication is not enabled, entering gsql
into the Linux terminal under the TigerGraph Linux user will log you in as user tigergraph
automatically.
Run the following command to change the password, and enter the new password as prompted:
User authentication has been enabled. Exit the GSQL shell and try to reenter, and confirm that GSQL will now prompt for your password.
To log in as a different user, use the -u
option when you enter the GSQL shell. You can also supply the password in the same command with the -p
option.
To enable RESTPP authentication, set the RESTPP.Factory.EnableAuth
parameter to true
.
As the TigerGraph Linux user, run the following command:
Run the following commands to save the configuration and restart system services:
User Privileges and Authentication, LDAP, Single Sign-on
TigerGraph's user access management features are based on the Role-based Access Control model, on top of which there are additional features that give users finer-grain data access control. Some key features include:
A TigerGraph user is a database-level security principal on the TigerGraph platform. When user authentication is enabled, only clients who can provide credentials that identify themselves as a user can interact with the TigerGraph database.
The TigerGraph platform offers two options for credentials:
A username-password pair
A token - a unique 32-character string used for REST++ requests, with an expiration date.
TigerGraph uses Role-based Access Control (RBAC) to manage authorization. On every graph, privileges to perform actions are assigned to roles, and roles are granted to users. Outside of the permissions granted by their roles, a user has no access to the system.
Privilege is permission to perform an action in a given scope. When a privilege is assigned to a role, it allows users with the role to perform the specified action in the specified scope. For example, the privilege READ_SCHEMA
on graph social
gives a user read permission to the schema of the graph social
. This allows the user to run commands such as ls
and SHOW VERTEX
on the graph.
To view a complete list of privileges available in TigerGraph and the commands they enable a user to run, see List of Privileges.
The scope of a privilege can be global or local. Global privileges apply to all graphs and global objects. Local privileges only apply on the graph they belong to.
For example, a role with WRITE_QUERY
on graph social
can only create queries on graph social
, but not on other graphs. In contrast, a role with WRITE_QUERY
on the global scope can create queries on all graphs.
Local roles can only be granted local privileges, while global roles can be granted both local and global privileges.
Global-only privileges
Some privileges can only be global by nature. For example, since users are global objects, any user-related privileges are global only. To see which privileges are global-only, see List of Privileges.
A role is a collection of privileges you can assign to users to grant them permission to perform actions on specific resources.
Roles can be global or local. Local roles can only be granted local privileges, while global roles can be granted both local and global privileges.
For example, if a user creates a role manager
on the graph social
:
This role can only be granted privileges on the graph social
. It cannot be granted global privileges.
GSQL offers 5 built-in local roles and 2 built-in global roles. The built-in roles cannot be dropped. Below is a table of the built-in roles and their corresponding set of privileges.
Users can define roles with their own list of privileges they want to grant to the role. To learn how to create/drop user-defined roles and manage privileges for the roles, see Role Management.
This page explains the procedures for various role management tasks under TigerGraph's authorization model.
Syntax
Required privilege
WRITE_ROLE
Procedure
To create a local role, run the CREATE ROLE
command like below. If you choose not to specify a graph in the command, the current scope will be used as the scope of the role:
This will create two roles named role1
and role2
on graph example_graph
. By default, these two roles do not have any privilege:
WRITE_ROLE
on the global scope
To create a global role, run the CREATE ROLE
command like below. Replace role1
with the name of the role you are creating.
This will create a role named role1
on the global scope. By default, this role has no privileges:
Syntax
Required privilege
READ_ROLE
Procedure
To view the privileges of a role, run the SHOW PRIVILEGE ON ROLE
command, and replace role1, role2
with the names of the roles whose privileges you want to view:
This will show the privileges of the role role1
and role2:
Syntax
Required privilege
READ_ROLE
Procedure
To list all existing roles, first ensure that you are in the correct scope. Run USE <graph_name>
or USE GLOBAL
to switch to your desired scope.
Run the SHOW ROLE
command:
This will show all the roles in your current scope:
Syntax
Require privilege
WRITE_ROLE
Procedure
To grant privileges to a role, run the GRANT PRIVILEGE
command from the GSQL shell:
Syntax
Required privilege
WRITE_ROLE
Procedure
To revoke privileges from a role, run the REVOKE PRIVILEGE
command from the GSQL shell:
This will revoke the WRITE_QUERY
privilege from the role role1
on graph example_graph.
Syntax
Required privilege
WRITE_ROLE
Procedure
To drop a role, run the DROP ROLE
command from the GSQL shell:
This will drop the roles role1
and role2
. This will also revoke the roles from users who have been granted these roles.
The Lightweight Directory Access Protocol ( LDAP ) is an industry-standard protocol for accessing and maintaining directory information services across a network. Typically, LDAP servers provide centralized user authentication services. The Tigergraph system supports LDAP authentication by allowing a TigerGraph user to log in using an LDAP username and credentials. During the authentication process, the GSQL server connects to the LDAP server and requests the LDAP server to authenticate the user.
GSQL LDAP authentication supports any LDAP server that follows the LDAPv3 protocol. StartTLS/SSL connection is also supported.
SASL authentication is not yet supported. Some LDAP servers are configured to require a client certificate upon connection. Client certificates are not yet supported in GSQL LDAP authentication.
In order to manage the user roles and privileges, the TigerGraph GSQL server employs two concepts—proxy user and proxy group.
A proxy user is a GSQL user created to correspond to an external LDAP user. When operating within GSQL, the external LDAP user's roles and privileges are determined by the proxy user.
A proxy group is a GSQL user group that is used to manage a group of proxy users who share similar properties/attributes in LDAP.
An existing LDAP user can log in to GSQL only when the user matches at least one of the existing proxy groups' criteria. Once the criteria are satisfied, a proxy user will be created for the LDAP user. The roles and privileges of the proxy user are at least as permissive as the proxy group(s) he belongs to. It is also possible to change the roles of a specific proxy user independently. When the roles and privileges of a proxy group changes, the roles and privileges of all the proxy users belonging to this proxy group change accordingly.
To configure a TigerGraph system to use LDAP, there are two main configuration steps:
Configure the LDAP Connection.
Configure GSQL Proxy Groups and Users.
Sufficient privileges are required to configure LDAP Authentication:
WRITE_ROLE
WRITE_PROXYGROUP
To enable and configure LDAP, run three commands.
Configure LDAP:
The gadmin program will then prompt the user for the settings for several LDAP configuration parameters.
2. Apply the configuration:
3. Restart the gsql server:
An example configuration is shown below.
Below is an explanation of each configuration parameter.
This section explains how to configure a GSQL proxy group in order to allow LDAP user authentication.
A GSQL proxy group is created by the CREATE GROUP command with a given proxy rule. For example, assume there is an attribute called "role" in the LDAP directory, and "engineering" is one of the "role" attribute values. We can create a proxy group with the proxy rule "role=engineering". Different roles can then be assigned to the proxy group. An example is shown below. When a user logins, the GSQL server searches for the user's entry in the LDAP directory. If the user's LDAP entry matches the proxy rule of an existing proxy group, a proxy user is created to which the user will log in.
The SHOW GROUP command will display information about a group. The DROP GROUP command deletes the definition of a group.
Nothing needs to be configured for a proxy user. As long as the proxy rule matches, the proxy user will be automatically created upon login. A proxy user is very similar to a normal user. The minor differences are that a proxy user cannot change their password in GSQL and that a proxy user comes with default roles inherited from the proxy group that they belong to.
Admin_dn is the "distinguished name" of an LDAP entry. In LDAP, "distinguished name" is often abbreviated as dn. When configuring this field, a dn entry with read permission on the ldap directory is expected. Configuring a dn with no read permission will result in an error. Not configuring this field will likely result in an error since the LDAP server is typically not publicly readable. Please note that only the dn field will be accepted for this entry. All other entries will result in an authentication error. The corresponding password for the configured dn should also be set correctly in the configured entry "security.ldap.admin_password ".
It depends on what type of protocol your LDAP server uses. SSL/TLS is very common in enterprise use today. When SSL is used, the port is typically 636 instead of default port 389.
You need to configure the truststore when SSL/TLS is used in the LDAP server. The truststore's path, password, and format need to be configured accordingly. We support two formats—JKS and PKCS12. The JKS is Java KeyStore. The corresponding certificates for the LDAP server need to be imported to the JKS for successful authentication. Different truststore formats are typically interchangeable.
This might be the case if SSL/TLS is enabled from the LDAP server side but you don't have a certificate. You can set "security.ldap.secure.trust_all" to true to bypass the SSL/TLS certificate checking.
"Parameter error" means some of the LDAP configurations are not set properly. Most often it is because admin_dn, admin_password, or the login username and password are not set correctly. Unfortunately, we cannot know exactly what field is wrong because the LDAP server side does not respond back with such detail.
This will allow users with the roles role1
and role2
to edit and install queries, as well as modify roles on the graph example_graph
. To see a full list of privileges and the command they allow users to run, see .
In order to choose and specify your LDAP configuration settings, you must understand some basic LDAP concepts. One reference for LDAP concepts is .
Congratulations! This means the LDAP is working. However, TigerGraph cannot find a matching rule for the login user. Please create a proxy group for the user. See documents for creating a proxy group .
Name
Global or Local
Privilege List
observer
Local
READ_SCHEMA
, READ_LOADINGJOB
,READ_QUERY
queryreader
Local
READ_SCHEMA
, READ_LOADINGJOB
,READ_QUERY
, EXECUTE_LOADINGJOB
, READ_DATA
querywriter
Local
READ_SCHEMA
, READ_LOADINGJOB
,READ_QUERY
, EXECUTE_LOADINGJOB
, READ_DATA
, WRITE_QUERY, WRITE_DATA
designer
Local
READ_SCHEMA
, READ_LOADINGJOB
,READ_QUERY
, EXECUTE_LOADINGJOB
, READ_DATA
, WRITE_QUERY, WRITE_DATA
, WRITE_SCHEMA
, WRITE_LOADINGJOB
, ACCESS_TAG
admin
Local
READ_SCHEMA
, READ_LOADINGJOB
,READ_QUERY
, EXECUTE_LOADINGJOB
, READ_DATA
, WRITE_QUERY, WRITE_DATA
, WRITE_SCHEMA
, WRITE_LOADINGJOB
, ACCESS_TAG
WRITE_ROLE
, WRITE_DATASOURCE
, READ_ROLE
, READ_USER
, READ_PROXYGROUP
globaldesigner
Global
Designer’s privileges on global + drop graph created by the same user
superuser
Global
All supported privileges
Name | Description | Example |
Security.LDAP.AdminDN | Configure the DN of LDAP user who has read access to the base DN specified above. Empty if everyone has read access to LDAP data: default empty |
|
Security.LDAP.AdminPassword | Configure the password of the admin DN specified above. Needed only when admin_dn is specified: default empty. If the value provided is a path to a script, the parameter will be set to the output of the script. |
|
Security.LDAP.BaseDN | Configure LDAP search base DN, the root node to start the LDAP search for user authentication: must specify |
|
Security.LDAP.Enable | Enable LDAP authentication: default false |
|
Security.LDAP.Hostname | Configure LDAP server hostname: default localhost |
|
Security.LDAP.Port | Configure LDAP server port: default 389 |
|
Security.LDAP.SearchFilter | Configure LDAP search base DN, the root node to start the LDAP search for user authentication. |
|
Security.LDAP.Secure.Protocol | Enable SSL/StartTLS for LDAP connection [none/ssl/starttls]: default none |
|
Security.LDAP.Secure.TrustAll | Configure to trust all LDAP servers (unsafe): default false |
|
Security.LDAP.Secure.TruststoreFormat | Configure the truststore format [JKS/PKCS12]: default JKS |
|
Security.LDAP.Secure.TruststorePassword | Configure the truststore password: default changeit |
|
Security.LDAP.Secure.TruststorePath | Configure the truststore absolute path for the certificates used in SSL: default empty. If the value provided is a path to a script, the parameter will be set to the output of the script. |
|
Security.LDAP.UsernameAttribute | Configure the username attribute name in LDAP server: default uid |
|
This page explains the procedures for various user management tasks under TigerGraph's authorization model.
Syntax
Required privilege
WRITE_USER
Procedure
From the GSQL shell, run the CREATE USER
command:
Enter the user information in the prompts that follow:
Syntax
Required privilege
READ_USER
for displaying roles of other users
Procedure
From the GSQL shell, run the SHOW USER
command:
If the user running the command has the READ_USER
privilege, role information on all users will be displayed. Otherwise, only the current user's roles will be displayed.
Syntax
Required privilege
READ_USER
Procedure
From the GSQL shell, run the SHOW PRIVILEGE ON USER
command :
The above command will show the privileges of user tigergraph
:
Syntax
Required privilege
WRITE_ROLE
Procedure
Start the GSQL shell and make sure you are using the correct graph
From the GSQL shell, run the GRANT ROLE
command. You can grant multiple roles to multiple users:
The above command will grant roles role1
and role2
on graph example_graph
to users user1
and user2
.
Syntax
Required privilege
WRITE_ROLE
Procedure
Start the GSQL shell and make sure you are using the correct graph
From the GSQL shell, run the REVOKE_ROLE
command. You can revoke multiple roles from multiple users at the same time:
The above command will revoke roles role1
and role2
on graph example_graph
from users user1
and user2
.
Syntax
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
Enter the new password in the prompt that follows.
Syntax
Required privilege
WRITE_USER
Procedure
From the GSQL shell, run the DROP USER
command. You can drop multiple users in the same command.
GSQL will confirm that the users you entered have been dropped
The Single Sign-On (SSO) feature in TigerGraph enables you to use your organization's identity provider (IDP) to authenticate users to access TigerGraph GraphStudio and Admin Portal UI.
Currently we have verified following the identity providers which support SAML 2.0 protocol:
For supporting additional IDPs, please inquire sales@tigergraph.com and submit a feature request.
In order to use Single Sign-On , you need to perform four steps :
Configure your identity provider to create a TigerGraph application.
Provide information from your identity provider to enable TigerGraph Single Sign-On .
Create user groups with proxy rules to authorize Single Sign-On users.
Change the password of the tigergraph user to be other than the default, if you haven't done so already.
We assume you already have TigerGraph up and running , and you can access GraphStudio UI through a web browser using the URL: http://tigergraph-machine-honestname:14240
If you enabled SSL connection, change http
to https
. If you changed the Nginx port of the TigerGraph system, replace 14240 with the port you have set.
Here we provide detailed instructions for identity providers that we have verified. Please consult your IT or security department for how to configure the identity provider for your organization if it is not listed here.
After you finish configuring your identity provider, you will get the following:
An Identity Provider Single Sign-On URL
An Identity Provider Entity ID
an X.509 certificate file idp.cert
. You need these 3 things to configure TigerGraph next.
After logging into Okta as the admin user, click Admin button at the top-right corner.
Click Add Applications in the right menu.
Click Create New App button in the left toolbar.
In the pop up window, choose SAML 2.0 and click Create .
Input TigerGraph (or whatever application name you want to use) in App Name , and click Next . Upload a logo if you like.
Enter the Assertion Consumer Service URL / Single sign on URL , and SP Entity ID .
Both are URLs in our case. You need to know the hostname of the TigerGraph machine. If you can visit GraphStudio UI through a browser, the URL contains the hostname. It can be either an IP or a domain name.
The Assertion Consumer Service URL, or Single sign on URL, is
Assertion Consumer Service URL, or Single sign on URL: http://tigergraph-machine-hostname:14240/api/auth/saml/acs
The SP entity id URL: http://tigergraph-machine-hostname:14240/gsqlserver/gsql/saml/meta
Scroll to the bottom for Group Attribute Statements. Usually you want to grant roles to users based on their user group. You can give a name to your attribute statement; here we use group . For filter, we want to return all group attribute values of all users, so we use Regex .* as the filter. Click Next after you set up everything.
In the final step, choose whether you want to integrate your app with Okta or not. Then click Finish .
Now your Okta identity provider settings are finished. Click View Setup Instructions button to gather information you will need to setup TigerGraph Single Sign-On.
Here you want to save Identity Provider Single Sign-On URL and Identity Provider Issuer (usually known as Identity Provider Entity Id ). Download the certificate file as okta.cert, rename it as idp.cert , and put it somewhere on the TigerGraph machine. Let's assume you put it under your home folder: /home/tigergraph/idp.cert. If you installed TigerGraph in a cluster, you should put it on the machine where the GSQL server is installed (usually it's the machine whose alias is m1).
Finally, return to previous page, go to the Assignments tab, click the Assign button, and assign people or groups in your organization to access this application.
After logging into Auth0, click Clients in the left navigation bar, and then click CREATE CLIENT button.
In the pop-up window, enter TigerGraph (or whatever application name you want to use) in the Name input box. Choose Single Page Web Application , and then click the CREATE button.
Click Clients again. In the Shown Clients list, click the settings icon of your newly created TigerGraph client.
Scroll down to the bottom of the settings section, and click Show Advanced Settings .
Click the Certificates tab and then click DOWNLOAD CERTIFICATE. In the chooser list, choose CER. Rename the downloaded file as idp.cert , and put it somewhere on the TigerGraph machine. Let's assume you put it under your home folder: /home/tigergraph/idp.cert. If you installed TigerGraph in a cluster, you should put it on the machine where the GSQL server is installed ( usually it's the machine whose alias is m1 ).
Click the Endpoints tab, and copy the text in the SAML Protocol URL text box. This is the Identity Provider Single Sign-On URL that will be used to configure TigerGraph in an upcoming step.
Scroll up to the top of the page, click the Addons tab, and switch on the toggle at the right side of the SAML2 card.
In the pop-up window, enter the Assertion Consumer Service URL in the Application Callback URL input box:
http://tigergraph-machine-hostname:14240/api/auth/saml/acs
Scroll down to the end of the settings JSON code, click the DEBUG button, and log in as any existing user in your organization in the pop-up login page.
If login in successfully, the SAML response will be shown in decoded XML format. Scroll down to the attributes section. Here you will see some attribute names, which you will use to set proxy rules when creating groups in an upcoming configuration step.
Return to the previous pop-up window and click the Usage tab. Copy the Issuer value. This is the Identity Provider Entity Id that will be used to configure TigerGraph in an upcoming step.
Click the Settings tab, scroll to the bottom of the pop-up window, and click the SAVE button. Close the pop-up window.
According to the SAML standard trust model, a self-signed certificate is considered fine. This is different from configuring a SSL connection, where a CA-authorized certificate is considered mandatory if the system goes to production.
There are multiple ways to create a self-signed certificate. One example is shown below.
First, use the following command to generate a private key in PKCS#1 format and a X.509 certificate file. In the example below, the Common Name value should be your server hostname (IP or domain name).
Second, convert your private key from PKCS#1 format to PKCS#8 format:
From a TigerGraph machine, run the following command: gadmin config entry Security.SSO.SAML
Answering the questions is straightforward; an example is shown below.
Since v2.3, the requirements for the Security.SSO.SAML.SP.Hostname parameter changed. The url must be a full url, starting with protocol (such as http) and ending with port number.
The reason we change Security.SSO.SAML.ResponseSigned to false is because some identity providers (e.g., Auth0) don't support signed assertion and response at the same time. If your identity provider supports signing both, we strongly suggest you leave it as true.
After making the configuration settings, apply the config changes, and restart gsql.
In order to authorize Single Sign-On users, you need create user groups in GSQL with proxy rules and grant roles on graphs for the user groups.
In TigerGraph Single Sign-On, we support two types of proxy rules:
nameid equations
attribute equations
Attribute equations are more commonly used because usually user group information is transferred as attributes to your identity provider SAML assertions. In the Okta identity provider configuration example, it is transferred by the attribute statement named group. By granting roles to a user group, all users matching the proxy rule will be granted all the privileges of that role. In some cases if you want to grant one specific Single Sign-On user some privilege, you can use a nameid equation to do so.
WRITE_PROXYGROUP
for creating proxy groups.
WRITE_ROLE
for granting roles to users
For example, if you want to create a user group SuperUserGroup that contains the user with nameid admin@your.company.com only, and grant superuser role to that user, you can do so with the following command:
Suppose you want to create a user group HrDepartment which corresponds to the identity provider Single Sign-On users having the group attribute value "hr-department", and want to grant the queryreader role to that group on the graph HrGraph:
Don't forget to enable User Authorization in TigerGraph by changing the password of the default superuser tigergraph to other than its default value. If you do not change the password, then every time you visit the GraphStudio UI, you will automatically log in as the superuser tigergraph.
Now you have finished all configurations for Single Sign-On. Let's test it.
Visit the GraphStudio UI in your browser. You should see a Login with SSO button appear on top of the login panel:
If after redirecting back to GraphStudio, you return to the login page with the error message shown below, that means the Single Sign-On user doesn't have access to any graph. Please double check your user group proxy rules, and roles you have granted to the groups.
If your Single Sign-On fails with error message show below, that means either some configuration is inconsistent between TigerGraph and your identity provider, or something unexpected happened.
You can check your GSQL log to investigate. First, find your GSQL log file with the following:
Then, grep the SAML authentication-related logs:
Focus on the latest errors. Usually the text is self-descriptive. Follow the error message and try to fix TigerGraph or your identity provider's configuration. If you encounter any errors that are not clear, please contact support@tigergraph.com .
Clicking the button will navigate to your identity provider's login portal. If you have already logged in there, you will be redirected back to GraphStudio immediately. After about 10 seconds, the verification should finish, and you are authorized to use GraphStudio. If you haven't login at your identity provider yet, you will need to log in there. After logging in successfully, you will see your Single Sign-On username when you click the User icon at the upper right of the GraphStudio UI.