Skip to main content
Loading
Version: Graph 2.2.0

RBAC for Aerospike Graph Service

Overviewโ€‹

This page describes how to set up Role Based Access Control (RBAC) for the Aerospike Graph Service (AGS) using Java Web Tokens (JWTs).

We recommend using RBAC on a secure network connection between client applications and AGS.

Enable RBACโ€‹

Enable RBAC for your AGS instance with the following configuration options:

OptionRequired?Value
aerospike.graph-service.auth.jwt.secretyesAny string that you choose.
aerospike.graph-service.auth.jwt.issueryesYour organization or a third-party authentication service.
aerospike.graph-service.auth.jwt.algorithmnoOne of: HMAC256, HMAC384, HMAC512. Default is HMAC256.
note

For a complete list, see Configuration options.

After RBAC security is enabled, all connections with AGS must carry a Java Web Token (JWT) with the correct secret and issuer, and all users must have sufficient privileges to run their queries.

Authentication detailsโ€‹

Rolesโ€‹

Role access levels in AGS include:

READโ€‹

Can read data. No write or admin privileges.

The following commands are blocked for READ users:

Blocked Gremlin steps
addV
addE
drop
mergeE
mergeV
property
Blocked call steps
aerospike.graph.admin.rbac-jwt.issue-token
aerospike.graph.admin.index.drop
aerospike.graph.admin.index.create
aerospike.graphloader.admin.bulk-load.* (all bulk-load steps are blocked)

READ_WRITEโ€‹

Can read data and perform write operations (addV(), addE(), property(), etc.)

All Gremlin steps are available to READ_WRITE users. The following commands are blocked:

Blocked call steps
aerospike.graph.admin.rbac-jwt.issue-token
aerospike.graph.admin.index.drop
aerospike.graph.admin.index.create

ADMINโ€‹

Can perform read and write operations, plus create and delete indexes. No Gremlin steps or call steps are blocked.

Create JWTsโ€‹

Use the following procedure to create JWTs for use with graph authentication.

  1. Create the ADMIN JWT

An admin user first creates a token with admin-level privileges. The first admin token must be created using an external token authority.

jwt.io provides a free utility for generating JWTs.

  • Select an algorithm from the dropdown menu. Valid algorithms for use with AGS are:

    • 'HS256' (corresponds to 'HMAC256')
    • 'HS384' (corresponds to 'HMAC384')
    • 'HS512' (corresponds to 'HMAC512')

    The HEADER field auto-populates based on your choice.

  • Fill in the PAYLOAD field with the following, edited to suit your needs:

    {
    "iss": "jwt.io",
    "iat": 1717107890,
    "exp": 14210121600,
    "aud": "",
    "sub": "admin",
    "role": "ADMIN"
    }
  • Add your secret to the VERIFY SIGNATURE field, and the encoded token on the left side is ready to use.

The following diagram shows the procedure for creating a token with an external token issuer:

Creating JWT with an external token issuer

  1. Create subsequent JWTs using admin token

The admin user can create tokens for other users, including admin tokens. Other users can use their tokens for graph queries, and the issuer and secret credentials are not required with the application code.

The following diagram shows the procedure for creating a token with the AGS aerospike.graph.admin.rbac-jwt.issue-token command:

Creating JWT with AGS

  1. The admin user can create tokens with the Gremlin call step aerospike.graph.admin.rbac-jwt.issue-token. Provide the new token's username and intended role as parameters:
g.call("aerospike.graph.admin.rbac-jwt.issue-token")
.with("username", "<USERNAME>")
.with("role", "<ROLE>")
.next()

Connect to AGS using a JWTโ€‹

The following diagram shows the procedure for connecting to AGS with a JWT:

Connecting to AGS with a JWT

Using a JWT over a Gremlin server connectionโ€‹

The following Java code example demonstrates a Gremlin server login with a JWT:

final Cluster cluster = Cluster.build()
.addContactPoint("localhost").port(8182)
.credentials(<USERNAME>, <TOKEN>)
.create();

Using a JWT over an HTTP connectionโ€‹

To authenticate an HTTP connection with a JWT, set the Authorization property to Bearer <JWT>, where <JWT> is a base64 encoded string of a JWT.

The following Java code example demonstrates setting up an HTTP connection with a JWT:

    public String adminIndexListHeaders(final String userCredentials) {
try {
final URL url = new URL("http://localhost:9090/admin/index/list");
final HttpURLConnection con = (HttpURLConnection) url.openConnection();

// Send request to the server and read reply
final String token = "Bearer " + new String(Base64.getEncoder().encode(userCredentials.getBytes()));

// Send request to the server and read reply
con.setRequestMethod("GET");
con.setRequestProperty("Authorization", token);

// Read input stream into String
final byte[] bytes = con.getInputStream().readAllBytes();
final String response = new String(bytes);
return response;
} catch (final Exception e) {
throw new RuntimeException(e);
}
}