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

Considerations for integration

  • Updated on Apr 14, 2026
  • Published on Nov 27, 2025
  • 6 minute(s) read
Prev Next

Take the following considerations into account during integration.

Hosting the App SDK on a Content Delivery Network

The Digipass S3 App SDK for JavaScript is hosted on the same origin as the API Server by default. If you need to host static web content on a Content Delivery Network (CDN) with a different origin from the API Server, choose one of these two approaches.

Host iframe.jsp on the same origin as the API Server origin, and host the nnlappsdk’s static files on a different, CDN, origin.

  1. Set up two instances of nnlappsdk, one on the API Server origin and the other on the CDN origin.

  2. Set the nnlappsdk on the API server origin to use JS files from the CDN origin. To do this,

    1. Specify the context parameter "appsdkUrl" in the context.xml file to point to the nnlappsdk URL in the CDN origin.

    2. Place the context.xml file in the META-INF directory of the nnlappsdk application.

<?xml version="1.0" encoding="UTF-8"?>
<Context>
   <Parameter name="appsdkUrl"
       value="https://CDN-origin-and-path-where-nnlappsdk-is-deployed" />
</Context>

  1. In your home page:

    1. Include a hidden iframe HTML element.

    2. Set the id of the hidden iframe element to be nnl_iframe.

    3. Set the src attribute of the hidden iframe element to be the URL of the iframe.jsp hosted on the API Server origin.

<!DOCTYPE html>
<html>
. . .
<body>
. . .
    <!-- This iframe is used by the AppSDK for communication with NNL Server -->
    <iframe id="nnl_iframe" name="nnl_iframe" style="display:none;" src=<URL-of-the-iframe.jsp-hosted-on-the-API-Server-origin>></iframe>
. . .
</body>
</html>

Alternative Approach: Configure Cross-origin Resource Sharing

You can achieve the same results using one instance of the nnlappsdk, hosted on the CDN domain, and configuring Cross-Origin Resource Sharing (CORS) on the API Server to enable access from the CDN’s domain. While this approach prevents unauthorized cross-origin resource requests, its configuration is more complex and it may cause problems like browser incompatibility and extra round-trips to the Content Delivery Network.

To set up CORS on the API Server using the web.xml deployment descriptor:

  1. Open the nnlgateway/WebContent/WEB-INF/web.xml

  2. Add the following configuration inside the <web-app> element to enable CORS:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE xml>
<web-app xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns="https://java.sun.com/xml/ns/javaee" xsi:schemaLocation="https://java.sun.com/xml/ns/javaee https://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" id="WebApp_ID" version="3.0">
. . .
<!-- CORS setup -->
  <filter>
     <filter-name>CorsFilter</filter-name>
     <filter-class>org.apache.catalina.filters.CorsFilter</filter-class>
       <init-param>
         <param-name>cors.allowed.origins</param-name>
         <param-value>
             CDN’s-origin-value-where-nnlappsdk-is-deployed
         </param-value>
       </init-param>
       <init-param>
          <param-name>cors.allowed.methods</param-name>
            <param-value>POST</param-value>
       </init-param>
       <init-param>
          <param-name>cors.allowed.headers</param-name>
          <param-value>Content-Type,Authorization</param-value>
       </init-param>
       <init-param>
          <param-name>cors.exposed.headers</param-name>
          <param-value>NNL-API-Server-Processing-Time</param-value>
       </init-param>
       <init-param>
         <param-name>cors.support.credentials</param-name>
         <param-value>true</param-value>
       </init-param>
    </filter>
    <filter-mapping>
        <filter-name>CorsFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
. . .
</web-app>

Hosting Your Web App and the API Server on Different Domains

By default, the Digipass S3 App SDK for JavaScript relies on iframe. If you use this default setting, make sure that no X-Frame-Options HTTP response header is set by the Auth Server. Or, if set, you must configure it properly with Cross-Origin Resource Sharing (CORS). The iframe element is handled by the App SDK and the web app does not put an iframe element onto the page.

The App SDK for JavaScript has a mechanism to prevent pages from unexpected origins from performing operations using an iframe. If the caller page and iframe have different origins, the SDK for JavaScript sends the origin of the caller page as a part of the REST call to the API Server's endpoint. As a result, the endpoint can reject calls from unexpected origins. For more information, see the callerOrigin attribute in the REST API Reference.

To avoid rejection, the API Server keeps a list of allowed origins, see the origin_allowlist property in API Server Configuration. Consequently, there is no need to use an X-Frame-Options HTTP response header.

Using the App SDK without an iframe

By default, the Digipass S3 App SDK for JavaScript relies on iframe for communication with the API Server. If you do not wish to include an iframe in your web app, add the data-nnl-use-iframe="false" attribute on the <script> tag for utils.js.

