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

PingFederate Integration

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

Introduction

This document guides you through the installation and configuration of the Nok Nok PingFederate Adapter. Using this Adapter you can implement passwordless authentication on your PingFederate Server, providing a seamless and secure authentication experience for your users.

The installation package includes the Nok Nok PingFederate Adapter and the required JAR libraries. Nok Nok also provides a sign-in page for your end users in the Nok Nok Web App SDK package.

An optional feature of the Adapter is called Inline Registration. When inline registration is enabled, if the end user signs in with a username and password and they have no strong authentication method already registered, then the sign-in page immediately prompts the end user to register a strong authentication method as their second-factor authenticator. Examples of strong authentication methods include FIDO or an adaptive authentication option like Email OTP or SMS OTP.

When your app performs passkey authentication it receives a JWT from the Nok Nok Server. The app sends the JWT to the PingFederate Server using a header, cookie, or form POST. The PingFederate Server then calls the Nok Nok PingFederate Adapter with the JWT for validation. Upon successful validation, the Adapter extracts the sub claim value and stores it in the username attribute of the JWT for the PingFederate Server. See the Sequence Diagrams for more detail.

Installation

To install the Nok Nok Adapter on your PingFederate deployment:

  1. Copy all JAR libraries from the installation package to the PingFederate server's deploy directory:

    <pf-install>/pingfederate/server/default/deploy

  2. Replace any older versions of the third-party JARs included in the package to prevent duplication.

  3. Prepare a jwt_config.json file. To ensure compatibility with the Nok Nok API Server, make sure the keys and configuration parameters for JWT in the jwt_config.json file match those of the API server's JWT Processor. If using a symmetric key on the server, you can export the JWT configuration from the API server session plugin. Refer to Export and Import Configurations for instructions on how to export the API Server configuration.

  4. Copy the prepared jwt_config.json file to <pf-install>/pingfederate/server/default/conf/configurations/<TENANT IDENTIFIER>/SessionPlugin/jwt_config.json, creating the required intermediate directories as needed. See the Nok Nok Adapter’s configuration parameters below.

  5. Restart the PingFederate Server. The Nok Nok Adapter should appear on the PingFederate Admin Console.

  6. Find the nnlsignin application inside the Nok Nok Web App SDK package. Deploy the nnlsignin web application on a web server. nnlsignin can be hosted on an origin that is different from the origin that hosts the PingFederate Adapter. You will configure the sign-in page after you configure the Adapter.

Multi-tenant deployments

If your Nok Nok deployment supports multiple tenants, follow these additional installation instructions:

  1. Use the PingFederate Admin Console to create and configure a separate realm in your PingFederate server for each Nok Nok Server tenant. The Nok Nok Adapter uses the TENANT IDENTIFIER that you configure for a realm in your PingFederate server to find the directory containing the configurations for that realm. See Step 4. in the Installation instructions above for details of this directory structure.

  2. Also while configuring each realm, make sure that the SIGN IN ENDPOINT includes the tenant_id parameter. For example, the following value for SIGN IN ENDPOINT is needed for the nnlsignin app:
    <SIGN IN ENDPOINT>?tenant_id=<TENANT IDENTIFIER>

  3. Repeat Step 3. and Step 4. in the Installation instructions above for each tenant.  

Configuration

To configure the Nok Nok Adapter for your PingFederate deployment, follow the instructions below using the PingFederate Admin Console.

Step 1) Create an IdP Adapter Instance

To create an instance of the Nok Nok Adapter, navigate to Authentication > Integration > IdP Adapters. Click Create New Instance. If the Nok Nok Adapter has been successfully installed, Nok Nok Universal Adapter appears in the list of available adapters.

Fill in the details and click Next:

