Built-in User Authentication and Authorization Configuration and Usage in HugeGraph

Overview

HugeGraph provides StandardAuthenticator for multi-user authentication and access control based on users, groups, operations, and resources.

Initialization creates the admin superuser. Administrators create users, groups, and resources, then grant or revoke permissions. Users receive read, write, delete, and execute permissions through their groups.

A resource describes accessible data using type, label, and properties. Conditions within one resource are combined with AND; multiple resources are combined with OR.

This relationship grants a user read access to data for Beijing.

1// Scenario: A user only has data read permission for the Beijing area
2user(name=xx) -belong-> group(name=xx) -access(read)-> target(graph=graph1, resource={label: person, city: Beijing})

Configure User Authentication

By default, HugeGraph does not enable user authentication, and it needs to be enabled by modifying the configuration file.

Use StandardAuthenticator for built-in access control, or implement HugeAuthenticator to connect an existing identity system.

HugeGraph uses HTTP Basic Authentication. The value after Basic is the Base64 encoding of username:password. With curl, pass the credentials directly through -u:

1curl -u 'admin:<password>' \
2  http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels

auth.token_secret is read from the authentication graph’s configuration. The default graph is hugegraph, so its file is normally conf/graphs/hugegraph.properties; if auth.graph_store changes, use that graph’s properties file. The core configuration defaults to 32 random bytes encoded as Base64 and does not write that default back to the file. Independently generated defaults cannot remain consistent across restarts or Server nodes. To preserve existing tokens across restarts or validate the same token on multiple nodes, explicitly configure the same strong random secret in each authentication graph configuration.

Server encodes this string as UTF-8 for JJWT’s HS256 signer, which requires at least 32 bytes. This is a byte-length requirement; an arbitrary 32-character string need not have sufficient randomness. The command below generates 32 random bytes and Base64-encodes them locally.

1# Set the same value in every Server node's authentication graph configuration
2auth.token_secret=<locally-generated-secret>

Generate the secret locally and transfer it securely into the authentication graph configuration. Do not commit the actual secret or expose it in public logs:

1openssl rand -base64 32

Token lifetime is controlled by auth.token_expire, defaulting to 86400 seconds.

Both auth.token_expire and auth.token_secret belong to the authentication graph specified by auth.graph_store. Entries with the same names in rest-server.properties do not override that graph configuration.

StandardAuthenticator Mode

StandardAuthenticator stores users and password hashes in the backend and checks access by role. After updating these three configurations, initialize authentication and restart Server.

Set the authenticator and REST configuration path in conf/gremlin-server.yaml.

1authentication: {
2  authenticator: org.apache.hugegraph.auth.StandardAuthenticator,
3  authenticationHandler: org.apache.hugegraph.auth.WsAndHttpBasicAuthHandler,
4  config: {tokens: conf/rest-server.properties}
5}

Set the authenticator and authentication graph in conf/rest-server.properties.

1auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator
2auth.graph_store=hugegraph
3# Used when Server first creates admin; replace public default pa with a strong password in production
4# For local persistent backends, init-store.sh prompts for a password when StandardAuthenticator is first initialized
5#auth.admin_pa=<your-admin-password>
6
7# Auth Client Config
8# If GraphServer and AuthServer are deployed separately, you also need to specify the following configuration. Fill in the IP:RPC port of AuthServer.
9# auth.remote_url=127.0.0.1:8899,127.0.0.1:8898,127.0.0.1:8897

auth.graph_store names the graph that stores authentication data. It must match a graph configuration in conf/graphs/.

Set gremlin.graph in conf/graphs/<graph>.properties for each protected graph.

1gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy

For authorization API usage, see the Authentication API documentation.

Custom User Authentication System

Implement org.apache.hugegraph.auth.HugeAuthenticator and point both authenticator configurations to that implementation to connect an existing identity system.

Switching authentication mode

Use this sequence for a local persistent backend such as RocksDB, after applying the configuration above. HStore/PD deployments create the administrator through the PD startup path. Set auth.admin_pa for that deployment instead of using local interactive initialization.

1. Stop Server.

   1bin/stop-hugegraph.sh

