Pre-implementation Recommendations

1. Designing Your Deployment

1.1. Data stored in the Digipass S3 Server

The stored operational data includes:

• System policies and properties: Critical information that determines whether authentications are allowed or disallowed. This also includes system configuration information required for Digipass S3 Server operation.

• Registration data: Information necessary for verifying user authentications.

• Transient data: Temporary data used for client interactions.

Authentication Server versions before 5.2.0 did not store transient data in the database.

Specify the Operational Database during installation. Refer to section Step 3. Setup the Installation Properties File.

1.2. Data Storage Planning

Data Rate

Content for databases internal to the Digipass S3 Server at the following rates:

• Operational Data:

  • 5.5KB per reg

  • 0KB per auth

• Transient Data:

  • 6KB per reg

  • 6KB per auth

Given the volume of data that can be generated for registration and transient data, it’s important to ensure that you have enough capacity to support several years worth of data. This section contains formulas for estimating the storage you need for the Digipass S3 database(s) internal to your deployment. First we calculate the storage needs of the Operational Database.

The Data Rate above states that an authentication operation does not add a new record to the Operational Database. Every auth operation does update an existing database record, but that update does not usually add to the size of the record. There are 3 exceptions:

• If you enable an extension such as location, IP address etc. then the database inserts approximately 2KB of extension data only when the user authenticates for the first time.

• If you enable AppAttest or Google Play Integrity, and the user authenticates using a synced passkey or security key from a new device, the database inserts approximately 3.5KB for the App Attest and Google Play Integrity data.

• If the user authenticates using a synced passkey or security key from a new device, the database inserts approximately 0.5KB for the new device information.

Operational Database Storage Requirements

Based on the Data Rate above, begin by estimating the average number of daily registrations you expect to see for your apps. Then use the following formula:

Estimated size of the operational data:
OpDataSize = (NumYears * 365) * (5.5KB * AvgDailyReg)

This formula assumes that you observe the data purging recommendations for transient data described in Database Management.

Operational data size calculation example:

Three years of 10,000 registrations per day generates 60.225GB of operational data (primarily registration data):

OpDataSize = (NumYears * 365) * (5.5KB * AvgDailyReg)

OpDataSize = (3 * 365) * (5.5KB * 10000)

OpDataSize = 1095 * 55000KB

OpDataSize = 60.225GB

Recommendation

To allow headroom for maintenance needs, such as backups and schema upgrades, double the estimated sizes for operational data to calculate the minimum disk size. Use the following formula to estimate your database storage needs for the Operational Database. In addition, be sure to follow database-specific best practices to plan your database storage.

Minimum data storage for the Operational Database:

Minimum storage estimate = 2 * OpDataSize or
2 * (NumYears * 365) * (5.5KB * AvgDailyReg)

Ensure that the performance characteristics, specifically input/output operations per second (IOPS), of the disk storage meets your performance needs. For example, for a sustained rate of 500 authentications/sec at an average of 100ms/authentication, you need an SSD of 3000 IOPS or higher. Refer to the Digipass S3 Server Performance Benchmarks technical note.

1.3. Database Replication

The Authentication Server, API Server, and CLI nodes require access to the Operational Database. If one Operational Database is not available, the servers should be able to access a second Operational Database automatically. This is commonly done through a load balancer. The servers access the databases through a VIP (Virtual IP), which is an IP address of a load balancer that checks database availability and routes traffic accordingly. See Figure 2 Site with Recommended Load Balancers.

Considerations for DB replication

An active-standby configuration is sufficient and recommended for all deployments. In this configuration, the data is replicated to the standby/secondary database. If the primary database becomes unavailable for any reason then the secondary database becomes the active/primary and all new authentication operations continue to work against this database.

See the following advantages and disadvantages of two approaches:

You may have concerns about switching to the secondary database in an active-standby configuration. Switching could affect the latest data availability during any failover because replication may be affected. However, given the design of the Authentication Server, this latency is unlikely to affect any new authentications.

