Connecting Keycloak to the WoodWing Identity Service

Keycloak is an Identity and Access Management (IAM) solution which can be connected to the WoodWing Identity Service (WIS). The recommended way of doing this is by using the OIDC protocol.

How this is done is explained in this article.

The process is as follows:

1. Steps in the WoodWing Identity Service
2. Steps in Keycloak
3. Steps in the WoodWing Identity Service
4. Testing the integration

1. Steps in the WoodWing Identity Service

In this step, a URL from the WoodWing Identity Service is copied for later use in the Keycloak configuration.

Step 1. Log in to the WoodWing Identity Service as a user that is part of a group with the role of 'owner'.

Step 2. Access the Settings page.

A page appears with information about the organization, including any identity provider that is set up.

Step 3. Under Identity provider, click Set up or edit.

A panel appears in which the identity provider can be configured.

Step 4. Select the OIDC tab.

Step 5. At the top of the tab, copy the redirect URI by clicking the Copy button. Store it somewhere temporarily, it is used in the next step for setting up Keycloak.

Tip: Leave the Settings page open in its own tab, we will come back to this page after setting up Keycloak.

2. Steps in Keycloak

Note: It is assumed here that Keycloak is fully set up, including all users who need access to the WoodWing applications via the WoodWing Identity Service, and that you are logged in with sufficient access rights to perform the steps outlined below.

Tip: Click the images for a larger view.

1. Creating a new realm

Step 1. Access the Manage realms page and click Create Realm.

The Create realm dialog appears.

Step 2. In the Realm name field, enter a name.

Step 3. Click Create.

Step 4. Back on the Manage realms page, verify that the newly created realm is set as the 'Current realm'.

2. Creating a new client

Step 1. Access the Clients page and click Create client.

The Create client General settings appear.

Step 2. Enter a Client ID (for example 'wis-test') and click Next.

The Capability config settings appear.

Step 3. Enable the Client authentication option and click Next.

The Login settings appear.

Step 4. In the Root URL field, enter the URL for connecting to the WoodWing Identity Service:

https://identity.woodwing.cloud

Step 5. In the Valid redirect URI field, paste the redirect URI that was copied from the OIDC settings page in the WoodWing Identity Service earlier.

Step 6. Click Save.

3. Creating the groups and oauth client scope

Note: Make sure that the group names match the group names that are defined in the WoodWing application, so that access rights and permissions work correctly.

Step 1. Access the Client scopes page and click Create client scope.

The Create client scope page appears.

Step 2. In the Name field, enter groups.

Step 3. Click Save.

Step 4. Select the Mappers tab and click Add predefined mapper.

The Add predefined mappers dialog appears.

Step 5. Navigate to the second page.

Step 6. Select groups and click Add.

The mapper is shown on the Mapper tab.

Step 7. Create a new client scope by clicking Client scopes in the menu on the left and clicking Create Client scope.

Step 8. In the Name field, enter oath.

Step 9. Click Save.

4. Assigning the groups and openid scopes to the created client

Step 1. In the menu on the left click Clients.

Step 2. Click the newly created client to open its page, select the Client scopes tab, and click Add client scope.

The Add client scopes dialog appears.

Step 3. Select the oauth and groups scopes and click Add/Default.

5. Obtaining the client credentials

In this step, the client credentials needed for setting up the WoodWing Identity Service are obtained.

Tip: These will be copied to the WoodWing Identity Service configuration. You may want to have the WoodWing Identity Service page open in a different tab so that the details can be easily copied, as explained in the next section.

Step 1. Access the Clients page and click the Credentials tab.

Step 2. Obtain the following:

• Client ID: the name of the client.
• Client Secret: click the copy icon next to the Client Secret field.

Step 3. Access the Realm settings page.

The settings on the General tab appear.

Step 4. Obtain the well-known URL by right-clicking the OpenID Endpoint Configuration link located at the bottom of the page and choosing Copy link address.

3. Steps in the WoodWing Identity Service

In this step, the WoodWing Identity Service is configured with the information from the Keycloak configuration.

Step 1. Return to the OIDC tab on the Settings page in the WoodWing Identity Service.

Step 2. Enter the following:

• The name of the client in Keycloak.
• The Client ID from the Clients > Credentials page.
• The Client secret from the Clients > Credentials page.
• The Well-known URL from the Realm settings > General page.

Step 3. Click Set up to store the settings.

4. Testing the integration

Test the integration by letting users (who are configured in Keycloak and who are given access to the app), access the WoodWing tenant that they should have access to.

Revisions

• 21 August 2025: Updated section 'Creating the groups and oauth client scope' with a note to make sure that group names match with those in the WoodWing application.