In the PingFederate Admin Console, the Nok Nok Adapter has the following configuration parameters:

  • SIGN IN ENDPOINT - This is the URL of the sign-in page where the Adapter redirects if the JWT is missing from the request, or if the JWT is present in the request but invalid.

  • TENANT IDENTIFIER - Specifies the tenant ID used for creating tenant-specific intermediate directories.

  • USE POST METHOD - Check this box if one or both of the following applies:

    • your sign-in page delivers the JWT to the Adapter as a request parameter in a form POST.

    • your sign-in page and the PingFederate Server have different origins.

    Note that you cannot use POST method if you enable inline registration.

  • COOKIE DOMAIN - If the PingFederate Server and the nnlsignin app have the same parent domain, specify the domain name here. Note that if you are using inline registration, then the PingFederate Server and the nnlsignin app must have the same domain or the same parent domain. This setting is ignored if "USE POST METHOD" is enabled.

  • ENABLE INLINE REGISTRATION -  When inline registration is enabled, if the end user signs in with a username and password and they have no strong authentication method already registered, then the sign-in page immediately prompts the end user to register a strong authentication method as their second-factor authenticator. Examples of strong authentication methods include FIDO or an adaptive authentication option like Email OTP or SMS OTP. The following are required for Inline Registration:

    • The Nok Nok Adapter is used for second-factor authentication. The Nok Nok PingFed adapter must be set as part of an adapter chaining flow in a PingFederate policy to enable multi-step authentication.

    • You are using Nok Nok Authentication Suite v.9.3 and above.

    • You are not using the POST method.

    • Your sign-in page and the Nok Nok Adapter are hosted on the same domain, or they must share the same parent domain.

    • Enable Inline registration in the Nok Nok API Server Session Plugin using the Nok Nok Admin Console. Load the URL for nnladmin in your browser, log in, navigate to Configuration > API Server > Session Plugins, and enable the Inline registration setting.

    • Your PingFederate Adapter is configured to permit Inline Registration.

Navigate to the Adapter Attributes tab and select username.

To finish setting up the Nok Nok Adapter, click Next to access the summary screen. Take a moment to review the summary and confirm that all the information is accurate. After confirming the information, click Save to create the adapter instance.

The Nok Nok Adapter instance is now displayed on the Identity Provider (IdP) Adapters screen.

Step 2) Map the adapter instance to a grant contract

To map the Nok Nok Adapter instance to a persistent grant contract, navigate to Authentication > OAuth > IdP Adapter Grant Mapping. From the list, select the Nok Nok Adapter instance and click Add Mapping.

Leave the Attribute Sources and User Lookup blank and click the Contract Fulfillment tab. Add details as below:

No changes are required on the Issuance Criteria tab. Click Next to see a summary similar to what is shown below. After reviewing the summary, click Save.

Step 3) Set up a default authentication source

To add the Nok Nok Adapter as a default authentication source, navigate to Authentication > Policies > Default Authentication Sources. Then select the Nok Nok Adapter instance and click Save.

Step 4) Create an access token management instance

To create the access token management instance, navigate to Applications > OAuth > Access Token Management and click Create New Instance.

Click Next until you reach the Access Token Attribute Contract tab. Add the username attribute to Extend the Contract.

Click Next until you reach the Summary tab. Click Save.

Step 5) Add the access token mapping

To add the access token mapping, navigate to Applications > OAuth > Access Token Mappings. Select the Idp Adapter CONTEXT and ACCESS TOKEN MANAGER, and click Add Mapping:

Click Next to reach the Contract Fulfillment tab. Select Adapter as your Source, and select username as your Value.

Click Next until you reach the Summary tab. Click Save.

Step 6) Add OpenID Connect policy

To add the OIDC policy, navigate to Applications > OAuth > OpenID Connect Policy Management and click Add Policy.

Click Next until you reach the Contract Fulfillment tab. Map the sub claim in Access Token to username value. Click Next until you reach the Summary tab. Click Save.

Step 7) Add OAuth clients

Your Nok Nok Adapter is now ready to use. Add your OAuth clients by referring to the instructions at Configuring OAuth Clients - PingFederate.

Sign-in page

If you are integrating FIDO authentication into a web app, or if you are using a webview to integrate it into your mobile app, then you need to have a sign-in web page for your end users. You can either use the nnlsignin web application, or you can use your own sign-in page. In most cases, the sign-in page and the PingFederate Adapter can be hosted on the same or on different domains. However, when using inline registration, the sign-in page and the PingFederate Adapter must be hosted on the same domain or have the same parent domain.