An authentication operation relies on the presence of data associated with its corresponding registration. Registration is not as frequent as authentication. Users register for a new FIDO authentication once per device that they use. If registration data has been replicated, any authentication with available registration data succeeds. Since registration is performed in an authenticated session, users don't typically authenticate immediately after registration and would not be affected by failover replication latency. Note that any authentication operations in progress during a database failure event may be affected in this configuration. In the worst case, users would need to authenticate again.

Recommendation

Replicate your database(s), as shown in the diagram below:

• Operational Database, replicated

• Use active-standby database replication

  

Figure 1 Authentication Server Cluster with Replicated Operational Database

1.4. Authentication Server

You can deploy multiple Digipass S3 Authentication Servers in a cluster to handle load and increase fault tolerance. The Authentication Server is designed to be stateless and FIDO messages can pass through any Authentication Server. These servers are CPU intensive. Select the appropriate configuration of machines or virtual instances for your load and performance requirements by referring to the Digipass S3 Server Performance Benchmarks technical note.

An Authentication Server with recommended hardware can process 500 authentications per second. This assumes that the database is well-tuned for the load. Your cluster should have enough Authentication Servers to handle the peak load, plus some additional capacity. For example, if you expect a peak load (maybe 10% of your user base) of 1000 authentications/second with a processing speed of 500 authentication/second per server, the minimum design would have three Authentication Servers (3 servers x 500 authentications per second per server = 1500 authentication per second). However, it is always good to add extra capacity for resiliency in case one server is not available.

You should have the same number of Digipass S3 API Server nodes as Authentication Server nodes in your cluster.

Recommendation

Calculate the number of authentication servers in a cluster using the following formula:

Number of servers = (peak authentication load/ server authentication processing rate) + 1

• Peak authentication load: Estimate from past data, if available.

• Server authentication processing rate: With the recommended hardware, use 500 authentications/second as the baseline processing rate. Contact Digipass S3 about an expected processing rate if you plan to use significantly different hardware.

Consult the Digipass S3 Server Performance Benchmarks technical note for the latest performance data.

1.5. Cache Configuration

The Authentication Server loads a FIDO policy or Adaptive Ruleset from the database into a memory cache when that ruleset or policy is first referenced by an API call. By default, the ruleset or the policy remains in cache until the server stops. Also by default, there is no limit on the number of rulesets or policies loaded into the cache. For a large deployment with a large number of policies and rulesets, you can configure size-based or time-based eviction of policies and rulesets from the cache using the two system properties in the table below.

Setting these properties is especially useful in containerized deployments where available memory per container may be limited. You may have to try different settings in your test environment to determine optimal values that suit your deployment. Depending on the complexity of a ruleset and available hardware resources, it may take a significant amount of time to load a ruleset into the cache. Use the highest settings that work for your deployment to minimize early eviction of rulesets.

Recommendation

• If you have a large number of FIDO policies and Adaptive Rulesets in your deployment, use the cache configuration settings to ensure optimal memory usage and performance.

• Use the highest settings that work for your deployment to minimize early eviction of policies and rulesets.

1.6. Admin Server

You can deploy multiple Digipass S3 Administration Servers in a cluster to handle load and increase fault tolerance. The Admin Server is responsible for purging transient data. The Admin Server must be able to communicate with both the API Server and the Auth Server.

Recommendation

Install the Admin Server on at least two nodes in your deployment.

1.7. Command-line Tools

Digipass S3 provides several command-line tools that you use to install the product, run pre and post installation checks, encrypt passwords, update or fetch metadata, and perform administrative operations. Because these tools can access sensitive functions, they should be isolated on one node (CLI node) in your deployment. Bring this node up only when you need to run one of the tools.

Recommendation

Your deployment should have one dedicated node where you've installed command-line tools.

1.8. Load Balancing

