Authentication API

10.1 User Authentication and Access Control

To enable authentication and related configurations, please refer to the Authentication Configuration documentation.

Overview of User Authentication and Access Control:

HugeGraph supports multi-user authentication and fine-grained access control. It adopts a 4-tier design based on “User-User Group-Operation-Resource” to flexibly control user roles and permissions. Resources describe data in the graph database, such as vertices that meet certain conditions. Each resource consists of three elements: type, label, and properties. There are a total of 18 types and combinations of any label and properties to form resources. The internal condition of a resource is an “AND” relationship, while the condition between multiple resources is an “OR” relationship. Users can belong to one or more user groups, and each user group can have permissions for any number of resources. The types of operations include read, write, delete, execute, etc. HugeGraph supports dynamically creating users, user groups, and resources, and supports dynamically assigning or revoking permissions. During the initialization of the database, a super administrator user is created, and subsequently, various role users can be created by the super administrator. If a newly created user is assigned sufficient permissions, they can create or manage more users.

Example:

user(name=boss) -belong-> group(name=all) -access(read)-> target(graph=graph1, resource={label: person, city: Beijing})
Description: User ‘boss’ has read permission for people in the ‘graph1’ graph from Beijing.

Interface Description:

The user authentication and access control interface includes 5 categories: UserAPI, GroupAPI, TargetAPI, BelongAPI, AccessAPI.

10.2 User (User) API

The user interface includes APIs for creating users, deleting users, modifying users, and querying user-related information.

10.2.1 Create User

Params
  • user_name: User name
  • user_password: User password
  • user_phone: User phone number
  • user_email: User email

Both user_name and user_password are required.

Request Body
  1. {
  2.     "user_name": "boss",
  3.     "user_password": "******",
  4.     "user_phone": "182****9088",
  5.     "user_email": "123@xx.com"
  6. }
Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/auth/users
Response Status
  1. 201
Response Body

In the response message, the password is encrypted as ciphertext.

  1. {
  2.     "user_password": "******",
  3.     "user_email": "123@xx.com",
  4.     "user_update": "2020-11-17 14:31:07.833",
  5.     "user_name": "boss",
  6.     "user_creator": "admin",
  7.     "user_phone": "182****9088",
  8.     "id": "-63:boss",
  9.     "user_create": "2020-11-17 14:31:07.833"
  10. }

10.2.2 Delete User

Params
  • id: User ID to be deleted
Method & Url
  1. DELETE http://localhost:8080/graphs/hugegraph/auth/users/-63:test
Response Status
  1. 204
Response Body
  1. 1

10.2.3 Modify User

Params
  • id: User ID to be modified
Method & Url
  1. PUT http://localhost:8080/graphs/hugegraph/auth/users/-63:test
Request Body

Modify user_name, user_password, and user_phone.

  1. {
  2.     "user_name": "test",
  3.     "user_password": "******",
  4.     "user_phone": "183****9266"
  5. }
Response Status
  1. 200
Response Body

The returned result is the entire user object including the modified content.

  1. {
  2.     "user_password": "******",
  3.     "user_update": "2020-11-12 10:29:30.455",
  4.     "user_name": "test",
  5.     "user_creator": "admin",
  6.     "user_phone": "183****9266",
  7.     "id": "-63:test",
  8.     "user_create": "2020-11-12 10:27:13.601"
  9. }

10.2.4 Query User List

Params
  • limit: Upper limit of the number of results returned
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/users
Response Status
  1. 200
Response Body
  1. {
  2.     "users": [
  3.         {
  4.             "user_password": "******",
  5.             "user_update": "2020-11-11 11:41:12.254",
  6.             "user_name": "admin",
  7.             "user_creator": "system",
  8.             "id": "-63:admin",
  9.             "user_create": "2020-11-11 11:41:12.254"
  10.         }
  11.     ]
  12. }

10.2.5 Query a User

Params
  • id: User ID to be queried
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/users/-63:admin
Response Status
  1. 200
