logo
Contact Us

Features

Access Control in NebulaGraph: Design, Code, and Operations

Access Control in NebulaGraph: Design, Code, and Operations

Access Control List (ACL) is not alien to database users and it is a significant part of data security. Like other database vendors, NebulaGraph takes data security seriously and now supports role-based access control.

In this article, we will detail user management with roles and privileges of NebulaGraph.

The Authentication Workflow

NebulaGraph is composed of three parts: the query engine, the storage layer and the meta service. The console, API and the web service are collectively referred to as Client API. See the figure below:

The Authentication Workflow

The account and role data will be stored in the meta engine. When query engine is started, the meta client through which the query engine communicates with the meta service will be initialized.

When users connect to query engine through the client API, the query engine will check the user information on the meta engine via the meta client, determining the existence of the requesting account and the correctness of the password. Once the verification is passed, the connection succeeds. Users can then perform data operations in this session.

Once a query is received, the query engine will parse it, which involves identifying the command type and verifying user's authority based on the operation and the user's role. If the authority is invalid, the command will be blocked in the query engine and an error is returned to the client API. In the entire permission check process, NebulaGraph caches the meta data. We will detail this in the next chapter.

The Access Control Logic

In general, access control is realized through roles and privileges granted to each role. However, in NebulaGraph, permissions are also granted at graph space level.

NebulaGraph supports creating multiple graph spaces in the database. The schema and graph data are managed in each space independently and the spaces are psychically isolated from each other. In addition, NebulaGraph also provides a set of advanced commands for managing the cluster globally.

Therefore, the ACL of NebulaGraph will be managed in three dimensions: graph spaces, roles and operations.

Role Types

NebulaGraph provides five built-in roles: GOD, ADMIN, DBA, USER and GUEST. These roles have covered all the scenarios in data security. An account can have different roles in different spaces. But it can only have one role in the same space.

Descriptions for the roles:

  • GOD

    • The initial root user similar to the Root in Linux.
    • Has the highest management access to the cluster.
    • When a cluster is initialized, a GOD account named root is created by default.
  • ADMIN

    • Advanced administration at the graph space level.
    • Full management access to a specific graph space.
    • No management access to the cluster.
  • DBA

    • Database administration.
    • Access to its authorized graph space. For example, alter or query the schema and data.
    • Not able to assign roles to users compared to ADMIN.
  • USER

    • Read/write access to the graph data limited to its authorized space.
    • Read-only access to the schema limited to its authorized space.
  • GUEST

    • Read-only access to both the schema and graph data limited to its authorized space.

Detailed role list is shown below.

OPERATION GOD ADMIN DBA USER GUEST
Read Space Y Y Y Y Y
Write Space Y
Read Schema Y Y Y Y Y
Write Schema Y Y Y
Write User Y
Write Role Y Y
Read Data Y Y Y Y Y
Write Data Y Y Y Y
Special Operation Y Y Y Y Y

Note: The Special Operation is available for every user. However, only account authorized result will be returned. For example, SHOW SPACE returns the spaces that account can access to.

Database Operations List

Please refer to the table below for the statements of each operation:

OPERATION STATEMENTS
Read Space 1.USE 2.DESCRIBE SPACE
Write Space 1.CREATE SPACE 2.DROP SPACE 3.CREATE SNAPSHOT 4.DROP SNAPSHOT 5.BALANCE
Read Schema 1.DESCRIBE TAG 2.DESCRIBE EDGE 3.DESCRIBE TAG INDEX 4.DESCRIBE EDGE INDEX
Write Schema 1.CREATE TAG 2.ALTER TAG 3.CREATE EDGE 4.ALTER EDGE 5.DROP TAG 6.DROP EDGE 7.CREATE TAG INDEX 8.CREATE EDGE INDEX 9.DROP TAG INDEX 10.DROP EDGE INDEX
Write User 1.CREATE USER 2.DROP USER 3.ALTER USER
Write Role 1. GRANT 2.REVOKE
Read Data 1.GO 2. PIPE 3.LOOKUP 4.YIELD 5.ORDER BY 6.FETCH VERTEX 7.FETCH EDGE 8. FIND PATH 9.LIMIT 10.GROUP BY 11. RETURN
Write Data 1. REBUILD TAG INDEX 2.REBUILD EDGE INDEX 3.INSERT VERTEX 4.UPDATE VERTEX 5.INSERT EDGE 6.UPDATE EDGE 7.DELETE VERTEX 8.DELETE EDGE
Special Operation 1. SHOW,e.g.: SHOW SPACE, SHOW ROLES 2.CHANGE PASSWORD

The Access Control Workflow

The Access Control Workflow

