Graph Modeling OAuth2 Authentication Integration with GraphDB

09/04/2026

This guide outlines the procedure for implementing OAuth2 authentication between Graph Modeling (GM) and GraphDB using Keycloak as the Identity Provider (IdP).

Note

Please note that this topic is targeted primarily at existing Graph Modeling customers if they want to use this new functionality respectively if they do not use Keycloak. New Graph Modeling customers will be provided a preconfigured Keycloak realm supporting this functionality.

1. Keycloak Configuration (Identity Provider)

Before configuring the applications the Keycloak realm (typically poolparty) must be prepared with the appropriate client scopes and client definitions. This configuration is comprised of four phases:

Creating a Client Scope & Audience Mapping
Configuring the GraphDB Client
Configuring the Application Client
Assigning User Permission

Navigate to Client Scopes → Create client scope.
- Name: aud-graphdb
- Type: Default
- Display on consent screen: Off
Save the scope, then navigate to the Mappers tab for this scope.
Select Configure a new mapper → Audience.
- Name: aud-graphdb
- Included Client Audience: graphdb
  Note
  If this is performed before the graphdb client has been created in Phase B, then this client will not appear in the dropdown and will have to be added manually.
- Add to ID token: Off
- Add to access token: On
- Add to token introspection: On
Save the mapper.

It is necessary to define a new Keyclock client representing the GraphDB server. The client name specified in this procedure must be used across different configurations in Keycloak, Graph Modeling. In this guide we use the client called graphdb.

Navigate to Clients → Create Client.
Note
The ID specified here must match the one defined in aud-graphdb. It also has to be the same as used in the Phase C item 5 and in Phase D.
- Client ID:graphdb (or your preferred ID).
On the Settings tab apply the following:
- Root URL: http://<gdb_address>:7200/
- Home URL: http://<gdb_address>:7200/
- Valid redirect URIs: http://<gdb_address>:7200/*
- Web origins: http://<gdb_address>:7200
- Client authentication: Disabled
- Standard flow: Enabled
- Direct access grants: Enabled
Navigate to the Client Scopes tab of the graphdb client:
- Click Add client scope, select aud-graphdb, and set it to Default.
- Ensure offline_access is also added (required for GraphDB Workbench login).
Navigate to Roles and create ROLE_REPO_MANAGER. (Add any required additional granular roles as described in the GraphDB documentation). Also create ROLE_USER. Other role examples would be READ_REPO_* which gives read access to all repositories, WRITE_REPO_* which grants read and write access to all repositories, or WRITE_REPO_pp_project_<projectId> where user is granted read and write access to the repository of a specific project.
Tip
The user role ROLE_REPO_ MANAGER grants the user full administrator rights for the repositories whereas the role READ_REPO_* grants the user permissions to log in and query the repositories.

You can create groups granting a user access to GraphDB when a user is a member of such.

You will need two groups - one with management rights and other for general use case.

A group with management access

Create a group with the name GraphDB_Managers
Open the newly created group and go to Attributes.
Add the attribute visible with the value false to hide this group from the Graph Modeling.
Then go to Role Mapping and add:
1. Filter by client → graphdb: ROLE_REPO_MANAGER
2. Filter by realm → offline_access. This is an optional step.
  If not specified then the user has to be a member in both groups GraphDB_Managers and GraphDB_WorkbenchUsers in order to have manager access as well as be able to login to GraphDB.

A group with general use access

Create group called GraphDB_WorkbenchUsers.
Open the newly created group and go to Attributes.
Add the attribute visible with the value false to hide this group from the Graph Modeling.
Then go to Role Mapping and add:
1. Filter by client → graphdb: ROLE_USER
2. Filter by realm → offline_access

Add the user superadmin to the group GraphDB_Managers

Open the GraphDB_Managers group.
Navigate to Members.
Add the superadmin user to the group.

You can assign GraphDB access via individual users or groups:

Per User: Go to Users → [Select User] → Role mapping → Assign role → Filter by client graphdb → Assign ROLE_USER.
Per Group: Go to Groups → Create group (e.g., GraphDB_Admins) → Role mapping → Assign role → Filter by client graphdb → Assign ROLE_REPO_MANAGER.

Note

Only assign the user role ROLE_REPO_MANAGER to a user if they are to be granted full administrator permissions to the specified repositories. If the user is only supposed to be able to log in and query the repositories, the role READ_RRPO_* is sufficient.

2. Graph Modeling (GM) Application Configuration

To activate OAuth2 update the application configuration file. The property poolparty.graphdb.oauth.clientId is the minimum requirement to toggle this feature.

Configuration Key	Description	Default Value	Required
`poolparty.graphdb.oauth.clientId`	The GraphDB OAuth2 client ID defined in Keycloak.		Yes
`poolparty.graphdb.oauth.method`	Authentication method. Allowed values: `client_secret_basic`, `client_secret_post`.	`client_secret_basic`	No
`poolparty.graphdb.oauth.scopes`	Comma-separated list of OIDC scopes.	`openid,profile,roles`	No

3. GraphDB Database Configuration

The following properties must be set within GraphDB to enable OpenID Connect and OAuth2 authentication.

Configuration Key	Value	Notes
`graphdb.auth.methods`	`openid`	Enables OpenID Connect authentication.
`graphdb.auth.database`	`oauth`	Specifies the authentication database.
`graphdb.auth.openid.issuer`	`http://<host>:<port>/auth/realms/poolparty`	Uses your specific Keycloak realm URL.
Important This realm has to match the actual realm configured in Graph Modeling under `poolparty.keycloak.login.realm`; The default value is `poolparty` .
`graphdb.auth.openid.client_id`	`graphdb`	Must match the Keycloak Client ID.
`graphdb.auth.openid.token_type`	`access`	Specifies token type for authentication.
`graphdb.auth.openid.username_claim`	`preferred_username`	Claim used to identify the user.
`graphdb.auth.openid.auth_flow`	`code`	Specifies the OAuth2 Authorization Code flow.
`graphdb.auth.openid.token_audience`	`graphdb`	Must match `poolparty.graphdb.oauth.clientId`.
`graphdb.auth.openid.require_audience`	`true`	Enforces audience claim validation.
`graphdb.auth.oauth.roles_claim`	`resource_access.graphdb.roles`	Path to roles; `graphdb` must match Client ID.
`graphdb.auth.oauth.default_roles`	`ROLE_USER`	Fallback role if no claims are found.

Tip

For more details on the configuration also refer to the following section.

In this section:

Graph Modeling OAuth2 Authentication Integration with GraphDB

Note

1. Keycloak Configuration (Identity Provider)

Note

Note

Tip

Tip

Note

2. Graph Modeling (GM) Application Configuration

3. GraphDB Database Configuration

Important

Tip