3DS Server Operation Manual

Starting/Stopping the 3DS Server

Use the 3dsctl script to start or stop a 3DS Server node.

Run the script with the -h option to learn about the available options and commands:

Logging

Refer to the Log4j2 Configuration documentation.

Credentials

The 3DS Server application uses TLSv1.2 client and root certificates.

The configuration of the 3DS Server client certificates depends on the 3DS Server Configuration type. When the 3DS Server uses database persisted configuration, the 3DS Server Admin Web application can be utilised for the certificates configuration. The 3DS Server Admin Web application allows:

Generating Certificate Signing Request (CSR) (for an existing certificate renewal or for a new certificate)
Importing signed certificate in the certificate store
Importing/Exporting client certificate store in Java KeyStore (JKS) format
Removing certificates

Visit 3DS Server Admin Client Certificate Store configuration for the procedure of configuring and managing the 3DS Server client certificate store.

When using 3DS Server XML configuration, the 3DS Server TLSv1.2 client and root certificates are stored in Java KeyStore (JKS) format. Keystore files, once created and populated, need to be referenced for usage in the 3DS Server Configuration file as part of the DirectoryServer configuration.

For creating and managing keystores, Java keytool is used. The keytool is part of the Java Development Kit (JDK).

The keytool expects certificates to be imported in either DER format or PEM format (Base64 encoded DER format).

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

Trust and Root certificates

3DS Server has only one type of root and trust certificates, that is defined under TrustCertificateStore in the following path in the 3dss-configuration.xml:

/Scheme/DirectoryServer/TrustCertificateStore

The TrustCertificateStore is used to store the root Certificate Authority (CA) certificates. If the root CA certificate is a public certificate already trusted by JAVA, this keystore may be omitted.

The TrustCertificateStore may contain the DirectoryServer CA certificate, just to separate the CA certificates from the client certificates.

TrustCertificateStore configuration may also reference the same keystore file as the ClientCertificateStore configuration.

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:

3DS Server configuration

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>/admin/configuration/reload-cache which can be used to reload the configuration using a HTTP GET request. If the 3DS configuration is not valid, it won't be reloaded with an error response explaining the validation failures.

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

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 GET request (using curl) to the configuration reloading endpoint.

NOTE: The configreload command applies 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.

Security

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

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
http(s)://<host>:<port>/3ds/v4/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

Errors and troubleshooting

Exceptions are logged to the 3DS Server application log (see Log4j2 Configuration for details) on level ERROR.

For every exception during request processing, an error code is set so that can be used to categorize the error.

Refer to the EMVCo 3-D Secure documentation for a description of the error codes used by the 3DS Server.

For most error codes the merchant can not intervene. In frequent cases of timeouts when communicating with the Directory Server or while waiting for a response from the DirectoryServer, increasing the corresponding timeout should be considered (see also 3DS Server Configuration).

Reporting

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)

Monitoring the application and gathering metrics

In order to monitor the application, the 'metrics' and 'health' endpoints are publicly exposed and available on http(s)://<host>:<port>/actuator/metrics and http(s)://<host>:<port>/actuator/health. However, these endpoints should be restricted from within the organization environment.

There are Spring built-in metrics, as well as several 3DS Server specific metrics. The metrics provide info about:

Number of requests handled by the application
Duration of request processing on 3DS Server side as well as the duration of the 3DS Server - Directory Server communication per request
Number of exceptions occurred, distinguished by their type and the message flow in which they occurred (PREPARATION, AUTHENTICATION, RESULTS, etc).

Each particular metric can be accessed via http(s)://<host>:<port>/actuator/metrics/<metric-name>.

There is a possibility to publish the metrics on a third-party monitoring systems which allow visualization and querying of the results, math operations, etc.. The Prometheus monitoring system is incorporated with the 3DS Server, but is disabled by default. In order to enable it set the management.metrics.export.prometheus.enabled property to true and add the prometheus endpoint to the publicly exposed actuator endpoints property - management.endpoints.web.exposure.include in 3DS Server Configuration Properties.

Upon request, other monitoring systems such as Atlas, Datadog, etc. can be incorporated with the 3DS Server.

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.

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

Name	Description	Tags	Percentiles
app_3ds-server_3ds2_versioning	Measures 3DS2 versioning requests processing duration.	orgName	✓
app_3ds-server_3ds2_method-notification	Measures 3DS2 handling of 3DS Method response sent by the ACS duration.	orgName	✓
app_3ds-server_3ds2_authentication	Measures 3DS2 Authentication Request processing duration.	orgName	✓
app_3ds-server_3ds2_authentication_ds	Measures 3DS2 sending of the Authentication Request to the Directory Server duration.	dsUrl	x
app_3ds-server_3ds2_preparation	Measures 3DS2 scheduled Preparation Requests processing duration.	orgName	x
app_3ds-server_3ds2_preparation_ds	Measures 3DS2 sending of the Preparation Request to the Directory Server duration.	dsUrl	x
app_3ds-server_3ds2_results	Measures 3DS2 Results Requests processing duration.	orgName	x
app_3ds-server_3ds2_challenge	Measures 3DS2 handling of Final Challenge Response sent by the ACS duration.	orgName	✓
app_3ds-server_exceptions	Exception counter.		x
app_3ds-server_3ds1_pareq-creation	Measures 3DS1 paReq creation duration.	orgName	✓
app_3ds-server_3ds1_pareq-creation_ds	Measures 3DS1 sending of the Verify Enrollment request to the Directory Server duration.	dsUrl	x
app_3ds-server_3ds1_pares-validation	Measures 3DS1 paRes validation duration.	orgName	✓
app_3ds-server_upop_authreq-creation	Measures UPOP authReq creation duration.	orgName	✓
app_3ds-server_upop_authres-validation	Measures UPOP authRes validation duration.	orgName	✓
app_3ds-server_upop_authstatus-inquiry	Measures UPOP Auth Status Inquiry processing duration.	orgName	✓
app_3ds-server_upop_authstatus-inquiry_out	Measures UPOP sending of the Auth Status Inquiry request to the Directory Server duration.		x
app_3ds-server_3ds2_oreq-data-cleanup-scheduler_start-time	Measures the last start time of the Operation Data cleanup scheduler execution.		x
app_3ds-server_3ds2_results-data-cleanup-scheduler_start-time	Measures the last start time of the Results Data cleanup scheduler execution.		x
app_3ds-server_3ds2_results-response-data-cleanup-scheduler_start-time	Measures the last start time of the Results Response Data cleanup scheduler execution.		x
app_3ds-server_3ds2_threeds-method-data-cleanup-scheduler_start-time	Measures the last start time of the ThreeDs Method Data cleanup scheduler execution.		x
app_3ds-server_3ds2_preq-scheduler_start-time	Measures the last start time of the Preparation Request scheduler execution.		x
app_3ds-server_3ds2_card-range-cache-updater_start-time	Measures the last start time of the Card Range Cache update scheduler execution.		x
app_3ds-server_3ds2_ds-url-cache-updater_start-time	Measures the last start time of the DsUrl Cache update scheduler execution.		x
app_3ds-server_config-cache-reload-scheduler_start-time	Measures the last start time of the Configuration Cache Reload scheduler execution.		x
app_3ds-server_3ds1_session-data-cleanup-scheduler_start-time	Measures the last start time of the ThreeDsOne Data cleanup scheduler execution.		x
app_3ds-server_upop_session-data-cleanup-scheduler_start-time	Measures the last start time of the UPOP Session Data cleanup scheduler execution.		x

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.

Grafana

Prometheus UI

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

Prometheus