Similar to most databases, NebulaGraph fetches access control information from the meta server and authenticates users from the perspectives of the graph space, roles and operations.  Once receiving the connection request from the client, NebulaGraph server will first check the existence of the requesting account and the correctness of the password.

When the login succeeds, NebulaGraph server will initialize the session ID for the connection, loading the session ID, user information, privileges and graph space information into the session. Each subsequent operation will be authorized based on the session information. The session will not be destroyed until the user logs out or session timeout.

In addition, the meta server syndicates the access control information to the meta client periodically so that it can cache the authentication data, thus greatly reducing the network consumption of each connection.

The Access Control Code Snippets

permissionCheck

bool PermissionCheck::permissionCheck(session::Session *session, Sentence* sentence) {
    auto kind = sentence->kind();
    switch (kind) {
        case Sentence::Kind::kUnknown : {
            return false;
        }
        case Sentence::Kind::kUse :
        case Sentence::Kind::kDescribeSpace : {
            /**
             * Use space and Describe space are special operations.
             * Permission checking needs to be done in their executors.
             * skip the check here.
             */
            return true;
        }
        ...

Permission check entry

Status SequentialExecutor::prepare() {
    for (auto i = 0U; i < sentences_->sentences_.size(); i++) {
        auto *sentence = sentences_->sentences_[i].get();
        auto executor = makeExecutor(sentence);
        if (FLAGS_enable_authorize) {
            auto *session = executor->ectx()->rctx()->session();
            /**
             * Skip special operations check here, which are:
             * kUse, kDescribeSpace, kRevoke and kGrant.
             */
            if (!PermissionCheck::permissionCheck(session, sentence)) {
                return Status::PermissionError("Permission denied");
            }
        }
   ...
}

Access Control Sample Queries

Show Users

nebula> show users;
===========
| Account |
===========
| root    |
-----------

Create Users

(root@127.0.0.1:6999) [(none)]> CREATE USER user1 WITH PASSWORD "pwd1"
Execution succeeded (Time spent: 194.471/201.007 ms)

(root@127.0.0.1:6999) [(none)]> CREATE USER user2 WITH PASSWORD "pwd2"
Execution succeeded (Time spent: 33.627/40.084 ms)

# Check the roles of existing users

(root@127.0.0.1:6999) [(none)]> SHOW USERS;
===========
| Account |
===========
| root    |
-----------
| user1   |
-----------
| user2   |
-----------
Got 3 rows (Time spent: 24.415/32.173 ms)

Grant Roles for Different Accounts

# Create a graph space

(root@127.0.0.1:6999) [(none)]> CREATE SPACE user_space(partition_num=1, replica_factor=1)
Execution succeeded (Time spent: 218.846/225.075 ms)

(root@127.0.0.1:6999) [(none)]> GRANT DBA ON user_space TO user1
Execution succeeded (Time spent: 203.922/210.957 ms)

(root@127.0.0.1:6999) [(none)]> GRANT ADMIN ON user_space TO user2
Execution succeeded (Time spent: 36.384/49.296 ms)

Show Roles in a Graph Space

(root@127.0.0.1:6999) [(none)]> SHOW ROLES IN user_space
=======================
| Account | Role Type |
=======================
| user1   | DBA       |
-----------------------
| user2   | ADMIN     |
-----------------------
Got 2 rows (Time spent: 18.637/29.91 ms)

Revoke Roles in a Graph Space

(root@127.0.0.1:6999) [(none)]> REVOKE ROLE DBA ON user_space FROM user1
Execution succeeded (Time spent: 201.924/216.232 ms)

# Show roles after revoking a role

(root@127.0.0.1:6999) [(none)]> SHOW ROLES IN user_space
=======================
| Account | Role Type |
=======================
| user2   | ADMIN     |
-----------------------
Got 1 rows (Time spent: 16.645/32.784 ms)

Drop User

(root@127.0.0.1:6999) [(none)]> DROP USER user2
Execution succeeded (Time spent: 203.396/216.346 ms)

# Show the role of user2 role in the graph space

(root@127.0.0.1:6999) [(none)]> SHOW ROLES IN user_space
Empty set (Time spent: 20.614/34.905 ms)

# Show existing users in the graph space

nebula> show users;
===========
| Account |
===========
| root    |
-----------
| user1   |
-----------
Got 2 rows (Time spent: 22.692/38.138 ms)

Here comes the end of NebulaGraph ACL introduction. If you encounter any problems in usage, please tell us on our forum or GitHub to get help.

_Hi, I'm bright-starry-sky, engineer at NebulaGraph. I'm interested in database storage and would like to share my experiences in this regard. Hope my post is of help to you. Please let me know if you have any ideas about this. Thanks!_

You might also like

  1. How Indexing Works in NebulaGraph
  2. Storage Balance and Data Migration
  3. An Introduction to Snapshot in NebulaGraph