diff --git a/docs/user_technical/how_to_guides/01_how-to-guides-overview.md b/docs/user_technical/how_to_guides/01_how-to-guides-overview.md index fba0ea5f9..e49ef1e57 100644 --- a/docs/user_technical/how_to_guides/01_how-to-guides-overview.md +++ b/docs/user_technical/how_to_guides/01_how-to-guides-overview.md @@ -9,3 +9,4 @@ So far we have covered the following topics: * [Import Tools](02_import-tools.md) * [Programmatic Querying](03_programmatic-querying.md) * [How to Ingest Data Using Kafka](04_how-to-ingest-data-using-kafka.md) + * [Manage User Privileges](05_manage-user-privileges.md) diff --git a/docs/user_technical/how_to_guides/05_manage-user-privileges.md b/docs/user_technical/how_to_guides/05_manage-user-privileges.md new file mode 100644 index 000000000..5baf510aa --- /dev/null +++ b/docs/user_technical/how_to_guides/05_manage-user-privileges.md @@ -0,0 +1,142 @@ +## How to Manage User Privileges? + +Most databases have multiple users accessing and modifying +data within the database. This might pose a serious security concern for the +system administrators that wish to grant only certain privileges to certain +users. A typical example would be an internal database of some company which +tracks data about their employees. Naturally, only certain users of the database +should be able to perform queries which modify that data. + +At Memgraph, we provide the administrators with the option of granting, +denying or revoking a certain set of privileges to some users or groups of users +(i.e. users that are assigned a specific user role), thereby eliminating such +security concerns. + +By default, anyone can connect to Memgraph and is granted all privileges. +After the first user is created, Memgraph will execute a query if and only +if either a user or its role is granted that privilege and neither the +user nor its role are denied that privilege. Otherwise, Memgraph will not +execute that specific query. Note that `DENY` is a stronger +operation than `GRANT`. This is also notable from the fact that if neither the +user nor its role are explicitly granted or denied a certain privilege, that +user will not be able to perform that specific query. This effect also is known +as a silent deny. The information above is neatly condensed in the following +table: + +User Status | Role Status | Effective Status +--------------------------------------------- +GRANT | GRANT | GRANT +GRANT | DENY | DENY +GRANT | NULL | GRANT +DENY | GRANT | DENY +DENY | DENY | DENY +DENY | NULL | DENY +NULL | GRANT | GRANT +NULL | DENY | DENY +NULL | NULL | DENY + +All supported commands that deal with accessing or modifying users, user +roles and privileges can only be executed by users that are granted the +`AUTH` privilege. All of those commands are listed in the appropriate +[reference guide](../reference_guide/security.md). + +At the moment, privileges are confined to users' abilities to perform certain +`OpenCypher` queries. Namely users can be given permission to execute a subset +of the following commands: `CREATE`, `DELETE`, `MATCH`, `MERGE`, `SET`, +`REMOVE`, `INDEX`, `AUTH`, `STREAM`. + +We could naturally cluster those privileges into groups: + + * Privilege to access data (`MATCH`) + * Privilege to modify data (`MERGE`, `SET`) + * Privilege to create and delete data (`CREATE`, `DELETE`, `REMOVE`) + * Privilege to index data (`INDEX`) + * Privilege to use data streaming (`STREAM`) + * Privilege to view and alter users, roles and privileges (`AUTH`) + +If you are unfamiliar with any of these commands, you can look them up in our +[reference guide](../reference_guide/01_reference-overview.md). + +Similarly, the complete list of commands which can be executed under `AUTH` +privilege can be viewed in the +[appropriate article](../reference_guide/08_security.md) within our reference +guide. + +The remainder of this article outlines a recommended workflow of +user management within an internal database of a fictitious company. + +### Creating an Administrator + +As it was stated in the introduction, after the first user is created, Memgraph +will execute a query for a given user if the effective status of a corresponding +privilege evaluates to `GRANT`. As a corollary, the person that created the +first user might not be able to perform any meaningful action after their +session had ended. To prevent that from happening, we strongly recommend +the first created user to be an administrator which is granted all privileges. + +Therefore, let's create a user named `admin` and set its' password to `0000`. +This can be done by executing: + +```openCypher + CREATE USER admin IDENTIFIED BY '0000'; +``` + +Granting all privileges to our `admin` user can be done as follows: + +```openCypher + GRANT ALL PRIVILEGES to admin; +``` + +At this point, the current user can close their session and log into a new +one as an `admin` user they have just created. The remainder of the article +is written from the viewpoint of an administrator which is granted +all privileges. + +### Creating Other Users + +Our fictitious company is internally divided into teams, and each team has +its own supervisor. All employees of the company need to access and modify +data within the database. + +Creating a user account for a new hire named Alice can be done as follows: + +```openCypher + CREATE USER alice IDENTIFIED BY '0042'; +``` + +Alice should also be granted a privilege to access data, which can be done by +executing the following: + +```openCypher + GRANT MATCH, MERGE, SET TO alice; +``` + +### Creating User Roles + +Each team supervisor needs to have additional privileges that allow them to +create new data or delete existing data from the database. Instead of tediously +granting additional privileges to each supervisor using language constructs from +the previous chapter, we could do so by creating a new user role for +supervisors. + +Creating a user role named `supervisor` can be done by executing the following +command: + +```openCypher + CREATE ROLE supervisor; +``` + +Granting the privilege to create and delete data to our newly created role can +be done as follows: + +```openCypher + GRANT CREATE, DELETE, REMOVE TO supervisor; +``` + +Finally, we need to assign that role to each of the supervisors. Suppose, a user +named `bob` is indeed a supervisor within the company. Assigning them that role +within the database can be done by the following command: + +``` + SET ROLE FOR bob TO supervisor; +``` diff --git a/docs/user_technical/reference_guide/01_reference-overview.md b/docs/user_technical/reference_guide/01_reference-overview.md index ec40c059e..06f189319 100644 --- a/docs/user_technical/reference_guide/01_reference-overview.md +++ b/docs/user_technical/reference_guide/01_reference-overview.md @@ -16,6 +16,7 @@ Our reference guide currently consists of the following articles: * [Indexing](05_indexing.md) * [Graph Algorithms](06_graph-algorithms.md) * [Graph Streams](07_graph-streams.md) - * [Dynamic Graph Partitioner](08_dynamic-graph-partitioner.md) - * [Other Features](09_other-features.md) - * [Differences](10_differences.md) + * [Security](08_security.md) + * [Dynamic Graph Partitioner](09_dynamic-graph-partitioner.md) + * [Other Features](10_other-features.md) + * [Differences](11_differences.md) diff --git a/docs/user_technical/reference_guide/08_security.md b/docs/user_technical/reference_guide/08_security.md new file mode 100644 index 000000000..51cd949a4 --- /dev/null +++ b/docs/user_technical/reference_guide/08_security.md @@ -0,0 +1,125 @@ +## Security + +Before reading this article we highly recommend going through a how-to guide +on [managing user privileges](../how_to_guides/05_manage-user-privileges.md) +which contains more thorough explanations of the concepts behind `openCypher` +commands listed in this article. + +### Users + +Creating a user can be done by executing the following command: + +```openCypher + CREATE USER user_name [IDENTIFIED BY 'password']; +``` +If the user should authenticate themself on each session, i.e. provide their +password on each session, the part within the brackets is mandatory. Otherwise, +the password is set to `null` and the user will be allowed to log-in using +any password provided that they provide the correct username. + +You can also set or alter a user's password anytime by issuing the following +command: + +```openCypher + SET PASSWORD FOR user_name TO 'new_password'; +``` + +Removing a user's password, i.e. allowing the user to log-in using any +password can be done by setting it to `null` as follows: + +```openCypher + SET PASSWORD FOR user_name TO null; +``` + +### User Roles + +Each user can be assigned at most one user role. One can think of user roles +as abstractions which capture the privilege levels of a set of users. For +example, suppose that `Dominik` and `Marko` belong to upper management of +a certain company. It makes sense to grant them a set of privileges that other +users are not entitled to so, instead of granting those privileges to each +of them, we can create a role with those privileges called `manager` +which we assign to `Dominik` and `Marko`. + +In other words, Each privilege that is granted to a user role is automatically +granted to a user (unless it has been explicitly denied to that user). +Similarly, each privilege that is denied to a user role is automatically denied +to a user (even if it has been explicitly granted to that user). + +Creating a user role can be done by executing the following command: + +```openCypher + CREATE ROLE role_name; +``` + +Assigning a user role to a certain user can be done by the following command: + +```openCypher + SET ROLE FOR user_name TO role_name; +``` + +Removing the role from the user can be done by: + +```openCypher + CLEAR ROLE FOR user_name; +``` + +Finally, showing all users that have a certain role can be done as: + +```openCypher + SHOW USERS FOR role_name; +``` + +Similarly, querying which role a certain user has can be done as: + +```openCypher + SHOW ROLE FOR user_name; +``` + +### Privileges + +At the moment, privileges are confined to users' abilities to perform certain +`OpenCypher` queries. Namely users can be given permission to execute a subset +of the following commands: `CREATE`, `DELETE`, `MATCH`, `MERGE`, `SET`, +`REMOVE`, `INDEX`, `AUTH`, `STREAM`. + +Granting a certain set of privileges to a specific user or user role can be +done by issuing the following command: + +```openCypher + GRANT privilege_list TO user_or_role; +``` + +For example, granting `AUTH` and `STREAM` privileges to users with the role +`moderator` would be written as: + +```openCypher + GRANT AUTH, STREAM TO moderator: +``` + +Similarly, denying privileges is done using the `DENY` keyword instead of +`GRANT`. + +Both denied and granted privileges can be revoked, meaning that their status is +not defined for that user or role. Revoking is done using the `REVOKE` keyword. +The users should note that, although semantically unintuitive, the level of a +certain privilege can be raised by using `REVOKE`. For instance, suppose a user +has been denied a `STREAM` privilege, but the role it belongs to is granted +that privilege. Currently, the user is unable to use data streaming features, +but, after revoking the user's `STREAM` privilege, they will be able to do so. + +Finally, if you wish to grant, deny or revoke all privileges and find it tedious +to explicitly list them, you can use the `ALL PRIVILEGES` construct instead. +For example, revoking all privileges from user `jdoe` can be done with the +following command: + +```openCypher + REVOKE ALL PRIVILEGES FROM jdoe; +``` + +Finally, obtaining the status of each privilege for a certain user or role can be +done by issuing the following command: + +```openCypher + SHOW PRIVILEGES FOR user_or_role; +``` diff --git a/docs/user_technical/reference_guide/08_dynamic-graph-partitioner.md b/docs/user_technical/reference_guide/09_dynamic-graph-partitioner.md similarity index 100% rename from docs/user_technical/reference_guide/08_dynamic-graph-partitioner.md rename to docs/user_technical/reference_guide/09_dynamic-graph-partitioner.md diff --git a/docs/user_technical/reference_guide/09_other-features.md b/docs/user_technical/reference_guide/10_other-features.md similarity index 100% rename from docs/user_technical/reference_guide/09_other-features.md rename to docs/user_technical/reference_guide/10_other-features.md diff --git a/docs/user_technical/reference_guide/10_differences.md b/docs/user_technical/reference_guide/11_differences.md similarity index 100% rename from docs/user_technical/reference_guide/10_differences.md rename to docs/user_technical/reference_guide/11_differences.md