Response Body
  1. {
  2.     "users": [
  3.         {
  4.             "user_password": "******",
  5.             "user_update": "2020-11-11 11:41:12.254",
  6.             "user_name": "admin",
  7.             "user_creator": "system",
  8.             "id": "-63:admin",
  9.             "user_create": "2020-11-11 11:41:12.254"
  10.         }
  11.     ]
  12. }

10.2.6 Query Roles of a User

Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/users/-63:boss/role
Response Status
  1. 200
Response Body
  1. {
  2.     "roles": {
  3.         "hugegraph": {
  4.             "READ": [
  5.                 {
  6.                     "type": "ALL",
  7.                     "label": "*",
  8.                     "properties": null
  9.                 }
  10.             ]
  11.         }
  12.     }
  13. }

10.3 Group (Group) API

Groups grant corresponding resource permissions, and users are assigned to different groups, thereby having different resource permissions. The group interface includes APIs for creating groups, deleting groups, modifying groups, and querying group-related information.

10.3.1 Create Group

Params
  • group_name: Group name
  • group_description: Group description
Request Body
  1. {
  2.     "group_name": "all",
  3.     "group_description": "group can do anything"
  4. }
Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/auth/groups
Response Status
  1. 201
Response Body
  1. {
  2.     "group_creator": "admin",
  3.     "group_name": "all",
  4.     "group_create": "2020-11-11 15:46:08.791",
  5.     "group_update": "2020-11-11 15:46:08.791",
  6.     "id": "-69:all",
  7.     "group_description": "group can do anything"
  8. }

10.3.2 Delete Group

Params
  • id: Group ID to be deleted
Method & Url
  1. DELETE http://localhost:8080/graphs/hugegraph/auth/groups/-69:grant
Response Status
  1. 204
Response Body
  1. 1

10.3.3 Modify Group

Params
  • id: Group ID to be modified
Method & Url
  1. PUT http://localhost:8080/graphs/hugegraph/auth/groups/-69:grant
Request Body

Modify group_description

  1. {
  2.     "group_name": "grant",
  3.     "group_description": "grant"
  4. }
Response Status
  1. 200
Response Body

The returned result is the entire group object including the modified content.

  1. {
  2.     "group_creator": "admin",
  3.     "group_name": "grant",
  4.     "group_create": "2020-11-12 09:50:58.458",
  5.     "group_update": "2020-11-12 09:57:58.155",
  6.     "id": "-69:grant",
  7.     "group_description": "grant"
  8. }

10.3.4 Query Group List

Params
  • limit: Upper limit of the number of results returned
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/groups
Response Status
  1. 200
Response Body
  1. {
  2.     "groups": [
  3.         {
  4.             "group_creator": "admin",
  5.             "group_name": "all",
  6.             "group_create": "2020-11-11 15:46:08.791",
  7.             "group_update": "2020-11-11 15:46:08.791",
  8.             "id": "-69:all",
  9.             "group_description": "group can do anything"
  10.         }
  11.     ]
  12. }

10.3.5 Query a Specific Group

Params
  • id: Group ID to be queried
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/groups/-69:all
Response Status
  1. 200
Response Body
  1. {
  2.     "group_creator": "admin",
  3.     "group_name": "all",
  4.     "group_create": "2020-11-11 15:46:08.791",
  5.     "group_update": "2020-11-11 15:46:08.791",
  6.     "id": "-69:all",
  7.     "group_description": "group can do anything"
  8. }

10.4 Resource (Target) API

Resources describe data in the graph database, such as vertices that meet certain criteria. Each resource includes three elements: type, label, and properties. There are 18 types in total, and the combination of any label and any properties forms a resource. The internal conditions of a resource are based on the AND relationship, while the conditions between multiple resources are based on the OR relationship.
The resource API includes creating, deleting, modifying, and querying resources.

10.4.1 Create Resource

Params
  • target_name: Name of the resource
  • target_graph: Graph of the resource
  • target_url: URL of the resource
  • target_resources: Resource definitions (list)

