Digipass S3 Authentication API

Session Plugins

The API Server supports multiple Session plugins. These plugins are described in the subsections below. The Session Preprocessor, JWT Processor, and the Session Postprocessor plugins are mandatory unless you create your own custom session plugin to replace one or more of them. The other plugins are all optional.

To configure the API Server to use the Session plugins you need, do the following:

1. Identify which optional plugins you need based on the type of client apps you implement and the functionality you use.

2. Use the Admin Console to activate or deactivate the plugins you want to use. After logging in to the Admin Console, navigate to Configuration > API Server > Authentication API > Session Plugins to activate or deactivate plugins.
   
   You can also modify the Session plugin's Main configuration object to achieve the same result, although this requires knowing the class that corresponds to a plugin. The API Server refers to Main to create the plugins based on the classes listed there. This activates the plugins so your apps can use them.
   
   The Main configuration object is described in the last subsection.

The table below summarizes when you need to use each session plugin and lists their associated class name and, where appropriate, their configuration object.

Always

Main

Session Plugins' Main object specifies the class names for the active Session Plugins. The Admin Console creates this Main object automatically based on which session plugins you Activate or Deactivate. The Admin Console also sets the flags in this Main object based on whether you enable or disable Authentication with user name and Allow push notifications without push handle. If you use the Command Line Interface, you can edit the Session Plugins' Main object with your text editor.

The API Server automatically creates an object for each class in the order listed in the classes field of this Main object. auth_with_username and push_without_handle are required for using FIDO2 on Android or sending a push notification without a push handle, respectively.

If the plugins are in the wrong order, session validation may not work. The Digipass S3 default session plugins MUST occur in this order: 1) SessionPreprocessor, 2) JWTProcessor and 3) SessionPostprocessor. You can customize the order of plugins by dragging and dropping plugin rows in the admin console UI.

The classes for the Session Preprocessor, JWT Processor and Session Postprocessor plugins:
"com.noknok.gateway.plugin.session.SessionPreprocessor", "com.noknok.gateway.plugin.session.JWTProcessor", "com.noknok.gateway.plugin.session.SessionPostprocessor".

Example Main Configuration for the Session Plugins

{
    "classes": [
        "com.noknok.gateway.plugin.session.SessionPreprocessor",
        "com.noknok.gateway.plugin.session.JWTProcessor",
        "com.noknok.gateway.plugin.session.SessionPostprocessor",
        "com.noknok.gateway.plugin.session.PushNotificationPlugin",
        "com.noknok.gateway.plugin.session.CredentialSimulator",
        "com.noknok.gateway.plugin.session.UAParserPlugin",
        "com.noknok.gateway.plugin.session.Emv3dsSessionPlugin",
        "com.noknok.gateway.plugin.session.IPAddressPlugin"
    ],
    "auth_with_username":true,
    "push_without_handle":false
}

Session Preprocessor

The Session Preprocessor prepares the request for the JWT Processor. It extracts the sessionKey token from the request payload and makes it available for the JWT Processor.

This plugin does not have its own configuration object. You can deactivate it only if you replace it with a custom session plugin.

JWT Processor

This plugin is critical for the proper functioning of the API Server. The JWT Processor plugin supports sessions using a JSON Web Token (JWT) as defined in RFC 7519.

This plugin uses a configuration object called jwt_config which specifies a secure session. When you install the Digipass S3 API Server, jwt_config is configured to generate and validate a JWT using the symmetric HS256 algorithm with one secret key. The generated JWT has a lifespan of 1 hour. For a production deployment, replace this with a JWT that uses an asymmetric algorithm.

For security reasons, jwt_config must be configured differently for each tenant. If improperly configured, the resulting sessions may be vulnerable to attacks. You can easily generate a new jwt_config with the default configuration. Use either the Admin Console or the nnl-mgmt.sh command-line utility. See Step 3. Update the API Server Configurations.

If your circumstances require that you use a different key, a different algorithm, a JWE instead of a JWS, and so on, then you need to modify jwt_config. See Understanding the Session Token. You can find documentation about jwt_config in Configuring JWT Generation and Validation.

Session Postprocessor

The Session Postprocessor processes the request after the JWT Processor. It sets the userName so that the Digipass S3 Server knows which end user is performing the request (for example, registration or listing registered authenticators). This plugin does not have its own configuration object. You can deactivate it only if you replace it with a custom session plugin.

Push Notification Activator

This plugin is required to perform out-of-band authentication and out-of-band transaction confirmation using push notifications. This plugin does not have its own configuration object, but you can verify that it is activated.

User Agent Parser Plugin

Use the User Agent (UA) Parser plugin if you implement web apps that use WebAuthn. This plugin parses the browser's user agent string, extracts relevant information about the device, platform, and browser, and sends it to the Auth Server. This plugin's configuration object can be identical across all tenants, so copy the ua_parser configuration object from an existing tenant, like default.

