3DS Server Operation Manual

Client Certificates

Client certificates can be defined in 3DS Server Configuration under the DirectoryServer configuration element, under Scheme.

• ClientCertificateStore on level Scheme (XPath in 3dss-configuration.xml:/Scheme/DirectoryServer/ClientCertificateStore):

Points to a keystore containing a certificate and a private key which are used when sending requests to the Directory Server. These requests are: Preparation Request, Authentication Request, Results Response and Protocol Error. The ClientCertificateStore will be resolved from the Schema configuration.

Keystore and key pair

To generate the keystore and key pair execute the following command:

Replace the placeholders in the distinguished name (e.g. COMMON NAME) with the appropriate values for the Merchant or Acquirer.

Change the name of the keystore and the alias as you wish. For this and the following examples client.jks and client are used.

Important: The passwords for the keystore and the key have to be the same in order for the 3DS Server to be able to access the keystore and the key.

Certificate Signing Request (CSR)

The Certificate Signing Request (CSR) can be created with the following command:

This command creates the client.csr file from the previously created keystore.

Obtaining a signed certificate

The CSR (generated in the previous step) needs to be sent to the Directory Server for the given scheme in order to receive a valid signed certificate.

Certificate Import

Once the client.crt file is obtained from the Certificate Authority, it can be imported into the existing keystore.

First import the CA certificate as a trusted entry:

Then use the following command to import the client certificate:

NOTE: It is important that the certificate is imported under the same alias as the existing alias with the private key. (i.e. in this case the alias is "client")

Existing Private Key and Certificate Import

For migrating existing client private keys and certificates, export them to PKCS#12 format and then use the Java keytool to import them in JKS format.

Use openssl to create the PKCS#12 file (src.p12) from your client certificate (client.crt), the private key (client.key) and the CA certificate (ca.crt):

Then import the PKCS#12 file into a Java keystore:

Note: use the same password when exporting the PKCS#12 file and when creating the destination JKS keystore.

Client Certificate Renewal

When renewing a client certificate, the existing CSR can be sent to the CA in order to issue a new valid certificate for the same private key.

After the CA responds, the new certificate can be imported into the client keystore. In order not to overwrite any existing valid certificates, first list the available aliases in the keystore:

If the initial CSR is reused, the client private key already exists in the keystore and must be cloned under a new alias:

Note: private key password and keystore password must be the same.

Import the renewed client certificate (client-new.csr) under the newly created alias:

Server certificates

For 3-D Secure requests initiated by the DirectoryServer, the 3DS Server need to establish a secure connection with the DirectoryServer. The connection need to be secured using mutual authentication. The server certificates are signed by the DirectoryServer's CA. The Requestor shall configure the environment to validate the certificates sent by the DirectoryServer or ACS.

We recommend configuring a virtual host for each DirectoryServer configured in the 3DS Server Configuration. Here is an example of an Apache configuration with virtual hosts for each DirectoryServer. In this example, the host name is the same, but the port is different.

It can also be configured to have different host names on the same port, or different host names with different ports. It is important the host name for the virtual host to match with the hostname configured under threeDSServerUrl configured for each DirectoryServer in the 3DS Server Configuration.

Apache configuration with multiple virtual hosts with same host names

Apache configuration with multiple virtual hosts with same ports

Certificate import

Once the root.crt file is received, it can be imported into a keystore. Use the following command to import the root certificate:

On the prompt, when asked if this certificate should be trusted, enter: yes.

Verify that the certificate and the alias have been added to the keystore:

Root certificate renewal

If the root certificate is nearing the expiration date, a new certificate may be added to the respective keystore.

Given a keystore file named "trusted-root.jks", first list all aliases in the keystore:

Given new certificate file named "new-certificate.crt", existing alias name "root" and new alias "root-new", importing the certificate is done with the following command:

On the prompt, when asked if this certificate should be trusted, enter: yes.

Verify that the certificate and the alias have been added to the keystore:

Root certificate changed

If the root certificate is no longer valid, it should be removed from the keystore and a new valid certificate should be imported.

Given a keystore file named "trusted-root.jks", first list all aliases in the keystore:

Given new certificate file named "new-certificate.crt" and existing alias name "root" first we remove the old invalid certificate.

Then we import the new valid certificate:

On the prompt if this certificate should be trusted, enter: yes.

Verify that the certificate and the alias have been added to the keystore:

Entity configuration (Merchants, Acquirers and Schemes)

Refer to the 3DS Server Configuration documentation for details about the configuration format.

Configuration properties