target_resources can include multiple target_resource, stored in the form of a list.
Each target_resource contains:

  • type: Optional value: VERTEX, EDGE, etc. Can be filled with ALL, indicating it can be a vertex or edge.
  • label: Optional value: name of a vertex or edge type. Can be filled with *, indicating any type.
  • properties: Map type, can contain multiple key-value pairs of properties. Must match all property values. Property values can support conditional ranges (e.g., age: P.gte(18)). If properties are null, it means any property is allowed. If both the property name and value are ‘*’, it also means any property is allowed.

For example, a specific resource: “target_resources”: [{“type”:“VERTEX”,“label”:“person”,“properties”:{“city”:“Beijing”,“age”:“P.gte(20)”}}]
The resource definition means: a vertex of type ‘person’ with the city property set to ‘Beijing’ and the age property greater than or equal to 20.

Request Body
  1. {
  2.     "target_name": "all",
  3.     "target_graph": "hugegraph",
  4.     "target_url": "127.0.0.1:8080",
  5.     "target_resources": [
  6.         {
  7.             "type": "ALL"
  8.         }
  9.     ]
  10. }
Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/auth/targets
Response Status
  1. 201
Response Body
  1. {
  2.     "target_creator": "admin",
  3.     "target_name": "all",
  4.     "target_url": "127.0.0.1:8080",
  5.     "target_graph": "hugegraph",
  6.     "target_create": "2020-11-11 15:32:01.192",
  7.     "target_resources": [
  8.         {
  9.             "type": "ALL",
  10.             "label": "*",
  11.             "properties": null
  12.         }
  13.     ],
  14.     "id": "-77:all",
  15.     "target_update": "2020-11-11 15:32:01.192"
  16. }

10.4.2 Delete Resource

Params
  • id: Resource Id to be deleted
Method & Url
  1. DELETE http://localhost:8080/graphs/hugegraph/auth/targets/-77:gremlin
Response Status
  1. 204
Response Body
  1. 1

10.4.3 Modify Resource

Params
  • id: Resource Id to be modified
Method & Url
  1. PUT http://localhost:8080/graphs/hugegraph/auth/targets/-77:gremlin
Request Body

Modify the ’type’ in the resource definition.

  1. {
  2.     "target_name": "gremlin",
  3.     "target_graph": "hugegraph",
  4.     "target_url": "127.0.0.1:8080",
  5.     "target_resources": [
  6.         {
  7.             "type": "NONE"
  8.         }
  9.     ]
  10. }
Response Status
  1. 200
Response Body

The response contains the entire target group object, including the modified content.

  1. {
  2.     "target_creator": "admin",
  3.     "target_name": "gremlin",
  4.     "target_url": "127.0.0.1:8080",
  5.     "target_graph": "hugegraph",
  6.     "target_create": "2020-11-12 09:34:13.848",
  7.     "target_resources": [
  8.         {
  9.             "type": "NONE",
  10.             "label": "*",
  11.             "properties": null
  12.         }
  13.     ],
  14.     "id": "-77:gremlin",
  15.     "target_update": "2020-11-12 09:37:12.780"
  16. }

10.4.4 Query Resource List

Params
  • limit: Upper limit of the number of returned results.
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/targets
Response Status
  1. 200
Response Body
  1. {
  2.     "targets": [
  3.         {
  4.             "target_creator": "admin",
  5.             "target_name": "all",
  6.             "target_url": "127.0.0.1:8080",
  7.             "target_graph": "hugegraph",
  8.             "target_create": "2020-11-11 15:32:01.192",
  9.             "target_resources": [
  10.                 {
  11.                     "type": "ALL",
  12.                     "label": "*",
  13.                     "properties": null
  14.                 }
  15.             ],
  16.             "id": "-77:all",
  17.             "target_update": "2020-11-11 15:32:01.192"
  18.         },
  19.         {
  20.             "target_creator": "admin",
  21.             "target_name": "grant",
  22.             "target_url": "127.0.0.1:8080",
  23.             "target_graph": "hugegraph",
  24.             "target_create": "2020-11-11 15:43:24.841",
  25.             "target_resources": [
  26.                 {
  27.                     "type": "GRANT",
  28.                     "label": "*",
  29.                     "properties": null
  30.                 }
  31.             ],
  32.             "id": "-77:grant",
  33.             "target_update": "2020-11-11 15:43:24.841"
  34.         }
  35.     ]
  36. }

