We’re overhauling Dgraph’s docs to make them clearer and more approachable. If
you notice any issues during this transition or have suggestions, please
let us know.
This feature was introduced in
v1.1.0. The
dgraph acl
command is deprecated and will be removed in a future release.
ACL changes can be made by using the /admin
GraphQL endpoint on any Alpha
node.Enable enterprise ACL feature
-
Generate a data encryption key that is 32 bytes long:
On a macOS you may have to use
LC_CTYPE=C; tr -dc 'a-zA-Z0-9' < /dev/urandom | dd bs=1 count=32 of=enc_key_file
. -
To view the secret key value use
cat enc_key_file
. -
Create a plain text file named
hmac_secret_file
, and store a randomly generated<SECRET KEY VALUE>
in it. The secret key is used by Dgraph Alpha nodes to sign JSON Web Tokens (JWT). -
Start all the Dgraph Alpha nodes in your cluster with the option
--acl secret-file="/path/to/secret"
, and make sure that they use the same secret key file created in Step 1. Alternatively, you can store the secret in HashiCorp Vault.
In addition to command line flags
--acl secret-file="/path/to/secret"
and
--security "whitelist=<permitted-ip-addresses>"
, you can also configure Dgraph
using a configuration file (config.yaml
, config.json
). You can also use
environment variables such as DGRAPH_ALPHA_ACL="secret-file=</path/to/secret>"
and DGRAPH_ALPHA_SECURITY="whitelist=<permitted-ip-addresses>"
. See
Config for more information in general about configuring
Dgraph.Example using Dgraph CLI
Here is an example that starts a Dgraph Zero node and a Dgraph Alpha node with the ACL feature turned on. You can run these commands in a separate terminal tab:Example using Docker Compose
If you are using Docker Compose, you can set up a sample Dgraph cluster using thisdocker-compose.yaml
configuration:
Example using Kubernetes Helm Chart
If you deploy Dgraph on Kubernetes, you can configure the ACL feature using the Dgraph Helm Chart. The first step is to encode the secret with base64:dgraph_values.yaml
. We want to copy the results of encoded
secret as paste this into the hmac_secret_file
like the example below:
Storing ACL secret in HashiCorp Vault
You can save the ACL secret on HashiCorp Vault server instead of saving the secret on the local file system.Configuring a HashiCorp Vault server
Do the following to set up on the HashiCorp Vault server for use with Dgraph:-
Ensure that the Vault server is accessible from Dgraph Alpha and configured
using URL
http://fqdn[ip]:port
. - Enable AppRole Auth method and enable KV Secrets Engine.
-
Save the 256-bits (32 ASCII characters) long ACL secret in a KV Secret path
(K/V Version 1 or
K/V Version 2). For
example, you can upload this below to KV Secrets Engine Version 2 path of
secret/data/dgraph/alpha
: -
Create or use a role with an attached policy that grants access to the
secret. For example, the following policy would grant access to
secret/data/dgraph/alpha
: -
Using the
role_id
generated from the previous step, create a correspondingsecret_id
, and copy therole_id
andsecret_id
over to local files, like./dgraph/vault/role_id
and./dgraph/vault/secret_id
, that will be used by Dgraph Alpha nodes.
The key format for the
acl-field
option can be defined using acl-format
with the values base64
(default) or raw
.Example using Dgraph CLI with HashiCorp Vault configuration
Here is an example of using Dgraph with a Vault server that holds the secret key:Example using Docker Compose with HashiCorp Vault configuration
If you are using Docker Compose, you can set up a sample Dgraph cluster using thisdocker-compose.yaml
configuration:
vault
in the
above docker-compose.yaml
, and then run through this sequence:
- Launch
vault
service:docker-compose up --detach vault
- Unseal and Configure
vault
with the required prerequisites (see Configuring a HashiCorp Vault Server). - Save role-id and secret-id as
./role_id
andsecret_id
- Launch Dgraph Zero and Alpha:
docker-compose up --detach
Example using Kubernetes Helm Chart with HashiCorp Vault configuration
If you deploy Dgraph on Kubernetes, you can configure the ACL feature using the Dgraph Helm Chart. The next step is that we need to create a Helm chart config values file, such asdgraph_values.yaml
.
Accessing secured Dgraph
Before managing users and groups and configuring ACL rules, you will need to login in order to get a token that is needed to access Dgraph. You will use this token with theX-Dgraph-AccessToken
header field.
Logging In
To login, send a POST request to/admin
with the GraphQL mutation. For
example, to log in as the root user groot
:
Access Token
The response includes the access and refresh JWTs which are used for the authentication itself and refreshing the authentication token, respectively. Save the JWTs from the response for later HTTP requests. You can run authenticated requests by passing the access JWT to a request via theX-Dgraph-AccessToken
header. Add the header X-Dgraph-AccessToken
with
the accessJWT
value which you got in the login response in the GraphQL tool
which you’re using to make the request.
For example, if you were using the GraphQL Playground, you would add this in the
headers section:
Refresh Token
The refresh token can be used in the/admin
POST GraphQL mutation to receive
new access and refresh JWTs, which is useful to renew the authenticated session
once the ACL access TTL expires (controlled by Dgraph Alpha’s flag
--acl_access_ttl
which is set to 6h0m0s by default).
Login using a client
With ACL configured, you need to log in as a user to access data protected by ACL rules. You can do this using the client’s.login(USER_ID, USER_PASSWORD)
method.
Here are some code samples using a client:
- Go (dgo client): example
acl_over_tls_test.go
(here) - Java (dgraph4j): example
AclTest.java
(here)
Login using curl
If you are usingcurl
from the command line, you can use the following with
the above login mutation saved to login.graphql
:
Parsing JSON results on the command line can be challenging, so you will find
some alternatives to extract the desired data using popular tools, such as
the silver searcher or the
JSON query tool jq, embedded in this snippet.
User and group administration
The default configuration comes with a usergroot
, with a password of
password
. The groot
user is part of administrative group called guardians
that have access to everything. You can add more users to the guardians
group
as needed.
Reset the root password
You can reset the root password like this example:Create a regular user
To create a useralice
, with password whiterabbit
, you should execute the
following GraphQL mutation:
Create a group
To create a groupdev
, you should execute:
Assign a user to a group
To assign the useralice
to both the group dev
and the group sre
, the
mutation should be
Remove a user from a group
To removealice
from the dev
group, the mutation should be
Delete a User
To delete the useralice
, you should execute
Delete a Group
To delete the groupsre
, the mutation should be
ACL rules configuration
You can set up ACL rules using the Dgraph Ratel UI or by using a GraphQL tool, such as Insomnia, GraphQL Playground, GraphiQL, etc. You can set the permissions on a predicate for the group using a pattern similar to the UNIX file permission conventions shown below:Permission | Value | Binary |
---|---|---|
READ | 4 | 100 |
WRITE | 2 | 010 |
MODIFY | 1 | 001 |
READ + WRITE | 6 | 110 |
READ + WRITE + MODIFY | 7 | 111 |
READ
- group has permission to read read the predicateWRITE
- group has permission to write or update the predicateMODIFY
- group has permission to change the predicate’s schema
dev
. If there are no rules for a predicate, the default behavior is to block
all (READ
, WRITE
and MODIFY
) operations.
Assign predicate permissions to a group
Here we assign a permission rule for thefriend
predicate to the group:
dgraph.all
keyword.
The following example provides read+write
access to the dev
group over all
the predicates of a given namespace using the dgraph.all
keyword.
The permissions assigned to a group
dev
is the union of permissions from
dgraph.all
and permissions for a specific predicate name
. So if the group
is assigned READ
permission for dgraph.all
and WRITE
permission for
predicate name
it will have both, READ
and WRITE
permissions for the
name
predicate, as a result of the union.Remove a rule from a group
To remove a rule or rules from the groupdev
, the mutation should be:
Querying users and groups
You can set up ACL rules using the Dgraph Ratel UI or by using a GraphQL tool, such as Insomnia, GraphQL Playground, GraphiQL, etc. The permissions can be set on a predicate for the group using using pattern similar to the UNIX file permission convention: You can query and get information for users and groups. These sections show output that will show the useralice
and the dev
group along with rules for
friend
and ~friend
predicates.
Query for users
Let’s query for the useralice
:
Get user information
We can obtain information about a user with the following query:Query for groups
Let’s query for thedev
group:
Get group information
To check thedev
group information:
Reset Groot password
If you have forgotten the password to thegroot
user, then you may reset the
groot
password (or the password for any user) by following these steps.
- Stop Dgraph Alpha.
-
Turn off ACLs by removing the
--acl_hmac_secret
config flag in the Alpha config. This leaves the Alpha open with no ACL rules, so be sure to restrict access, including stopping request traffic to this Alpha. - Start Dgraph Alpha.
-
Connect to Dgraph Alpha using Ratel and run the following upsert mutation to
update the
groot
password tonewpassword
(choose your own secure password): -
Restart Dgraph Alpha with ACLs turned on by setting the
--acl_hmac_secret
config flag. - Login as groot with your new password.