Digipass S3 is now DigipassONE. This section is currently being updated to reflect our new name.

Keycloak Adapter

  • Updated on May 5, 2026
  • Published on Feb 2, 2026
  • 5 minute(s) read
Prev Next

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

You can choose to install the Keycloak Adapter in integrated mode. Integrated mode allows you to manage the Keycloak Adapter from your Digipass S3 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 Digipass S3 Keycloak Adapter itself is available on request from OneSpan customer support.

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.  

  2. Install Keycloak using the official documentation. If you are using the optional integrated mode to integrate the Keycloak Adapter and the Digipass S3 Admin Console, then install Keycloak on exactly the same subdomain as the subdomain where the Digipass S3 Admin Server is installed.

  3. Configure the Database. Keycloak supports a range of databases.  

  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, which requires special configuration to work properly in a scalable environment. Keycloak provides several ways to configure the cache.  

Step 2. Install the Digipass S3 Keycloak Adapter

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

    /<path to keycloak>/providers  

To configure the Digipass S3 Keycloak Adapter, edit the following file:

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

Edit the Digipass S3 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 Digipass S3 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 to retrieve the password from your secure vault.

Step 3. Optional. Integrate with the Digipass S3 Admin Console

You can choose to manage the Digipass S3 Keycloak Adapter from the Digipass S3 Admin Console by using integrated mode. This allows Digipass S3 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 Digipass S3 administrator, after they successfully sign in to the Digipass S3 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 Digipass S3 Admin Console corresponds to the master realm in the Keycloak Admin Console. The default value is Admin.

     For example:  

    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:

  2. Secure the communications between the Digipass S3 Keycloak Adapter and the Digipass S3 Admin Server.

    1. The integration between Keycloak and the Digipass S3 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 Digipass S3 Admin Server.

  3. Ensure that the name of each Keycloak realm corresponds to the name of a Digipass S3 tenant. The Digipass S3 Keycloak Adapter automatically maps the Master realm to the Digipass S3 Admin tenant. Create any other Keycloak realm with the same name as an existing Digipass S3 Server tenant. For example, the default Digipass S3 tenant must correspond to the default Keycloak realm. Create the default realm using Keycloak's command line tool:

    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 Digipass S3 command line tool nnl-mgmt.sh to set the property for nnl.keycloak.base.url.  

    ./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.  

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

Step 4. Configure the Digipass S3 Keycloak Adapter

Create an authentication flow and add the Digipass S3 Authenticator to that flow.

  1. Navigate to the Authentication tab and click Create Flow.

  2. Fill in the required fields and click Create.

  3. Click Add execution and select Digipass S3 Authenticator. Click Add.

  4. Click the gear (⚙) icon to open the configuration settings.

 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 Digipass S3.

Authenticator Reference Max Age

Not used by Digipass S3.

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 Digipass S3 SSO page.

Digipass S3 Tenant ID

The tenant identifier in the Digipass S3 Server.

Just-In-Time (JIT) User Provisioning

If enabled, users who authenticate through the sign-in page are automatically provisioned in Keycloak.