Refer to the 3DS Server Configuration Properties documentation for details about the configuration options.

Retry mechanism for Preparation Request and Authentication Request to the Directory Server

Directory servers can be configured with multiple directory server endpoints, so that in case of a failure in one - 3DS Server can try contacting the next available endpoint.

According to the EMVCo 3-D Secure specification for Preparation and Authentication requests, if a timeout has occurred while invoking the request to the DirectoryServer , the 3DS Server will retry using the next available endpoint. If only one endpoint is configured for the DirectoryServer, the same one will be used in the retry attempt.

For Preparation requests, when the retry mechanism is triggered, the 3DS Server will send the PReq message to the DirectoryServer in an interval of 60 seconds until a message is received from the DirectoryServer. Then it will switch back in a normal mode of operation.

Reloading the 3DS Server Configuration at runtime

The 3DS Server supports reloading the 3DS Server Configuration without restarting it.

NOTE: The 3DS Server exposes an endpoint http://<host>:<port>/reload/config which can be used to reload the configuration using a HTTP POST request. An additional dryRun=true request parameter can be sent to the endpoint to have the 3DS Server only validate the 3DS Server configuration without actually reloading it.

For convenience, the 3dsctl.sh script can be used with the following command to validate the 3DS Server configuration:

After the new configuration has passed the validation, the 3DS Server Configuration can be reloaded with the following command:

NOTE: The script will parse the node-$NODE_ID.properties found in the $THREEDS_HOME/conf folder to resolve the port. In case the node ID parameter is not passed, the 3DS Server will resolve the node ID to 1. If the server.port is not configured in $THREEDS_HOME/conf/node-1.properties, the 3DS Server will try to resolve it from $THREEDS_HOME/conf/application.properties. It will then send an HTTP POST request (using curl) to the config-reloading-endpoint.

NOTE: The configtest and configreload commands apply to only one 3DS Server node. The -n option is used to specify the 3DS Server node that should reload the configuration. In a setup with more than one 3DS Server node, the reloading of the 3DS Server Configuration must be performed on all nodes. Before issuing the configreload command, make sure that all 3DS Server nodes use or have the same 3DS Server Configuration.

Reloading the 3DS Server License at runtime

The 3DS Server supports reloading the 3DS Server License without restarting the 3DS Server.

NOTE: The 3DS Server exposes an endpoint http://<host>:<port>/reload/license which can be used to reload the license using an HTTP POST request. An additional dryRun=true request parameter can be sent to the endpoint to have the 3DS Server only validate the 3DS Server license without actually reloading it.

For convenience, the 3dsctl.sh script can be used with the following command to validate the 3DS Server license:

After the new license has passed the dryRun reloading, the 3DS Server License can be reloaded with the following command:

NOTE: The script will parse the node-$NODE_ID.properties found in the $THREEDS_HOME/conf folder to resolve the port. In case the node ID parameter is not passed, the 3DS Server will resolve the node ID to 1. If the server.port is not configured in $THREEDS_HOME/conf/node-1.properties, the 3DS Server will try to resolve it from $THREEDS_HOME/conf/application.properties. It will then send an HTTP POST request (using curl) to the license-reloading-endpoint.

NOTE: The licensetest and licensereload commands apply to only one 3DS Server node. The -n option is used to specify the 3DS Server node that should reload the license. In a setup with more than one 3DS Server node, the reloading of the 3DS Server License must be performed on all nodes.

Access permissions

You should protect the 3DS Server Configuration file using Unix file permissions as it contains keystore passwords.

Make sure the user running the 3DS Server application is still able to read the file.

Password encryption

Keystore passwords in the 3DS Server Configuration can be encrypted.

The encrypted passwords must be created using the 3dstool script as follows:

As additional precaution, if using same password in multiple occurrences, run the tool for each occurrence to generate a different encrypted value.

To make the 3DS Server application aware of using encrypted passwords, you have to set the corresponding 3DS Server Configuration Property:

The default value for this property is false, meaning that plain-text passwords are used. When using the 3DS Server with database configuration, keystore passwords are always encrypted.

Key rotation

Database configuration

Steps bellow can be followed to rotate the encryption key for database configuration:

Define or change the active key alias and its keystore properties in application.properties file in $THREEDS_CONFIG_HOME. Find more information in 3DS Server Configuration Properties.

Restart 3DS Server nodes.

Define or change the active key alias and its keystore properties in application.properties file for 3DS Server Admin application. Find more information in 3DS Server Admin Configuration Properties.