Load balancing allows you to scale API Servers, Admin Servers, and Authentication Servers horizontally. New Authentication Server nodes can be added to the cluster to increase throughput and reduce response time. Also, since the Authentication Server performs mostly cryptographic operations, it is mainly CPU bound and scales vertically. Machines with faster CPUs or additional cores can be used to increase throughput and decrease response time. You should have the same number of Digipass S3 API Server nodes as Authentication Server nodes in your cluster.

Figure 2 Site with Recommended Load Balancers

Use an API gateway solution to protect the API requests to the Digipass S3 API Servers. The API gateway may also function as a load balancer, depending on the cloud platform vendor. API gateways provide edge-level security with policy-based checks that allow request filtering based on request headers and payloads. For example, a client application using the Digipass S3 App SDK sends requests to the server that include client-specific information in the request. These requests are checked at the API gateway level and only the requests originating from certain clients are allowed through. The API gateway can also be used to throttle requests from clients to address denial of service attacks.

Recommendations

For optimal cluster performance, configure your cluster with three load balancers and a failover router, as shown in the diagram above.

• Use an API gateway between incoming traffic and the load balancer for the API Server nodes.

• Place one load balancer between the API gateway and the API Server nodes, unless the API gateway also serves as a load balancer.

• Place an internal load balancer between the API Server nodes and the Authentication Server nodes.

• Place another internal load balancer in front of the Admin Server nodes.

• Place a failover router between the Authentication Server nodes and the replicated Operational Databases.

If your cluster only contains one Authentication Server, you won’t need load balancing.

1.9. Disaster Recovery

Implement your load-balanced cluster in a secondary site in case the first site is not available. Replicate the databases between the sites. Start the standby Admin Server in case of failover from active to standby. In the diagrams below, the NNL server icon represents the entire Digipass S3 Server cluster that includes the Authentication, API, Admin, and command-line-tools servers.

Locate sites in different geographic areas to avoid natural or man-made disasters taking down both sites. Cloud vendors offer different geographical regions and zones. Database replication between sites is subject to latency and there could be minimal loss of the most recent updates, depending on where your sites are located and network speed. Your company needs to make a choice balancing network speed vs. cost. Some cloud vendors automatically take care of replication within a region but leave replication between regions up to the client. You can choose to use a cloud-managed database service rather than deal with database replication across regions. Active-standby configurations are recommended since the design simplifies the database replication requirements and can also be used to test upgrades in a production environment. For example, the standby site can be upgraded and tested without affecting the traffic on the active site.

There are different load balancers available to direct traffic between sites. Examples include 3DNS, Google Cloud Load Balancing, and Amazon Route 53 Geolocation Routing Policies. Traffic can be routed between sites depending on site availability, load, and distance.

Figure 3 Two Sites with Database Replication Between Them

Figure 4 Two Sites with Databases in a Cloud-managed Database Service

Recommendations

• Replicate your Digipass S3 Server cluster (or site) so operations can failover to the second site if there’s a problem with the first site.

• Use an active-standby configuration since it simplifies the database replication requirements and production upgrade tests.

• Start the standby Admin Server in case of failover from active to standby.

• Replicate your site in a different geological region.

• If you don’t want to deal with database replication between sites, use a cloud-managed database service.

2. Before Installation

2.1. Secure Tomcat

Always create a specific user to run the Tomcat process with only the minimum permissions for operating system functions. Do not use the root user because this poses security risks to the Tomcat server.

The standard Tomcat installation comes with default samples and test applications. Remove them if you don't plan to use them. You can find them in the $tomcat/webapps folder. Leaving them on your Tomcat server can enable an attacker to exploit their known vulnerabilities.

There are several configuration changes you can make to server.xml, such as enabling SSL/TLS, disabling TRACE requests, disabling SSLv3 to prevent POODLE attacks, and so on. Apache provides a useful guide that covers important security considerations at https://tomcat.apache.org/tomcat-10.1-doc/security-howto.html