10.4.5 Query a Specific Resource

Params
  • id: Id of the resource to query
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/targets/-77:grant
Response Status
  1. 200
Response Body
  1. {
  2.     "target_creator": "admin",
  3.     "target_name": "grant",
  4.     "target_url": "127.0.0.1:8080",
  5.     "target_graph": "hugegraph",
  6.     "target_create": "2020-11-11 15:43:24.841",
  7.     "target_resources": [
  8.         {
  9.             "type": "GRANT",
  10.             "label": "*",
  11.             "properties": null
  12.         }
  13.     ],
  14.     "id": "-77:grant",
  15.     "target_update": "2020-11-11 15:43:24.841"
  16. }

10.5 Association of Roles (Belong) API

The association between users and user groups allows a user to be associated with one or more user groups. User groups have permissions for related resources, and the permissions for different user groups can be understood as different roles. In other words, users are associated with roles.
The API for associating roles includes creating, deleting, modifying, and querying the association of roles for users.

10.5.1 Create an Association of Roles for a User

Params
  • user: User ID
  • group: User group ID
  • belong_description: Description
Request Body
  1. {
  2.     "user": "-63:boss",
  3.     "group": "-69:all"
  4. }
Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/auth/belongs
Response Status
  1. 201
Response Body
  1. {
  2.     "belong_create": "2020-11-11 16:19:35.422",
  3.     "belong_creator": "admin",
  4.     "belong_update": "2020-11-11 16:19:35.422",
  5.     "id": "S-63:boss>-82>>S-69:all",
  6.     "user": "-63:boss",
  7.     "group": "-69:all"
  8. }

10.5.2 Delete an Association of Roles

Params
  • id: ID of the association of roles to delete
Method & Url
  1. DELETE http://localhost:8080/graphs/hugegraph/auth/belongs/S-63:boss>-82>>S-69:grant
Response Status
  1. 204
Response Body
  1. 1

10.5.3 Modify an Association of Roles

An association of roles can only be modified for its description. The user and group properties cannot be modified. If you need to modify an association of roles, you need to delete the existing association and create a new one.

Params
  • id: ID of the association of roles to modify
Method & Url
  1. PUT http://localhost:8080/graphs/hugegraph/auth/belongs/S-63:boss>-82>>S-69:grant
Request Body

Modify the belong_description field

  1. {
  2.     "belong_description": "update test"
  3. }
Response Status
  1. 200
Response Body

The response includes the modified content as well as the entire association of roles object

  1. {
  2.     "belong_description": "update test",
  3.     "belong_create": "2020-11-12 10:40:21.720",
  4.     "belong_creator": "admin",
  5.     "belong_update": "2020-11-12 10:42:47.265",
  6.     "id": "S-63:boss>-82>>S-69:grant",
  7.     "user": "-63:boss",
  8.     "group": "-69:grant"
  9. }

10.5.4 Query List of Associations of Roles

Params
  • limit: Upper limit on the number of results to return
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/belongs
Response Status
  1. 200
Response Body
  1. {
  2.     "belongs": [
  3.         {
  4.             "belong_create": "2020-11-11 16:19:35.422",
  5.             "belong_creator": "admin",
  6.             "belong_update": "2020-11-11 16:19:35.422",
  7.             "id": "S-63:boss>-82>>S-69:all",
  8.             "user": "-63:boss",
  9.             "group": "-69:all"
  10.         }
  11.     ]
  12. }

10.5.5 View a Specific Association of Roles

Params
  • id: The id of the association of roles to be queried
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/belongs/S-63:boss>-82>>S-69:all
Response Status
  1. 200
Response Body
  1. {
  2.     "belong_create": "2020-11-11 16:19:35.422",
  3.     "belong_creator": "admin",
  4.     "belong_update": "2020-11-11 16:19:35.422",
  5.     "id": "S-63:boss>-82>>S-69:all",
  6.     "user": "-63:boss",
  7.     "group": "-69:all"
  8. }

