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

Keycloak Adapter

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

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

You can choose to install the Keycloak Adapter in integrated mode. Integrated mode allows you to manage the Keycloak Adapter from your Nok Nok 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 Nok Nok Keycloak Adapter itself is available on request from Nok Nok 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 Nok Nok Admin Console, then install Keycloak on exactly the same subdomain as the subdomain where the Nok Nok 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 Nok Nok Keycloak Adapter

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

    /<path to keycloak>/providers  

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

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

Edit the Nok Nok 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 Nok Nok 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 Nok Nok Admin Console

You can choose to manage the Nok Nok Keycloak Adapter from the Nok Nok Admin Console by using integrated mode. This allows Nok Nok 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 Nok Nok administrator, after they successfully sign in to the Nok Nok 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 Nok Nok 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 Nok Nok Keycloak Adapter and the Nok Nok Admin Server.

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

  3. Ensure that the name of each Keycloak realm corresponds to the name of a Nok Nok tenant. The Nok Nok Keycloak Adapter automatically maps the Master realm to Nok Nok's Admin tenant. Create any other Keycloak realm with the same name as an existing Nok Nok Server tenant. For example, the default Nok Nok 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 Nok Nok 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 Nok Nok Keycloak Adapter

Create an authentication flow and add the Nok Nok 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 Nok Nok 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 Nok Nok.

Authenticator Reference Max Age

Not used by Nok Nok.

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 Nok Nok SSO page.

Nok Nok Tenant ID

The tenant identifier in the Nok Nok Server.

Just-In-Time (JIT) User Provisioning

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