Recommendations

• Do not run Tomcat as the root user.

• Remove default sample and test applications.

• Review other ways to secure your Tomcat server at https://tomcat.apache.org/tomcat-10.1-doc/security-howto.html.

2.2. Limit the Size of POST Requests to Digipass S3 Servers

While there is no hard limit on the amount of data that can be sent in a POST request, you should limit the size of a POST request to the smallest amount of data needed to provide necessary information. This ensures optimal network performance and response times from your servers and apps. Use your load balancers or the reverse proxy server to enforce size limits for POST requests. Position these devices or servers in front of the Digipass S3 Auth Server, API Server, and Admin Server.

Recommendations

Configure the load balancer or the reverse proxy server that is in front of the Digipass S3 Auth Server, API Server, and Admin Server to limit the size of POST requests.

2.3. Configure Your Network to Only Allow Necessary Traffic

Lock down your deployment so that your firewall only allows necessary inbound and outbound traffic.

Recommendations

• Set the default firewall configuration to "DENY ALL" outbound traffic.

• Make a list of the IP addresses for the internet service endpoints with which you need to communicate. Include the DNS resolver, the SMTP server for email notifications, and the APNS endpoint used when sending push notifications.

• Update the firewall rules to only allow outbound communication from specific ports to the endpoints on your list.

• Allow outbound communications to come only from the systems where they are needed by specifically listing the subnet ranges or IP addresses of those systems.

• Make use of a proxy-based content filtering mechanism to monitor and block any content that is considered to be in violation of your company policies.

• Ensure that DNS requests are sent only to the IP addresses of trusted DNS resolvers.

2.4. Secure the Communication Between Components

Some companies have security policies that require Transport Layer Security (TLS) connections between network devices such as the API Server, the Authentication Server, and the database. TLS between devices is supported and is implemented by exporting and importing the respective certificates into the partner keystore, followed by updating the Tomcat configuration. For example, implementing a TLS connection between the API Server and the Authentication Server would use the following steps:

1. Create keystores on the server-side (Authentication Server) and client-side (API Server).

2. Export the certificate from the client keystore and import it into the server keystore.

3. Export the certificate from the server keystore and import it into the client keystore.

4. Verify that the certificates were added correctly to the appropriate keystores.

5. Configure Tomcat to enable Client Authentication using the server keystore.

For more information about TLS configuration, ask Digipass S3 Support for the Using Certificates for Communication Between Servers Technical Note.

Recommendation

If your company requires TLS among routers, servers, and proxies, you can implement a TLS connection between Digipass S3 Server-side components. However, note that TLS encryption has a small impact on the performance of the authentication process due to cryptographic and connection setup operations.

2.5. Enable Supported Algorithms in TLS

When you configure the server that hosts Digipass S3 API Server, enable TLS 1.2 and higher with all supported algorithms required by iOS App Transport Security (ATS.) See Requirements for Connecting Using ATS. iOS applications require TLS 1.2.

Recommendation

Ensure that your iOS application works with the API Server by enabling TLS 1.2 and higher with all algorithms required by iOS App Transport Security (ATS.)

2.6. Secure the Server Credentials

During installation, encrypt database passwords and other credentials used by Digipass S3 Servers using Digipass S3’s encryption script. By default, Digipass S3 Servers use an internal encryption key that is the same across different installations. Replace the default key with a custom key by assigning the custom key to the NNL_PKEY system environment variable. Refer to the section Step 4. Encrypt Credentials Used by the Server.

To further enhance the security of your deployment, Digipass S3 provides programmatic interfaces that support the use of an external secret management system and an external cryptographic service. Digipass S3's Secrets Plugin retrieves keys and passwords for databases, push notification services, email, SMS, and PhotoID services from an external secrets store. For more information, see Crypto and Secrets Plugin. Digipass S3's Crypto Plugin allows you to perform cryptographic operations such as encryption, decryption, and signing using an external cryptographic service. For more information, see Crypto and Secrets Plugin.