Restart 3DS Admin application.

Re-encrypt database content with 3DS Server CLI Tool by running the following command:

Find more information in 3DS Server CLI Tool operation manual.

XML configuration

Steps bellow can be followed to rotate the encryption key for XML configuration:

Re-encrypt each encrypted value from configuration by running the following command:

Find more information in 3DS Server CLI Tool operation manual.

Define threedss.encryption.* properties in application.properties file in $THREEDS_CONFIG_HOME. Find more information in 3DS Server Configuration Properties.

Restart 3DS Server nodes.

3DS Server exposed HTTP endpoints

3DS Server Dashboard endpoints

3DS Server exposes the following endpoints to which access should be restriced from within the organization environment:

• http(s)://<host>:<port>/admin/dashboard
• for more information see 3DS Server Dashboard

3-D Secure endpoints

3DS Server exposes the following endpoints to which access should be restricted from within the organization environment:

• http(s)://<host>:<port>/3ds/versioning
• for more info see 3-D Secure Versioning samples
• http(s)://<host>:<port>/3ds/authentication
• for more info see 3-D Secure Authentication Request samples
• http(s)://<host>:<port>/3ds/challenge-cancelled
• for more info see Challenge Cancelled Request samples
• http(s)://<host>:<port>/actuator/metrics

3-D Secure externally exposed endpoints

3DS Server exposes the following endpoints to which access should be allowed (invoked from the ACS and DS systems):

• https://<host>:<port>/3ds/3ds-method-notification/
• https://<host>:<port>/3ds/results-request
• https://<host>:<port>/3ds/challenge-response

Session replication

You can use the 3DS Server's support for session replication, where EhCache is used as a session replication service.

For details about session replication configuration with the 3DS Server, refer to the Ehcache Configuration documentation.

When using session replication, every 3DS Server node in the cluster may process any request of a 3-D Secure transaction. I.e. every node can resume sessions started on another node.

Obtain info from the log files

Search the log files using grep command (refer to Log4j2 Configuration documentation for location of the log files).

• Find error by error description

• Get all log messages connected to 3DS Server Transaction ID

• Navigate to some exception in app.log

and search for string (e.g /DsAresValidationException)

• Navigate to some date

and search for date (e.g /2018-04-03 14:39:51,436)

Prometheus Metrics

The 3DS Server provides extensive logging by Prometheus and you can setup a Grafana dashboard to have maximum insight into the server activity.

The prefix "app_3ds-server" is used for all metrics. What follows after that is determined by the version, it can be "3ds2", "3ds1" or "upop". After the version comes the name.

In release 2.3.0.0 the old metrics were replaced with new ones. The old metrics are deprecated and will soon be removed.

The following table shows all metrics sent to Prometheus by the 3DS server.

The following table shows deprecated metrics that have no replacement.

Query metrics

You can use Grafana or Prometheus UI to query metrics.

Grafana

• Go to your Grafana Dashboard → Explore and switch to "Prometheus" in the dropdown at the top.
• Select "Metrics" from the dropdown next to the query input.
• Enter the metrics name and execute query.

Prometheus UI

• Go to Prometheus.
• Enter the metrics name you want to query and execute.

3DS Server Dashboard

The 3DS Server provides a HTML dashboard reachable under /admin/dashboard.

The dashboard shows information about:

• Performance and failure statistics
• Errors
• Configuration
• License

Note that performance and exceptions statistics will be lost when the 3DS Server application is restarted.

Transactions dashboard

The transactions dashboard shows statistics for /3ds/* exposed endpoints and preparation requests. It displays number of requests, average, max and min and total time of each category.

Exceptions dashboard

The exceptions dashboard shows the type and number of exceptions that occurred in the 3DS Server

Acquirers configuration

The acquirers configuration tab shows each configured acquirer information including configured acquirer BINs. Each acquirer is shown in a separate visual container, and each BIN associated to the acquirer is displayed with the scheme and acquirerBIN value.

Merchants configuration

The merchants configuration tab shows each configured merchant information including merchant acquirer configuration. Each merchant is shown in a separate visual container and the associated acquirers are displayed in individual accordion containers, with a header showing the acquirer merchant name.

Scheme configuration

The scheme configuration tab shows each configured scheme, including Directory Server configuration. Each scheme is shown in a separate visual container.

URL configuration

The URL configuration tab displays the configured URLs for notification, results response notification, challenge response notification, 3DS Requestor and 3DS Method Notification.

License information

The license information tab shows information for the 3DS Server license, including licensed version and expiry date.