10.6 Authorization (Access) API

Grant permissions to user groups for resources, including operations such as READ, WRITE, DELETE, EXECUTE, etc. The authorization API includes: creating, deleting, modifying, and querying permissions.

10.6.1 Create Authorization (Granting permissions to user groups for resources)

Params
  • group: Group ID
  • target: Resource ID
  • access_permission: Permission grant
  • access_description: Authorization description

Access permissions:

  • READ: Read operations, including all queries such as querying the schema, retrieving vertices/edges, aggregating vertex and edge counts (VERTEX_AGGR/EDGE_AGGR), and reading the graph’s status (STATUS), variables (VAR), tasks (TASK), etc.
  • WRITE: Write operations, including creating and updating operations, such as adding property keys to the schema or adding/updating properties of vertices.
  • DELETE: Delete operations, including deleting metadata, vertices, or edges.
  • EXECUTE: Execute operations, including executing Gremlin queries, executing tasks, and executing metadata functions.
Request Body
  1. {
  2.     "group": "-69:all",
  3.     "target": "-77:all",
  4.     "access_permission": "READ"
  5. }
Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/auth/accesses
Response Status
  1. 201
Response Body
  1. {
  2.     "access_permission": "READ",
  3.     "access_create": "2020-11-11 15:54:54.008",
  4.     "id": "S-69:all>-88>11>S-77:all",
  5.     "access_update": "2020-11-11 15:54:54.008",
  6.     "access_creator": "admin",
  7.     "group": "-69:all",
  8.     "target": "-77:all"
  9. }

10.6.2 Delete Authorization

Params
  • id: The ID of the authorization to be deleted
Method & Url
  1. DELETE http://localhost:8080/graphs/hugegraph/auth/accesses/S-69:all>-88>12>S-77:all
Response Status
  1. 204
Response Body
  1. 1

10.6.3 Modify Authorization

Authorization can only be modified for its description. User group, resource, and permission cannot be modified. If you need to modify the relationship of the authorization, you can delete the original authorization relationship and create a new one.

Params
  • id: The ID of the authorization to be modified
Method & Url
  1. PUT http://localhost:8080/graphs/hugegraph/auth/accesses/S-69:all>-88>12>S-77:all
Request Body

Modify access_description

  1. {
  2.     "access_description": "test"
  3. }
Response Status
  1. 200
Response Body

Return Result Including Modified Content of the Entire User Group Object

  1. {
  2.     "access_description": "test",
  3.     "access_permission": "WRITE",
  4.     "access_create": "2020-11-12 10:12:03.074",
  5.     "id": "S-69:all>-88>12>S-77:all",
  6.     "access_update": "2020-11-12 10:16:18.637",
  7.     "access_creator": "admin",
  8.     "group": "-69:all",
  9.     "target": "-77:all"
  10. }

10.6.4 Query Authorization List

Params
  • limit: The maximum number of results to return
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/accesses
Response Status
  1. 200
Response Body
  1. {
  2.     "accesses": [
  3.         {
  4.             "access_permission": "READ",
  5.             "access_create": "2020-11-11 15:54:54.008",
  6.             "id": "S-69:all>-88>11>S-77:all",
  7.             "access_update": "2020-11-11 15:54:54.008",
  8.             "access_creator": "admin",
  9.             "group": "-69:all",
  10.             "target": "-77:all"
  11.         }
  12.     ]
  13. }

10.6.5 Query a Specific Authorization

Params
  • id: The ID of the authorization to be queried
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/auth/accesses/S-69:all>-88>11>S-77:all
Response Status
  1. 200
Response Body
  1. {
  2.     "access_permission": "READ",
  3.     "access_create": "2020-11-11 15:54:54.008",
  4.     "id": "S-69:all>-88>11>S-77:all",
  5.     "access_update": "2020-11-11 15:54:54.008",
  6.     "access_creator": "admin",
  7.     "group": "-69:all",
  8.     "target": "-77:all"
  9. }

Last modified July 31, 2023: doc: added cypher api (#280) (18547af3)