Custom Keycloak Client

30/09/2026

GraphRAG 1.3

GraphRAG requires access to multiple Graph Modelling components' APIs using a single OAuth2 credential. Currently this includes the thesaurus and extractor, with more components likely to be added in future. For security reasons, none of the default Keycloak clients grants the combined access that GraphRAG requires. You must therefore create a dedicated Keycloak client graphrag on the Graph Modelling Keycloak server. Whilst future releases are expected to automatically provision this client during deployment, it must currently be configured manually.

A custom client graphrag has to be set up in the Keycloak instance connected to the Graph Modeling server to enable authenticated and authorized OAuth-based service-to-service and machine-to-machine communications between GraphRAG and Graph Modeling.

Log in to the Keycloak instance connected to the Graph Modeling server with KC administrator credentials.
Select the realm poolparty (1) from the drop-down list.
In the left navigation area select Clients (2) and on the Client list (3) tab click Create client (4).
Enter the following on the General settings (1) page:
- graphrag as the Client ID (2)
- GraphRAG as the Name (3)
- Then either click Next or Capability config to proceed to the next page.
Configure the following settings on the Capability config (1) page:
- Set Client authentication to On (2)
- Set Authorization to Off (3)
- Tick the following checkboxes (4) in the Authentication flow section :
  - Standard flow
  - Direct access grants
  - Service account roles.
- Click on Next (5) to proceed to the Login settings.
Specify the following on the Login settings page (1) :
- Valid redirect URIs (2)
- Valid post logout redirect URIs (3)
- Web origins (4).
- Confirm the settings of the new client with a click on Save (5).
Note
Please note that these three values are sever setup-specific.
Go to the Credentials tab (1) of the new client and click the double-page icon (2) to copy the Client Secret which you will need later during the configuration of the n8n credentials.
Navigate to the Service accounts roles (1) of the service-account-graphrag (2) and click Assign role (3).
Assign the ApiAdmin role to your client. Use Filter by realm roles to display it. Due to the required ONTOLOGIES_READ permissions this role is the lowest usable one.
Click on service-account-graphrag (2) and then navigate to the Groups tab. There click Join Group which opens a pop-up window where you can select the relevant Graph Modeling groups to access the project configured in GraphRAG. To join a group set the tick in the leading checkbox and when ready click the Join button to confirm.
Navigate to Clients (1) to display the Clients list tab and select graphrag from the list of available clients.
Then navigate to the Client scopes tab (2) and click graphrag-dedicated (3).
The Mappers tab (2) opens.
Click Add mapper drop-down and select By configuration (3).
The Configure a new mapper (1) pop-up opens where you have to click Group Membership (2).
Selecting Group Membership opens the following Add mapper page.
Enter the following configuration details for the Mapper type (1):
- Enter groups in the Name (2) field.
- In the Token Claim Name (3) field enter groups .
- Set Add to ID token (4) to Off.
- Keep the default values for the other settings.
- Click Save (5) to confirm and complete the graphrag client configuration. Clicking Cancel will abort this operation.
:

In this section:

Custom Keycloak Client

Note