EMV 3DS Generator Plugin

This plugin adds additional data required by the EMV 3DS protocol. This protocol was developed by EMVCo to enable consumers to authenticate themselves when making credit card-not-present purchases. For information about the EMV 3DS protocol requirements for this data, download the EMV® 3-D Secure Protocol from the EMVCo site and see Table A.10, entry "threeDSReqAuthData".

This plugin returns EMV 3DS data to the App SDK in sessionData's emv3dsData attribute in the following situations:

• Regular FIDO: Successful registration, authentication, or transaction confirmation.

• Adaptive Authentication: The succeeding Adaptive Rule returns an EMV 3DS FIDO blob.

The EMV 3DS plugin generates JSON Web Signatures (JWSs) containing EMV 3DS data but validation is always done by a 3rd party. This plugin has a configuration object called jws_config that specifies what algorithm and key to use and where to find the key.

The default settings for this plugin's configuration object generates a JWS using the symmetric HS256 algorithm with one secret key. The Digipass S3 Admin Console and the nnl-mgmt.sh command-line utility have built-in support to create a new jws_config with these default settings.

jws_config, shown below, is similar to jwt_config but it only contains a generate object because the API Server doesn't validate JWSs. For a description of these fields, refer to generate Fields. To learn more about key sources, see Key Sources.

{
    "generate":{
        "kid":"1",
        "algorithm":<signing_encryption_algorithm>,
        "jwks_object":<>,
        "jwks_keystore":{
            "file":<keystore_file_path>,
            "storepass":<keystore_password>,
            "keypass":[
                {
                    "alias":<key_alias_name>,
                    "pass":<key_password>
                }
            ]
        }
    }
}

For security reasons, this object must be configured differently for each tenant. You can generate a new jws_config that uses the default configuration with either the Admin Console or the nnl-mgmt.sh command-line utility.

You can modify jws_config to change the algorithm, key, and the key source. Because jws_config is similar to jwt_config, use the instructions in When to Modify a JWT Configuration Object but ignore changes to the validate object.

This plugin can assign a certificate chain to a JWS's x5c header parameter. See Using a Certificate Chain.

By default this plugin is not active in production installations. Use the instructions below to activate it.

Using the Admin Console

1. Log in and, if needed, switch to the desired tenant. Navigate to Configuration > API Server > Authentication API > Session Plugins.

2. Find the EMV 3DS Generator label. If the status is INACTIVE,  click the Activate button to activate the EMV 3DS Generator, then click the Modify button to modify the plugin’s configuration page.

   

3. Click the Generate button. Confirm that you want to generate a new configuration object.

Using nnl-mgmt.sh

Use the nnl-mgmt.sh's apiserver create command to generate a new jws_config for the EMV 3DS plugin. The example below generates a new jws_config for the Marketing tenant.

./nnl-mgmt.sh apiserver create -tenantid Marketing -type SessionPlugin -name jws_config

IP Address Extractor Plugin

Use this plugin if you create Adaptive Rules that use an IP address in their condition. By default this plugin is not active. It extracts the IP Address from the request header and packages that information for the Authentication Server. It can do this even if the client is connected to the API Server through a proxy or load balancer.

This plugin supports proxy servers that use the following commonly-used request header types:

• Forwarded

• X-Forwarded-For

• WL-Proxy-Client-IP

• X-Real-IP

If your proxy server doesn't use any of the above request headers, you can modify the IP Address's configuration object, ip_address_plugin. An example is shown below.

{
  "proxy_patterns": [
    {
      "headers": [
        "Forwarded"
      ],
      "regex": "(?<=(for=))((2(5[0-5]|[0-4][0-9])|1[0-9]{1,2}|[1-9]?[0-9])[.]){3}(2(5[0-5]|[0-4][0-9])|1[0-9]{1,2}|[1-9]?[0-9])|([0-9a-fA-F]{1,4}[:]){7}[0-9a-fA-F]{1,4}|(?<=\\[)[^\\]]+"
    },
    {
      "headers": [
        "X-Forwarded-For",
        "WL-Proxy-Client-IP",
        "X-Real-IP"
      ],
      "regex": "((2(5[0-5]|[0-4][0-9])|1[0-9]{1,2}|[1-9]?[0-9])[.]){3}(2(5[0-5]|[0-4][0-9])|1[0-9]{1,2}|[1-9]?[0-9])|([0-9a-fA-F]{1,4}[:]){7}[0-9a-fA-F]{1,4}"
    }
  ]
}

