---
title: "Keycloak Adapter"
slug: "dpo-iam-integration-keycloak-adapter"
updated: 2026-10-27T19:53:14Z
published: 2026-10-27T19:53:14Z
canonical: "docs.onespan.com/dpo-iam-integration-keycloak-adapter"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keycloak Adapter

To incorporate FIDO authentication into your existing OIDC identity provider, use the DigipassONE Keycloak Adapter. The Keycloak Adapter enables FIDO authentication using OIDC or SAML between your app and DigipassONE authentication software.

You can choose to install the Keycloak Adapter in integrated mode. Integrated mode allows you to manage the Keycloak Adapter from your DigipassONE Admin Console, without an additional sign-in. Decide whether you want to use this integrated mode before you begin this installation, because the instructions differ slightly depending on your choice.

This article gives instructions for installing the Keycloak Adapter. The DigipassONE Keycloak Adapter itself is available on request from [OneSpan customer support](mailto:support@onespan.com).

## Step 1. Install Keycloak

Keycloak can run on Linux, Windows or MacOS. It requires OpenJDK version 17 or later.

1. Download [version 24.0.2 of Keycloak](https://www.keycloak.org/archive/downloads-24.0.2.html).
2. Install Keycloak using the [official documentation](https://www.keycloak.org/guides). If you are using the optional [integrated mode](/dpoa/docs/keycloak-adapter-1#step-3-optional-integrate-with-the-nok-nok-admin-console) to integrate the Keycloak Adapter and the DigipassONE Admin Console, then install Keycloak on exactly the same subdomain as the subdomain where the DigipassONE Admin Server is installed.
3. Configure the Database. Keycloak supports [a range of databases](https://www.keycloak.org/server/db).
4. **Optional**. Configure the Cluster.

This is only required if you are deploying on AWS ECS. Keycloak relies extensively on the internal caching system [Infinispan](https://infinispan.org/), which requires special configuration to work properly in a scalable environment. Keycloak provides several ways to [configure the cache](https://www.keycloak.org/server/caching).

## Step 2. Install the DigipassONE Keycloak Adapter

Copy all JAR files from nn_keycloak_bom_{version}.zip into the following directory:

/<path to keycloak>/providers

To configure the DigipassONE Keycloak Adapter, edit the following file:

/<path to keycloak>/conf/keycloak.conf

Edit the DigipassONE Adapter properties in the table below. Each property begins with spi-authenticator-noknok-authenticator-. For example,

spi-authenticator-noknok-authenticator-gw-db-url.

| **Required Property** | **Description** |
| --- | --- |
| gw-db-url | The JDBC URL for the DigipassONE Server's operational database. For example: jdbc:postgresql://localhost:5432/nnldb |
| gw-db-username | The JDBC user name. |
| gw-db-password-enc | The encrypted password of the JDBC user. |
| gw-db-driver | The JDBC driver class name. For example: org.postgresql.Driver |
| gw-db-connection-properties | A semicolon separated set of key=value pairs for additional connection pool properties. <key1>=<value1>;<key2>=<value2> For example: maxWaitMillis=5000;maxWait=10000;maxTotal=20;minIdle=1;maxIdle=3;timeBetweenEvictionRunsMillis=30000;minEvictableIdleTimeMillis=60000;removeAbandonedOnBorrow=true;removeAbandonedTimeout=10; |

**Note**: The database password, gw-db-password-enc, must be stored in encrypted form. Alternatively, you can implement the [Secrets plugin](/dpoa/docs/s3suite94-implementing-the-secrets-plugin-1) to retrieve the password from your secure vault.

## Step 3. **Optional**. Integrate with the DigipassONE Admin Console

You can choose to manage the DigipassONE Keycloak Adapter from the DigipassONE Admin Console by using integrated mode. This allows DigipassONE Admin Console users to access the Keycloak Admin Console without an additional sign-in.

1. Configure all of the following integration properties in the file /<your path to keycloak>/conf/keycloak.conf. Each property begins with

spi-authenticator-noknok-authenticator-

| **Integration Property** | **Description** |
| --- | --- |
| integrated-mode | Set this to true to enable the integration with the NNL Admin Console. Default value is false. |
| sign-in-url | The URL of the NNL Admin Console sign-in page. For example, https://example.com/nnladmin/login.jsp |
| token-field-name | The name of the cookie set by the NNL Admin Console after a successful sign-in. Set this property to AdminSessionKey. |
| jit-user-provisioning | Set this to true to enable the Keycloak Adapter to automatically provision a Keycloak user for each DigipassONE administrator, after they successfully sign in to the DigipassONE Admin Console. Default value is false. |
| back-btn-href | The Keycloak Admin Console navigation bar contains a back button that redirects to this URL. Defaults to /nnladmin/index.jsp |
| back-btn-text | The Keycloak Admin Console navigation bar contains a back button with this label. Default value is Back. |
| root tenant | The root tenant of the DigipassONE Admin Console corresponds to the master realm in the Keycloak Admin Console. The default value is Admin. |

## For example:

```plaintext
spi-authenticator-noknok-authenticator-integrated-mode=true
                spi-authenticator-noknok-authenticator-sign-in-url=https://sampleurl.com/nnladmin/login.jsp
                spi-authenticator-noknok-authenticator-token-field-name=AdminSessionKey
                spi-authenticator-noknok-authenticator-jit-user-provisioning=true
                spi-authenticator-noknok-authenticator-back-btn-href=https://nnl serveripaddress.com:9443/nnladmin/index.jsp
                spi-authenticator-noknok-authenticator-back-btn-text= ⇦ Back to Server Administration
                spi-authenticator-noknok-authenticator-root-tenant=Admin
```

This is part of the Keycloak Admin Console showing the back button labeled with the back-btn-text property from the example above:

![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/base64-converted-image-1791315553014.png?sv=2026-02-06&spr=https&st=2026-10-29T05%3A02%3A46Z&se=2026-10-29T06%3A02%3A46Z&sr=c&sp=r&sig=GM3MY5vbEmfonclZrNKlQHAL1qIF0W8Hbi2z3XEO7vc%3D)
2. Secure the communications between the DigipassONE Keycloak Adapter and the DigipassONE Admin Server.
  1. The integration between Keycloak and the DigipassONE Keycloak Adapter requires that Keycloak is installed on the same subdomain where the NNL Admin Server is installed.
  2. This communication uses cookies and headers, so configure Keycloak to run on a secured port. By default Keycloak runs on port 8080, so instead configure Keycloak to run on port 443 or port 9443.
  3. Configure TLS for Keycloak with the same domain as you configured the TLS for the DigipassONE Admin Server.
3. Ensure that the name of each Keycloak *realm* corresponds to the name of a DigipassONE *tenant*. The DigipassONE Keycloak Adapter automatically maps the Master realm to the DigipassONE Admin tenant. Create any other Keycloak realm with the same name as an existing DigipassONE Server tenant. For example, the default DigipassONE tenant must correspond to the default Keycloak realm. Create the default realm using Keycloak's command line tool:

```plaintext
kcadm.sh create realms -s realm=default -s enabled=true -o
```
4. Configure the NNL Admin Console to include a link to the Keycloak Admin Console. Use the DigipassONE command line tool nnl-mgmt.sh to set the property for nnl.keycloak.base.url.

```plaintext
./nnl-mgmt.sh properties set nnl.keycloak.base.url -value https://nnlkeycloakaddress.com:9443 -tenantid Admin
```

After you set this property, the NNL Admin Console's **Configuration** menu has an additional item for **Keycloak**.

![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/base64-converted-image-1791315553016.png?sv=2026-02-06&spr=https&st=2026-10-29T05%3A02%3A46Z&se=2026-10-29T06%3A02%3A46Z&sr=c&sp=r&sig=GM3MY5vbEmfonclZrNKlQHAL1qIF0W8Hbi2z3XEO7vc%3D)

When you choose the **Configuration>Keycloak** menu item, your browser displays the Keycloak Admin Console.

## Step 4. Configure the DigipassONE Keycloak Adapter

Create an authentication flow and add the DigipassONE Authenticator to that flow.

1. Navigate to the **Authentication** tab and click **Create Flow**.
2. Fill in the required fields and click **Create**.

![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/base64-converted-image-1791315553017.png?sv=2026-02-06&spr=https&st=2026-10-29T05%3A02%3A46Z&se=2026-10-29T06%3A02%3A46Z&sr=c&sp=r&sig=GM3MY5vbEmfonclZrNKlQHAL1qIF0W8Hbi2z3XEO7vc%3D)
3. Click **Add execution** and select DigipassONE **Authenticator**. Click **Add**.

![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/base64-converted-image-1791315553019.png?sv=2026-02-06&spr=https&st=2026-10-29T05%3A02%3A46Z&se=2026-10-29T06%3A02%3A46Z&sr=c&sp=r&sig=GM3MY5vbEmfonclZrNKlQHAL1qIF0W8Hbi2z3XEO7vc%3D)
4. Click the gear (⚙) icon to open the configuration settings.

![](https://cdn.document360.io/038f59a7-abd0-4c14-9de7-3434d28b49fd/Images/Documentation/base64-converted-image-1791315553748.png?sv=2026-02-06&spr=https&st=2026-10-29T05%3A02%3A46Z&se=2026-10-29T06%3A02%3A46Z&sr=c&sp=r&sig=GM3MY5vbEmfonclZrNKlQHAL1qIF0W8Hbi2z3XEO7vc%3D)

Fill in the properties in this configuration dialog and click **Save**. The properties are described below:

| **Property** | **Description** |
| --- | --- |
| Alias | Name of the flow configuration. Set this when you create a new flow. String |
| Authenticator Reference | Not used by DigipassONE. |
| Authenticator Reference Max Age | Not used by DigipassONE. |
| Sign-in Page URL | The full URL of the sign-in page where the user completes FIDO authentication. |
| Header or Cookie name of the token | The key of the authorization token that the authenticator looks for in headers or cookies. **Note**: This property is not required when you use the DigipassONE SSO page. |
| DigipassONE Tenant ID | The tenant identifier in the DigipassONE Server. |
| Just-In-Time (JIT) User Provisioning | If enabled, users who authenticate through the sign-in page are automatically provisioned in Keycloak. |

Formerly known as Digipass S3.

The Keycloak Adapter implements a Keycloak Authenticator.

Formerly Digipass S3 software.

Formerly known as Digipass S3 Server.

If you install Keycloak on a subdomain of the domain where the Digipass S3 Admin Server is installed, integration fails.