Prevent Internet traffic from directly accessing the Authentication Server. To address this, route traffic to the Digipass S3 API Server or proxy. The Digipass S3 API Server or proxy verifies the request before forwarding the REST API call to the Authentication Server.

Recommendations

• Encrypt database passwords using your own custom encryption key.

• Consider using external services for secret management and cryptographic operations.

• Where possible, ensure that traffic to the API Server comes from your application and is not directly open to the Internet.

2.7. Specify the Character Encoding for the Database

To allow Unicode characters to be stored in the database, specify the character encoding to use when you create the database. Digipass S3 recommends the UTF-8 encoding. Before You Begin provides examples of database creation commands that designate UTF-8.

Recommendation

Provide the UTF-8 character encoding when you create the database.

3. After Installation

3.1. Allowed Authenticators

Determine which authenticators you do and don't want your end-users to use. The metadata for UAF authenticators are shipped with Digipass S3 Software and imported automatically during installation. You need to download FIDO2 and U2F authenticator metadata from the FIDO Metadata Service and then import it into your Digipass S3 deployment in order for your customers to use them.

See Authenticator Metadata Commands for instructions on how to use the command line interface nnl-mgmt.sh to download and then import authenticator metadata. Review the report generated during the download and only import the metadata for authenticators you wish to allow.

Recommendations

• Identify the smallest list of authenticators you expect to support/allow.

• Import the metadata for only the authenticators you want your end-users to use.

3.2. Adaptive Rules and FIDO Policies

Adaptive Rules and FIDO Policies control the authentication behavior of your applications. Adaptive Rules enable you to tailor an authentication response by using data provided by your app, a small set of user history, and criteria and guidelines from your organization. When a rule's decision is to authenticate a user, the rule gets the list of allowed authenticators from a FIDO policy.

FIDO policies enforce your organization's choice of valid FIDO authenticators when a user registers or authenticates. You can create different FIDO policies to restrict the FIDO authenticators for specific situations.

Carefully consider the types of authentication scenarios your users will require. Specify the FIDO2 authenticator attributes and the smallest list of UAF authenticators that will ensure secure user authentication. Then use the Server Administration Console (Admin Console) to create your Adaptive Rules, FIDO policies, and authenticator groups. You can also remove unnecessary authenticators from your authenticator groups. See Configure Adaptive Rulesets, and Create FIDO policies for details on creating Adaptive Rules and FIDO policies.

Each category of UAF authenticators has several associated Authenticator Attestation IDs (AAIDs). When you select an authenticator, you select a specific AAID. For example, the Android fingerprint authenticator has six AAIDs. Avoid selecting all AAIDs since some lack robust security. In addition, some AAIDs behave differently when a user needs to change a fingerprint or other biometric data, resulting in inconsistent behavior in your app.

Unlike UAF policies, FIDO2 policies do not require a list of valid authenticators. Instead, your policy specifies the authenticator attributes you want such as user verification or authenticator attestation. Digipass S3 Software supplies sample policies you can review.

Use the following questions to assist you in selecting the appropriate UAF and FIDO2 authenticators. We strongly suggest that you consult with Digipass S3 support to discuss these and other considerations.

1. In what countries do you plan to deploy?

2. What platform(s) do you want to support? Android / iOS / Web?

3. Do you want to support software keys? The most secure keys are generated by hardware, these are the only keys you should use in production systems. However, you can choose to use software keys for tests or during development.

4. What user verification modalities do you want? This is not just the UAF-defined modalities, but, for example, PIN versus Passcode.

5. What key deletion behavior do you want? You can choose to automatically delete a key if any fingerprint changes or an additional fingerprint is added.

6. On iOS, do you want to share keys across your apps? You must make modifications to your app before using these AAIDs.