proxy_patterns is an array of header-rule objects. Each header-rule specifies an array of header names and a regular expression. The API Server uses regex to extract the client IP address from the header. If the header name matches an entry in the headers array, the associated regular expression is used. If your proxy's header can be parsed by an existing regex, you can add your header name to the corresponding headers array. Otherwise, create a new header-rule object.

If the API Server cannot find a match using these patterns, it takes the remote IP address of the client. This assumes that the API Server has a direct connection to the client.

You can revert back to the default configuration for ip_address_plugin using the Admin Console. Login using an administrative user who can manage the tenant in the Admin Console. Navigate to Configuration > API Server > Authentication API > Session Plugins. Click the Modfy button to modify the plugin’s configuration and then click Reset.

If you deactivated this plugin, use these instructions to reactivate it.

1. Login and, if needed, switch to the desired tenant. Navigate to Configuration > API Server > Session Plugins.

2. Look for the label IP Address Extractor. If it has ACTIVE in the Status column, the plugin is already active. Otherwise, click the Activate button.

Privacy Credential Generator Plugin

This plugin is required if you create Android apps that use FIDO2 or web apps that use WebAuthn. It is used in conjunction with auth_with_username to enable an authentication flow in which the username is known up front.

This plugin's configuration object is credsim_config which must be configured differently for each tenant. The credsim_config object contains 1 field which is a cryptographic salt. You can easily generate a new credsim_config using either the Admin Console or the nnl-mgmt.sh command-line utility. See Authenticating with the User Name for instructions.

Policy Selector Plugin

The Digipass S3 API Server's Policy Selector plugin configuration specifies the default FIDO policy to use for non-adaptive FIDO registrations. For all adaptive operations, the FIDO policy is specified in the adaptive ruleset. The FIDO policy specifies the valid authenticators that can be registered. See the Registering section in the Android, iOS, or Web Developer Guide to see how the application triggers the use of this plugin.

The Policy Selector plugin uses 2 configuration objects: Main and default_config.

Main

Main specifies the class name for the Policy Selector plugin, which includes the full path. The API Server automatically creates an object of this class and uses this name. Don't change the class name. The object should be exactly as shown below:

{
    "class":"com.noknok.gateway.plugin.policy.DefaultPolicyManager"
}

default_config

The JSON for this object specifies the default FIDO policy to use for non-adaptive registration. It also provides a way to override the default policy. Use the Admin Console to create FIDO policies.

Fields

The fields in default_config are listed in the table below.

The FIDO policy named “default” is used as the default policy for FIDO operations. This default policy is only defined in non-production installations of S3.

The server uses the policy named “default” for non-adaptive registration operations. To override this behavior,  specify a different policy name in the default_config. See below for an example.

An example default_config

{
    "registration_policy_name": "acmeRegPolicy",
}

To override the default policy for a non-adaptive registration operation, pass the policy name in the request payload in the optionsData object as follows:

{
    …
    "optionsData":
    {
        "policyName": "policyNameValue"
    }
    …
}

Transaction Plugin

Note that the Transaction plugin is optional and you can disable it by deleting its Main object.

Transactions are cryptographic proof of a user's confirmation to a specific set of transaction details, such as purchasing merchandise totalling $369. When the Auth Server successfully authenticates the user's consent, the Transaction plugin generates a secure transaction confirmation token called tcToken. This token is important because it is sent to the client app's backend system to prove that the user confirmed the transaction before the transaction is actually processed.

The tcToken is a JWT that includes the transaction ID in its txn claim. For more details on tcToken's structure see Transaction Confirmation Token. The Transaction plugin assigns this JWT to SessionData.tcToken. The API Server returns SessionData to the App SDK. The client app retrieves SessionData.tcToken and sends it to the backend server to process the transaction. For an overview of the transaction confirmation process and what the client app is responsible for doing, see Transaction in the iOS, Android, and Web Developer Guides. To configure the API Server to support transactions, see Configuring Transaction Support.

The Transaction plugin uses 2 configuration objects, Main and jwt_config, described below.

Main

Main specifies the class name for the Transaction Plugin, which includes the full path. The API Server dynamically creates an object of this class and uses this name. Don't change the class name. The object should be exactly as shown below:

{   "class":"com.noknok.gateway.plugin.transaction.JWTTransactionManager"
}

jwt_config

The JSON for this object specifies information related to transaction confirmation. This plugin uses a configuration object called TransactionPlugin/jwt_config. When you install the Digipass S3 API Server, jwt_config is configured to generate and validate a JWT using the symmetric HS256 algorithm with one secret key. The generated JWT has a lifespan of 1 hour.

For security reasons, jwt_config must be configured differently for each tenant. You can easily generate a new jwt_config with the default configuration. Use either the Admin Console or the nnl-mgmt.sh command-line utility. See Step 3. Update the API Server Configurations.

