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:
$ $THREEDS_HOME/3ds-server/bin/3dsctl.sh -h
Refer to the Log4j2 Configuration documentation.
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:
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 can be defined in 3DS Server Configuration under the DirectoryServer configuration element, under Scheme.
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.
To generate the keystore and key pair execute the following command:
keytool -genkey -alias client -keyalg RSA -keysize 2048 -keystore client.jks -dname "CN={COMMON NAME},O={ORGANIZATION},L={LOCATION},ST={CITY},C={COUNTRY}"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.
The Certificate Signing Request (CSR) can be created with the following command:
keytool -certreq -alias client -file client.csr -keystore client.jks
This command creates the client.csr file from the previously created keystore.
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.
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:
keytool -import -trustcacerts -alias ca -file ca.crt -keystore client.jks
Then use the following command to import the client certificate:
keytool -import -trustcacerts -alias client -file client.crt -keystore client.jks
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")
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):
$ openssl pkcs12 -export -out src.p12 -inkey client.key -in client.crt -certfile ca.crt
Then import the PKCS#12 file into a Java keystore:
$ keytool -importkeystore -srckeystore src.p12 -srcstoretype PKCS12 -destkeystore client.jks
Note: use the same password when exporting the PKCS#12 file and when creating the destination JKS keystore.
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:
keytool -list -keystore client.jks
If the initial CSR is reused, the client private key already exists in the keystore and must be cloned under a new alias:
keytool -keyclone -alias client -dest client-new -keystore client.jks
Note: private key password and keystore password must be the same.
Import the renewed client certificate (client-new.csr) under the newly created alias:
keytool -import -trustcacerts -alias client-new -file client-new.crt -keystore client.jks
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.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | <Location /3ds-server/3ds/results-request> # Require mutual authentication for the specified path SSLVerifyClient require</Location># Host name is the same in both VirtualHost configurations, the ports are different<VirtualHost hostname.3ds.server:443> SSLEngine on SSLCACertificateFile /path/to/scheme-1/server/certificate/3dss-ca-scheme1.crt SSLCertificateFile /path/to/scheme-1/server/certificate/3ds-server1.crt SSLCertificateKeyFile /path/to/scheme-1/server/certificate/3ds-server1.key</VirtualHost><VirtualHost hostname.3ds.server:11443> SSLEngine on SSLCACertificateFile /path/to/scheme-2/server/certificate/3dss-ca-scheme2.crt SSLCertificateFile /path/to/scheme-2/server/certificate/3ds-server2.crt SSLCertificateKeyFile /path/to/scheme-2/server/certificate/3ds-server2.key</VirtualHost> |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | <Location /3ds-server/3ds/results-request> # Require mutual authentication for the specified path SSLVerifyClient require</Location># Host names are different in both VirtualHost configurations, the ports are the same<VirtualHost scheme-1.hostname.3ds.server:443> SSLEngine on SSLCACertificateFile /path/to/scheme-1/server/certificate/3dss-ca-scheme1.crt SSLCertificateFile /path/to/scheme-1/server/certificate/3ds-server1.crt SSLCertificateKeyFile /path/to/scheme-1/server/certificate/3ds-server1.key</VirtualHost><VirtualHost scheme-2.hostname.3ds.server:443> SSLEngine on SSLCACertificateFile /path/to/scheme-2/server/certificate/3dss-ca-scheme2.crt SSLCertificateFile /path/to/scheme-2/server/certificate/3ds-server2.crt SSLCertificateKeyFile /path/to/scheme-2/server/certificate/3ds-server2.key</VirtualHost> |
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:
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.
Once the root.crt file is received, it can be imported into a keystore. Use the following command to import the root certificate:
keytool -import -trustcacerts -alias root -file root.crt -keystore trusted-root.jks
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:
keytool -list -keystore trusted-root.jks -alias root
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:
keytool -list -keystore trusted-root.jks
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:
keytool -import -trustcacerts -alias root-new -file new-certificate.crt -keystore trusted-root.jks
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:
keytool -list -keystore trusted-root.jks -alias root-new
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:
keytool -list -keystore trusted-root.jks
Given new certificate file named "new-certificate.crt" and existing alias name "root" first we remove the old invalid certificate.
keytool -delete -alias root -keystore root.jks
Then we import the new valid certificate:
keytool -import -trustcacerts -alias root -file new-certificate.crt -keystore trusted-root.jks
On the prompt if this certificate should be trusted, enter: yes.
Verify that the certificate and the alias have been added to the keystore:
keytool -list -keystore trusted-root.jks -alias root-new
Refer to the 3DS Server Configuration documentation for details about the configuration format.
Refer to the 3DS Server Configuration Properties documentation for details about the configuration options.
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.
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:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 configtest
After the new configuration has passed the validation, the 3DS Server Configuration can be reloaded with the following command:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 configreload
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.
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:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 licensetest
After the new license has passed the dryRun reloading, the 3DS Server License can be reloaded with the following command:
$ $THREEDS_HOME/bin/3dsctl.sh -n 1 licensereload
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.
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.
Keystore passwords in the 3DS Server Configuration can be encrypted.
The encrypted passwords must be created using the 3dstool script as follows:
$ $THREEDS_HOME/3ds-cli-tool/bin/3dstool.sh encrypt my_password
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:
$ threedsserver.configuration.use-encrypted-passwords=true
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.
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:
$ $THREEDS_HOME/3ds-cli-tool/bin/3dstool.sh re-encrypt-db
Find more information in 3DS Server CLI Tool operation manual.
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:
$ $THREEDS_HOME/3ds-cli-tool/bin/3dstool.sh re-encrypt-single <encrypted-field>
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 exposes the following endpoints to which access should be restriced from within the PSP environment:
http(s)://<host>:<port>/admin/dashboard
3DS Server exposes the following endpoints to which access should be restricted from within the PSP environment:
http(s)://<host>:<port>/3ds/versioning
http(s)://<host>:<port>/3ds/authentication
http(s)://<host>:<port>/3ds/challenge-cancelled
http(s)://<host>:<port>/actuator/metrics3DS 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-requesthttps://<host>:<port>/3ds/challenge-responseThe 3DS Server needs to maintain data between the versioning and authentication calls or the 3DS transactions. You should choose the session handling strategy that best suits your setup. Session replication can be used in a cluster setup where the 3DS Server internally maintains a session.
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.
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).
Search the log files using grep command (refer to Log4j2 Configuration documentation for location of the log files).
grep "Error while trying to communicate with the Directory Server." app.2018-04-03.log
grep f26f7244-e273-4bce-a0b8-d2cf096f7136 app*.log
app.log
less app.2018-04-03.log
and search for string (e.g /DsAresValidationException)
less app.2018-04-03.log
and search for date (e.g /2018-04-03 14:39:51,436)
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 PSP environment.
There are Spring built-in metrics, as well as several 3DS Server specific metrics. The metrics provide info about:
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.
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.
| Name | Description | Tags | Percentiles | Corresponding old metric |
| app_3ds-server_3ds2_versioning | Measures 3DS2 versioning requests processing duration. | orgName | ✓ | 3ds-server_versioning_requests_duration |
| app_3ds-server_3ds2_method-notification | Measures 3DS2 handling of 3DS Method response sent by the ACS duration. | orgName | ✓ | 3ds-server_3ds_method_notification_requests_duration |
| app_3ds-server_3ds2_authentication | Measures 3DS2 Authentication Request processing duration. | orgName | ✓ | 3ds-server_authentication_requests_duration |
| app_3ds-server_3ds2_authentication_ds | Measures 3DS2 sending of the Authentication Request to the Directory Server duration. | dsUrl | x | 3ds-server_ds_authentication_requests_duration |
| app_3ds-server_3ds2_preparation | Measures 3DS2 scheduled Preparation Requests processing duration. | orgName | x | 3ds-server_preparation_requests_duration |
| app_3ds-server_3ds2_preparation_ds | Measures 3DS2 sending of the Preparation Request to the Directory Server duration. | dsUrl | x | 3ds-server_ds_authentication_requests_duration |
| app_3ds-server_3ds2_results | Measures 3DS2 Results Requests processing duration. | orgName | x | 3ds-server_results_requests_duration |
| app_3ds-server_3ds2_challenge | Measures 3DS2 handling of Final Challenge Response sent by the ACS duration. | orgName | ✓ | 3ds-server_challenge_requests_duration |
| app_3ds-server_exceptions | Exception counter. | x | 3ds-server_exceptions | |
| app_3ds-server_3ds1_pareq-creation | Measures 3DS1 paReq creation duration. | orgName | ✓ | PaReqCreation |
| app_3ds-server_3ds1_pareq-creation_ds | Measures 3DS1 sending of the Verify Enrollment request to the Directory Server duration. | dsUrl | x | PaReqCreation_EnrollmentVerification_DsCommunication |
| app_3ds-server_3ds1_pares-validation | Measures 3DS1 paRes validation duration. | orgName | ✓ | PaResValidation |
| app_3ds-server_upop_authreq-creation | Measures UPOP authReq creation duration. | orgName | ✓ | AuthReqCreation |
| app_3ds-server_upop_authres-validation | Measures UPOP authRes validation duration. | orgName | ✓ | AuthResValidation |
| app_3ds-server_upop_authstatus-inquiry | Measures UPOP Auth Status Inquiry processing duration. | orgName | ✓ | AuthStatusInquiry |
| app_3ds-server_upop_authstatus-inquiry_out | Measures UPOP sending of the Auth Status Inquiry request to the Directory Server duration. | dsUrl | x | AuthStatusInquiry_SendInquiry |
The following table shows deprecated metrics that have no replacement.
| Name |
| PaReqCreation_InputValidation |
| PaReqCreation_EnrollmentVerification |
| PaReqCreation_EnrollmentVerification_ResponseValidation |
| PaReqCreation_EnrollmentVerification_ErrorNotification |
| PaResValidation_InputValidation |
| PaResValidation_PaResConversion |
| PaResValidation_MessageElementValidation |
| PaResValidation_SessionRetrieval |
| PaResValidation_TimeoutValidation |
| PaResValidation_MessageValidation |
| PaResValidation_MessageValidation_ResponseValidation |
| PaResValidation_MessageValidation_ErrorNotification |
| PaResValidation_MessageValidation_SignatureValidation |
| AuthReqCreation_InputValidation |
| AuthResValidation_InputValidation |
| AuthResValidation_ResponseValidation |
| AuthStatusInquiry_InputValidation |
| AuthStatusInquiry_ResponseValidation |
You can use Grafana or Prometheus UI to query metrics.
The 3DS Server provides a HTML dashboard reachable under /admin/dashboard.
The dashboard shows information about:
Note that performance and exceptions statistics will be lost when the 3DS Server application is restarted.
The transactions dashboad shows statistics for /3ds/* exposed endpoints and preparation requests. It displays number of requests, average, max and min and total time of each category.
The exceptions dashboard shows the type and number of exceptions that occurred in the 3DS Server
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.
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.
The scheme configuration tab shows each configured scheme, including Directory Server configuration. Each scheme is shown in a separate visual container.
The URL configuration tab displays the configured URLs for final Challenge Response message notification, results response notification, 3DS Requestor and 3DS Method Notification.
The license information tab shows information for the 3DS Server license, including licensed version and expiry date.
