Skip to content

Role-Based Access Control (RBAC)

PuppyGraph supports role-based access control (RBAC) to restrict what each user can do. This page explains the built-in roles, how to manage users through the UI, and how to configure SSO group mappings.

Roles

PuppyGraph has five built-in roles:

Role Intended for What they can do
Admin PuppyGraph administrators Everything: full access to all features including user management, graph schema, catalogs, queries, cluster, and system operations
UserAdmin Team leads, security officers Manage users and roles; read-only access to graphs, catalogs, and queries. Cannot modify graphs, catalogs, or cluster infrastructure
GraphAdmin Data engineers Build and maintain graph schemas; run queries; read catalog metadata. Cannot create or delete catalogs, and cannot manage users
Analyst Data analysts, application developers Run queries; read graph schemas and catalog metadata
Viewer Stakeholders, reviewers Read graph schemas and catalog metadata. Cannot run queries

Permission Matrix

Permission Admin UserAdmin GraphAdmin Analyst Viewer
View graph schema ✓ ✓ ✓ ✓ ✓
Modify graph schema ✓ ✓
View catalogs ✓ ✓ ✓ ✓ ✓
Create/delete catalogs ✓
Run queries ✓ ✓ ✓ ✓
View data and cache ✓ ✓ ✓ ✓
Manage data and cache ✓ ✓
View cluster status ✓ ✓ ✓
Manage cluster nodes ✓
System administration ✓
View users and audit log ✓ ✓
Manage users and roles ✓ ✓
Assign Admin/UserAdmin roles ✓

Note

UserAdmin and GraphAdmin are peers; neither is a superset of the other. Only Admin can assign the Admin or UserAdmin roles to other users.

Schema uploads with embedded catalogs

If a schema file includes a catalog section, uploading it requires CATALOG:write permission (Admin only). Users with the GraphAdmin role must remove the catalog section from their schema file and have an admin register the catalogs separately via Catalogs in the left sidebar.

Managing Users

RBAC settings are in Settings (gear icon in the left sidebar). The management tabs (Users, Service Accounts, SSO Configuration, and Audit Log) are only visible to users with the Admin or UserAdmin role.

Creating a Local User

Local users authenticate with a username and password managed by PuppyGraph.

  1. Go to Settings → Users
  2. Click Create User
  3. Enter a username and select a role (defaults to Analyst)
  4. Click Create. A generated password appears; copy it now, because it is shown only once and cannot be retrieved later.
  5. Share the username and password with the new user.

Note

Only Admin can assign the Admin or UserAdmin roles when creating a user.

Changing a User's Role

  1. Go to Settings → Users
  2. Find the user in the table
  3. Use the Role dropdown in their row to select a new role

The role change takes effect the next time the user logs in.

Resetting a User's Password

For local users who have forgotten their password:

  1. Go to Settings → Users
  2. Find the user and click the Password button
  3. Confirm the reset. A new generated password is shown once. Share it with the user.

Deleting a User

  1. Go to Settings → Users
  2. Find the user and click the Delete button
  3. Confirm the deletion

Note

The bootstrap admin (puppygraph by default) cannot be deleted or have its role changed.

Changing Your Own Password

Local users can change their own password from the Preferences tab:

  1. Go to Settings → Preferences
  2. Scroll to the Password section
  3. Click Change Password
  4. Enter your current password and new password (minimum 8 characters)

SSO Users

When SSO is enabled, users who authenticate through your identity provider (IdP) are created automatically on first login. For how to wire PuppyGraph up to your IdP, see OAuth / OIDC Single Sign-On. The role for each SSO user is determined in this order:

  1. Explicit assignment. If an admin has assigned a role via the Users tab, it takes precedence and is not re-evaluated on future logins.
  2. Group mapping. If the user's IdP groups match a configured mapping (see below), the matching role is assigned.
  3. Default role. Falls back to the RBAC_DEFAULT_ROLE environment variable (default: Analyst).

Configuring SSO Group Mappings

Group mappings automatically assign roles to SSO users based on their IdP group membership, eliminating the need to manually assign roles to each user.