<script src="https://<nnl_apiserver_domain>:<port>/nnlappsdk‑<version>/js/utils.js" data-nnl-use-iframe="false"></script>

If your web app and the API Server are hosted on different domains, make sure to configure Cross-Origin Resource Sharing (CORS) on the API Server to enable access from your web app's domain. In this case, set cors.allowed.origins to the origin of your web app.

Accessing Your Web App and the API Server from Different Domains

If your web app and the API Server are hosted on the same domain, but both can also be accessed from a different domain (e.g. domain alias), then your web app front-end (JavaScript) might need several adjustments. For example, the URLs for the web app and the API Server could be

  • https://example.com/mywebapp

  • https://example.com/nnlapiserver

Or

  • https://alias.example.com/mywebapp

  • https://alias.example.com/nnlapiserver

In both cases, mywebapp and the API Server are on the same domain.

Do the following:

  • Use a relative URL to load the API Server file, appsdk.js, into your web app. For example:

<script src="../nnlappsdk-<version>/js/appsdk.js"></script>

  • Use the JavaScript window.location property to dynamically construct a full URL for the App SDK regEndpoint and authEndpoint. For example:

appSdk.regEndpoint = window.location.host + 
                     "/nnlgateway/nnl/<tenant_id>/reg";
appSdk.authEndpoint = window.location.host + 
                     "/nnlgateway/nnl/<tenant_id>/auth";

Using windows.location adds flexibility because the web app doesn't know on which domain it's located, but it does know that the API Server is on the same domain. Browsers have rules that enforce a same-origin policy. So even if a malicious script changes window.location, a browser won't allow a request to be sent to an origin other than the current one.

Implementing a Proxy Server

By default, the JavaScript App SDK is configured so the registration and authentication endpoints (regEndpoint and authEndpoint, respectively) can only use paths that match the regular expression pattern: /nnlgateway/. https://example.com/nnlgateway/nnl/reg is an example of a URL that matches this regular expression. If there is a proxy server between the client and the API Server, then the URLs that you assign to regEndpoint and authEndpoint might not match the default regular expression.

You need to modify the regular expression to match the proxy server's path so the JS App SDK can verify the endpoints. For example, if regEndpoint is https://example.com/myproxy/registration, then the regular expression must be /myproxy/. This change needs to be done on the backend. Specify the regular expression in one of the following locations:

  • $TOMCAT_HOME/webapps/nnlappsdk‑<version>/WEB-INF/web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app … >
…
  <context‑param>
    <param‑name>endpoint_regex_pattern</param‑name>
    <param‑value>/nnlgateway/</param‑value>
  </context‑param>
…
</web-app>

  • $TOMCAT_HOME/webapps/nnlappsdk-<version>/META-INF/context.xml

<?xml version="1.0" encoding="UTF-8"?>
<Context>
…
    <Parameter name="endpoint_regex_pattern"
               value="/nnlgateway/"
               override="false"/>
…
</Context>

Using HttpOnly Cookies to Return the Session

If your API Server Session plugin uses HttpOnly cookies to return the session, then your web app and the API Server must be hosted on the same domain. If they are hosted on different domains, then you need to consider other mechanisms to return the session. For example, you can pass a JSON Web Token (JWT) in the response body or use a federation protocol such as OIDC or SAML.

Integration with ReactJS

The Digipass S3 Web AppSdk includes components that allow ReactJS apps to easily add FIDO functionality. ReactJS developers install the Digipass S3 ReactJS Component Library and expose a collection of ReactJS components to integrate into their web applications.

Components of the Digipass S3 ReactJS Library

  • NNLAppSdk acts as a core module. This provides nnlappsdk_url, regEndpoint and authEndpoint for registration and authentication endpoints used by ReactJS components.

  • AdaptiveAuthenticationView returns a view that either automatically starts FIDO authentication or shows available methods for the user to select from.

  • AdaptiveRegistrationView returns a view that shows a UI for registering and deleting adaptive methods.

  • FidoRegistrationView returns a view that shows the FIDO methods available for registration.

  • ManageRegistrationsView returns a view that shows a list of existing registrations. This allows the user to rename or delete an adaptive authentication method.

Installing the Digipass S3 ReactJS Component Library

The Digipass S3 ReactJS Component Library is in the Digipass S3 Web App SDK deployment package. To install the Digipass S3 ReactJS Component Library, follow these steps:

  1. Navigate to your ReactJS web application root directory.

  2. Install the Digipass S3 ReactJS Component Library.

npm install /path/to/web-appsdk-bom-directory/react/ --install-links

  1. Import the components into your React application code.

import {NNLAppSdk, AdaptiveRegistrationView, 
  FidoRegistrationView, ManageRegistrationsView} from ‘nnl-react-appsdk’;

  1. Use the components in your JSX code.

For more details, see the Client API Docs.