2. Initialize authentication data.

   1bin/init-store.sh

   Enter a strong password when prompted to create admin. Existing graph data is retained. If admin already exists, this command does not reset its password. Keep the existing storage directory.

3. Start Server and check authentication.

   1bin/start-hugegraph.sh
   2curl -u admin \
   3  http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels

   curl prompts for the password. Correct credentials should return HTTP 200; missing or incorrect credentials should return HTTP 401. If startup fails, check the logs and authentication graph configuration before retrying.

Enable authentication with Docker

For a new container, choose either Docker run or Docker Compose. For an existing container, see enabling authentication in existing containers.

When deploying with Docker, the official image supports enabling authentication directly via environment variables (applicable to the official /hugegraph-server layout). Replace the placeholder below with your image tag or digest:

1export HUGEGRAPH_IMAGE='<image:tag-or-digest>'
2read -r -s -p 'Admin password: ' PASSWORD
3printf '\n'
4export PASSWORD

Execute the command and enter a strong administrator password when prompted. Avoid committing plaintext passwords into shared Compose files. Persist the JWT secret in the authentication graph configuration as described above. Use the same value across all nodes.

Docker run

Create a new container and publish its REST port only on the local host.

1docker run -d --name server \
2  -p 127.0.0.1:8080:8080 \
3  -e PASSWORD \
4  "$HUGEGRAPH_IMAGE"
5unset PASSWORD

The entrypoint configures authentication, initializes the backend on first startup, and starts Server. Continue with checking authentication.

Docker Compose

Save the following as compose.yaml. Compose rejects missing required variables to avoid starting an unauthenticated service by accident. Start the service in the same terminal.

1services:
2  server:
3    image: ${HUGEGRAPH_IMAGE:?Set HUGEGRAPH_IMAGE}
4    container_name: server
5    ports:
6      - "127.0.0.1:8080:8080"
7    environment:
8      PASSWORD: ${PASSWORD:?Set PASSWORD}

1docker compose up -d
2unset PASSWORD

Set these variables again before recreating the container. Retain its data volumes and persist the configuration required by your deployment. Continue with checking authentication.

Existing containers

Use this path for an official Server container that ran without authentication and uses a local persistent backend. Back up its data first. Confirm that the configuration, backend data, and conf-bak are all in mounted persistent volumes. The official image declares /hugegraph-server as a volume; inspect the mounts of custom images first. HStore/PD and external authentication services use their own administrator initialization paths.

1. Stop the original container and open a maintenance container with the same image and volumes.

   1SERVER_IMAGE=$(docker inspect --format '{{.Image}}' server)
   2docker stop server
   3docker run --rm -it --volumes-from server \
   4  --entrypoint bash "$SERVER_IMAGE"

   Keep the original container stopped so two JVMs do not open the local database at once. --entrypoint bash opens a shell without starting Server.

2. Configure authentication and initialize it inside the maintenance container.

   1cd /hugegraph-server
   2bin/enable-auth.sh

   On its first run, enable-auth.sh saves the original configuration in conf-bak and updates authentication and the default hugegraph graph. If conf-bak already exists, the script skips its changes. Check all three configurations under StandardAuthenticator mode. Configure other authentication graphs manually. Write a strong random JWT secret to the authentication graph configuration as described above, then initialize it.

   1bin/init-store.sh
   2exit

   Enter the administrator password when prompted, then exit after initialization succeeds.

3. Start the original container from the host.

   1docker start server

   Retain the docker/init_complete marker. Later changes to the PASSWORD environment variable do not change the stored administrator password.

Check authentication

Once Server is running, execute the following requests from the host to verify. -u admin prompts interactively for the password:

1curl -sS -o /dev/null -w '%{http_code}\n' \
2  http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels
3curl -sS -o /dev/null -w '%{http_code}\n' -u admin \
4  http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels

Requests without credentials should return 401 Unauthorized, while requests with the correct password return 200 OK (incorrect passwords also return 401). Note: Current master URLs include /graphspaces/DEFAULT; for 1.7.0 and older versions, omit the graphspace prefix (use /graphs/hugegraph/... directly). If unauthenticated requests still return 200, authentication is not active; inspect configuration and restart Server.