Collaborate With Team

Each ApertureDB instance has database users and roles. Roles define permissions; users receive the permissions of their assigned roles. The ApertureDB Web UI and API both manage access to an existing instance.

note

Database users and roles are independent of Cloud user accounts. Each database instance maintains its own access-control configuration, regardless of where it is deployed.

The Web UI's ACCESS CONTROL tab creates users and manages their roles.

png

Add New Roles

A role specifies the actions its users can perform. Multiple users can share a role, so permissions can be managed without defining them separately for every account.

png

The access-control JSON commands also create and manage roles in a database instance.

Add New Users

Separate user accounts let team members access shared data with the permissions assigned to each account. The Web UI creates users and assigns their roles.

png

The access-control JSON commands provide the same operations for scripts that configure users across multiple instances.

Manage a reader account through the API

A reader account needs a role with object-read permission. The procedure below creates that role and its user, checks access, assigns a personal token, and removes the account when finished. Use a separate database or unused account and role names. The administrator needs access-control create, read, update, and delete permissions. Install the Python SDK and set APERTUREDB_HOST, APERTUREDB_USER, and APERTUREDB_PASSWORD for that administrator; optionally set APERTUREDB_PORT. The connection below uses TLS. See client configuration for certificates and local evaluation connection settings.

import os
from getpass import getpass
from aperturedb import Connector

host = os.environ["APERTUREDB_HOST"]
port = int(os.environ.get("APERTUREDB_PORT", "55555"))
admin = Connector.Connector(host, port, user=os.environ["APERTUREDB_USER"],
                            password=os.environ["APERTUREDB_PASSWORD"])
username = "documentation_reader"
role_name = "documentation_reader_role"
password = getpass("New reader password (10+ characters, letters, digits, symbols): ")

def run(connection, commands):
    response, blobs = connection.query(commands)
    if not isinstance(response, list):
        raise RuntimeError(response)
    for command in response:
        for result in command.values():
            if not isinstance(result, dict) or result.get("status") != 0:
                raise RuntimeError(response)
    return response, blobs

run(admin, [{"CreateRole": {"name": role_name, "objects": {"read": True}}}])
run(admin, [{"CreateUser": {"username": username, "password": password,
                            "roles": [role_name]}}])

Omitted permissions default to false. These are separate requests because role and user changes happen during response processing. If a name already exists, inspect it with GetRoles or GetUserDetails and choose a new name; do not remove an existing account to make the example run.

GetUserDetails reports the account's effective permissions. A successful FindEntity request from the new account confirms read access; the count can be zero when the database is empty.

response, _ = run(admin, [{"GetUserDetails": {"username": username}}])
permissions = response[0]["GetUserDetails"]["permissions"]
assert permissions["objects"]["read"] is True
assert permissions["objects"]["create"] is False
assert permissions["access_control"]["create"] is False

reader = Connector.Connector(host, port, user=username, password=password)
run(reader, [{"FindEntity": {"results": {"count": True}}}])
reader.close()

Generate a personal token and assign it to the account. Generation alone does not authorize the token. Store it in your application's secret store without printing it or saving it in a notebook output.

response, _ = run(admin, [{"GenerateToken": {}}])
personal_token = response[0]["GenerateToken"]["token"]
run(admin, [{"UpdateUser": {"username": username, "add_tokens": [personal_token]}}])

token_reader = Connector.Connector(host, port, user=username, token=personal_token)
run(token_reader, [{"FindEntity": {"results": {"count": True}}}])
token_reader.close()

adbp_ identifies a personal token; adbs_ and adbr_ identify session and refresh tokens. The connector manages session refresh. GetUserDetails can show token tags, rather than full token values, to the account owner or a user with access-control read permission.

Removing a personal token prevents it from authenticating a new connection. An already established session does not demonstrate whether revocation has taken effect. Revoke unused tokens and check that a new connection using the revoked token fails to authenticate.

run(admin, [{"UpdateUser": {"username": username, "remove_tokens": [personal_token]}}])
del personal_token

# Remove only the account and role created for this exercise, in this order.
run(admin, [{"RemoveUser": {"username": username}}])
run(admin, [{"RemoveRole": {"name": role_name}}])
admin.close()

If a response or connection fails during an administrative change, inspect the account or role before retrying: the change may already have happened. The response reference describes these failure phases. CreateRole and UpdateUser define the fields used in this procedure.

Add New Roles​

Add New Users​

Manage a reader account through the API​

Add New Roles

Add New Users

Manage a reader account through the API