If your circumstances require that you use a different key, a different algorithm, a JWE instead of a JWS, and so on, then you need to modify jwt_config. For common scenarios that require editing jwt_config and detailed instructions, see When to Modify a JWT Configuration Object. You can find documentation about jwt_config in Configuring JWT Generation and Validation.

External Authentication Plugins

Allow your users to authenticate with a password, or any other non-FIDO method that you have implemented, by configuring an External Authentication Plugin. The Digipass S3 API Server provides two optional External Authentication Plugins: the JWT External Authentication Plugin, and the Password External Authentication Plugin.

• If your client app verifies the user and generates a JWT, then configure the JWTAuthenticationMethod.

• If your client app sends a password to the API Server for verification, then configure the PwdAuthenticationMethod.

This section describes the configuration objects for these two built-in External Authentication Method plugins. Note that configuring the External Authentication plugins is only one step in creating an External Authentication Method for your end users. See Configure External Authentication for the other steps. If neither of these built-in plugins satisfy your requirements, you can create a custom External Authentication plugin.

Activate or deactivate these plugins in one of the following 2 ways:

• Modify the Main object for the type ExternalAuthenticationPlugin.

• Log into the Admin Console, navigate to Configuration > API Server > External Authentication Plugins, and click the Activate or Deactivate for JWT Authentication Method or Password Authentication Method.

The External Authentication Plugins share the same Main configuration object.

Main specifies the class name for either of the External Authentication plugins, which includes the full path. The API Server dynamically creates an object of this class and uses this name. Don't change the class name

{
  "classes": [
    "com.noknok.gateway.plugin.external.JWTAuthenticationMethod"
  ]
}

If you are using the Password External Authentication Plugin, the Main object should look like this:

{
  "classes": [
    "com.noknok.gateway.plugin.external.PwdAuthenticationMethod"
  ]
}

JWT External Authentication Plugin

The default, generated JWT External Authentication plugin configuration validates a JWT with a lifespan of 3 minutes that was encoded using the symmetric HS256 algorithm with one secret key. If these settings work for you, see Step 3. of Configure a JWT External Authentication Method to generate this default configuration.

When the App SDK receives a request for authentication using an External Authentication Method, it sends the user ID and password to your RP server. Your RP Server must return a JWT with the outcome. The Digipass S3 JWT External Authentication plugin then attempts to validate this JWT.

Your RP Server must return a JWT with a claim set described in claim set. If this isn't possible then you must create a custom External Authentication plugin to validate the credential your RP Server does return.

The JWT External Authentication plugin depends on a JSON configuration object called jwt_config. If JWT validation succeeds, the API Server extracts the user name from the token's sub claim and forwards it to the Authentication Server. If JWT validation fails, the plugin raises an ExternalAuthException, which causes the API Server to respond with an HTTP status code 401: Unauthorized.

For security reasons, jwt_config must be configured differently for each tenant that uses the JWT External Authentication plugin. This allows the plugin to use a different key and other parameters for the JWT. You can easily generate a new jwt_config for each tenant with the default configuration. See Step 3. of Configure a JWT External Authentication Method to generate this default configuration.

Modify the JWT External Authentication plugin's jwt_config to do the following:

• Add your RP Server as a legitimate issuer so the plugin doesn't reject the JWT.

• Specify what algorithm and key to use to decode the JWT.

• Define where to find the key.

• Specify how long the JWT is valid.

For detailed instructions, see When to Modify a JWT Configuration Object. You can find documentation about jwt_config in Configuring JWT Generation and Validation. In addition, the Tutorial Web App contains a sample implementation of an external authentication method that uses password-based authentication to obtain the JWT.

The jwt_config object includes information related to the externally authenticated user.

When using JWT External Authentication, your RP Server, and not the API server, generates the actual JWT. For this reason the External Authentication plugin only uses the validate section of jwt_config. If you don't modify the default values for lifespan, algorithm and secret key, you can use the generate section of the jwt_config to help configure the RP Server to generate the JWT.

Password External Authentication Plugin

This plugin extracts userName and password from the API Server request and sends them to your RP Server's REST endpoint in an HTTP POST request. If the RP Server verifies the password, the Password External Authentication plugin forwards the userName to the Authentication Server. If the verification fails, the plugin raises an ExternalAuthException, which causes the API Server to respond with an HTTP status code 401: Unauthorized.

The Password External Authentication plugin uses a JSON configuration object called pwd_plugin_config. The fields in this object are described in the table below.

Here is an example pwd_plugin_config:

{
  "url": "https://MyRPServer.com/RestEndpoint",
  "apikey": "84839229",
  "connection_timeout": 10000,
  "read_timeout": 10000
}

For more information, refer to the sample implementation in PasswordVerificationServlet.java. This servlet is part of the gwtutorial Web App that ships with the Digipass S3 Web App SDK.