7. What other devices do you plan to support?

Recommendation

Create Adaptive Rules and FIDO policies that use desired FIDO2 authenticator attributes and allowed UAF authenticator groups.

3.3. Allowed Apps

Verify that the list of allowed apps in the Authentication Server does not contain any test or sample apps that you implemented. Use the Server Administration Console to delete unneeded apps and add the apps you've implemented that need to communicate with the Server to register and authenticate users. See Configure Apps for how to edit the app list.

If any of your apps use a remote UAF FIDO client instead of the embedded client in the Digipass S3 App SDK, then you need to update the facets.uaf file. This file contains a list of valid apps and is shipped with the API Server. Modify facets.uaf to delete unneeded apps and add the apps you implemented that need to communicate with the API Server. For specific instructions, see Update facets.uaf.

Recommendations

• Include only the applications you are deploying in the Apps Configuration page in the Server Administration Console. Remove any sample or test applications.

• If you implemented an app that uses a remote UAF FIDO client, make similar changes to facets.uaf.

3.4. Securing Session and Transaction Management

The API Server’s default session and transaction plugins use a symmetric key and the HS256 algorithm to secure JSON Web Tokens (JWTs). The key is automatically generated during installation. You may choose to use a different key, a different symmetric algorithm, or an asymmetric algorithm. An asymmetric algorithm is more secure than a symmetric algorithm. For instructions on how to make these changes, refer to Updating the Algorithm and Key.

When you add a new tenant, generate a new key. Refer to section Step 3. Update the API Server Configurations.

Session management is essential to control access to the protected resources of registration, deregistration, and list registration. In the case of FIDO, the registration operation should be restricted to only known users who have already been identified. It is critical for the application infrastructure to determine if the user has an existing valid session before allowing registration to proceed. For example, session validity can be determined by validating JWTs or cookies that are sent to the user’s device when the user is authenticated.

After successful authentication, your Session Management system creates a session for the user. For example, the session can be established by sending a token or cookie via the REST API response to the user’s device once the user is authenticated. To understand how Digipass S3 Software uses JWTs for session management, see Understanding the Session Token.

Recommendations

• If possible, use an asymmetric algorithm to sign/encrypt your JWT. An asymmetric signing algorithm like RSA or ECDSA is more secure than a symmetric algorithm like HMAC.

• Generate a new JWT key when you add a tenant.

• Where possible, ensure a valid session is in place for registration, deregistration, and list registration APIs because these are protected resources.

3.5. Unused Plugins

The API Server’s Transaction plugin is optional. If your deployment doesn’t support transactions, remove the configuration for this plugin. If you use the Admin Console, refer to section Step 2. Activate the Transaction Plugin, except click Deactivate instead of Activate. If you don't use the Admin Console, refer to Transaction Plugin.

Recommendation

Remove configurations for the API Server Transaction plugin if your deployment doesn’t support transactions.

3.6. Personally Identifiable Information (PII)

With the advent of regulatory requirements protecting customers' private data, your apps must enable users to view and delete their sensitive data. The Authentication Server automatically stores the user’s login name/id, device information, app information, and authenticators for each user. You can configure the Authentication Server to store user location information.

To view the types of PII data stored by the Authentication Server, use the Admin Console. To control whether or not the Authentication Server stores user location, use the Admin Console or Digipass S3's command-line interface, nnl-mgmt.sh.

Using the Admin Console

1. Login and, if needed, switch to the desired tenant. Navigate to the Privacy panel, Configuration > Compliance > Privacy. This screen displays the types of PII data stored.

2. Click the value for Store Location Information to change it. True means the Auth Server stores location information.

Using nnl-mgmt.sh

Use the command below to store user location:

nnl-mgmt.sh properties set -name nnl.storage.extension.list -value noknok.uaf.location

Use the command below to disable storing user location:

nnl-mgmt.sh properties set -name nnl.storage.extension.list -value ""