To add a group mapping:

  1. Go to Settings → SSO Configuration.
  2. Click Add Group Mapping.
  3. Fill in:
  4. SSO Group Name. Must match exactly how the group appears in your IdP's token claim.
  5. Role. The PuppyGraph role to assign to members of this group.
  6. Priority. Lower number = higher precedence, used when a user belongs to multiple mapped groups.
  7. Click Add.

For example: if a user belongs to both data-engineering (mapped to GraphAdmin, priority 10) and all-employees (mapped to Viewer, priority 100), they get GraphAdmin because 10 < 100.

To edit a mapping, click the edit icon on any row. You can change the Role and Priority, but not the Group Name. To delete a mapping, click the delete icon on the row.

Tip

Set SSO_GROUPS_CLAIM to the name of the claim your IdP uses for group memberships (default: groups).

Service Accounts

Service accounts provide programmatic access for scripts, pipelines, and applications. They authenticate using a name and secret instead of a password.

Creating a Service Account

  1. Go to Settings → Service Accounts.
  2. Click Create Service Account.
  3. Fill in:
  4. Name. Alphanumeric, hyphens, and underscores only; no colons.
  5. Role. The role this service account will have.
  6. Description. Optional, for identification.
  7. Allow user impersonation. Enables acting as a specific user (see Impersonation).
  8. Click Create. A secret is shown; copy it now, because it is shown only once.

Using a service account:

# REST API
curl -u 'etl-pipeline:<secret>' http://localhost:8081/schemajson

# Gremlin (WebSocket): use full sa: prefix
username: sa:etl-pipeline
password: <secret>

# Bolt (Neo4j driver): use full sa: prefix
auth=('sa:etl-pipeline', '<secret>')

Managing Service Accounts

From Settings → Service Accounts:

  • Change role: use the Role dropdown in the service account's row.
  • Toggle impersonation: use the switch in the Impersonation column.
  • Rotate secret: click the refresh icon, then confirm to generate a new secret (shown once; old secret is immediately invalidated).
  • Delete: click the delete icon.

The Last Used column shows when the service account last authenticated.

Impersonation

A service account with impersonation enabled can act as a specific user, inheriting that user's role and permissions. This is useful for multi-tenant applications where a single service account serves many users.

Constraints:

  • The service account must have Allow user impersonation enabled.
  • The target user's role must be equal to or lower than the service account's role (prevents privilege escalation).
  • Impersonation is recorded in the audit log with both identities.

Using impersonation:

# Bolt (Neo4j Python driver)
with driver.session(impersonated_user='sso:alice@example.com') as session:
    result = session.run('MATCH (n) RETURN n LIMIT 10')

# Gremlin (WebSocket): fixed per connection
c = client.Client(
    'ws://puppygraph-host:8182/gremlin', 'g',
    username='sa:dashboard-app', password='<secret>',
    headers={'X-PuppyGraph-Assume-User': 'sso:alice@example.com'}
)

# REST API
curl -u 'dashboard-app:<secret>' \
     -H 'X-PuppyGraph-Assume-User: sso:alice@example.com' \
     http://localhost:8081/submitCypher -d '{"query": "MATCH (n) RETURN n"}'

Audit Log

The audit log records all RBAC-related actions.

  1. Go to Settings → Audit Log
  2. The table shows Timestamp, Actor (who performed the action), Action, and Target user
  3. Click the expand icon on any row to see the full detail (e.g., role before and after a change)
  4. Click Load More to fetch older entries

Recorded actions include: user creation, role changes, password resets, service account operations, group mapping changes, and access denials.

Configuration

Environment Variable Default Description
RBAC_ENABLED true Set to false to disable RBAC (all authenticated users treated as Admin)
RBAC_DEFAULT_ROLE Analyst Default role for new SSO users who don't match any group mapping
PUPPYGRAPH_USERNAME puppygraph Bootstrap admin username. Always Admin; cannot be changed via API
PUPPYGRAPH_PASSWORD puppygraph123 Bootstrap admin password. For production deployments, set this to a strong secret and rotate it periodically; do not rely on the default value.
SSO_GROUPS_CLAIM groups Name of the IdP token claim that contains the user's group memberships