The nnlsignin web application implements the required functionality. This app is shipped with both the Nok Nok Web App SDK and the Nok Nok Server. Test your integration with nnlsignin, even if you intend to implement your own sign-in web page later. For information on how to configure the nnlsignin web app, see Nok Nok Utility Apps. To implement your own PingFederate sign-in page, follow the instructions below.

Implement your own PingFederate sign-in page

Once the Nok Nok PingFederate Adapter is working with the nnlsignin web application, you can choose to implement your own PingFederate sign-in page. The submitLogin() function in file Controller.js of the nnlsignin app demonstrates how to implement FIDO authentication in your page. The submitLogin() function also shows how to do a form POST after successful authentication. That JavaScript code makes use of the Nok Nok Javascript App SDK to initiate FIDO authentication.

The PingFederate Adapter redirects to your PingFederate sign-in page with the following URL query parameters:

URL Query Parameter

Description

goto <resume_url>

If you are hosting the sign-in page on the same origin as the Nok Nok Adapter, then this parameter is required.

resume_path <relative_url>

If you are hosting the sign-in page on an origin that is different from the Nok Nok Adapter, then this parameter is required.

username

Add this parameter only if the user is pre-authenticated, as is the case with a step-up authentication.

tenant_id

Add this parameter only if your Nok Nok deployment has more than one tenant.

Sample URL query if you are hosting the sign-in page on the same origin:

https://<same-origin-host-name>/nnlsignin/?goto=https%3A%2F%2F<same-origin-host-name>%3A9031%2Fas%2FPB2TAsJfGf%2Fresume%2Fas%2Fauthorization.ping&tenant_id=default

Sample URL query if you are hosting the sign-in page on a different origin:

https://<different-origin-sign-in-page-host-name>/nnlsignin/index.jsp?resume_path=%2Fas%2F1QmfS2twMi%2Fresume%2Fas%2Fauthorization.ping&tenant_id=eval

If the authentication is successful, the Nok Nok Web App SDK returns a JWT in sessionData.sessionKey.

Your Javascript code sends the JWT to the PingFederate Adapter in one of the following places:

  • Authorization header

  • Authorization cookie

  • form POST - only available when you are NOT using inline registration.

If you are using the goto URL query parameter, send the JWT as the Authorization header or cookie. This header or cookie is sent with the request to the PingFederate resume URL. If you are using the resume_path URL query parameter, send the JWT as the token parameter.

For more information on how to add FIDO functionality to your sign-in page, refer to the Web Dev Guide.

Initial FIDO Registration through OIDC

Before a user can sign in with FIDO, the user must first authenticate with an external identity provider and then register a FIDO authenticator. The Nok Nok API Server incorporates built-in OIDC client functionality, facilitating access to the FIDO registration page after a user has successfully authenticated with an external identity provider. For comprehensive guidance on configuring External Identity Providers (IdPs), please refer to the section Federated Identity Management in API Server Configuration.

Appendix A: Sequence Diagrams

Web App Sign In Integration

This sequence diagram illustrates the flow for FIDO authentication in a web app.

  1. PingFederate calls the Nok Nok Adapter.

  2. The Nok Nok Adapter redirects to the sign-in page.

  3. PingFederate returns a redirect to the sign-in page

  4. If a FIDO registration exists, FIDO Authentication is performed and response sent to Nok Nok Server.

  5. The Nok Nok Server returns a JWT.

  6. If a FIDO registration does not exist and inline registration is enabled, FIDO registration is performed and the response sent to Nok Nok Server.

  7. The Nok Nok Server returns success.

  8. Sign in page redirects to PingFederate with the JWT.

  9. PingFederate calls the Nok Nok Adapter.

  10. The Nok Nok Adapter validates the JWT and extracts the username and any custom attributes from the JWT.

  11. This username is returned to PingFederate.

Native App Sign In Integration

This sequence diagram illustrates the authentication flow for FIDO authentication in a native app:

  1. Using the Nok Nok App SDK, your app sends a "start FIDO authentication" to the Nok Nok Server.

  2. The FIDO authentication finishes and the Nok Nok Server returns a JWT.

  3. The app redirects to the PingFederate.

  4. PingFederate calls the Adapter.

  5. The Adapter validates the JWT and extracts the username and any custom attributes from the JWT.

  6. This username is returned to PingFederate.

  7. PingFederate sends the app the session.