Installation

ActiveAccess installation and setup processed simplified

Prerequisites¶

• Ensure that a compatible JDK is installed

• Ensure that the hardware security module is properly installed and configured

  HSM keys

  If this is a first time installation, ActiveAccess keys will be generated automatically.

  For subsequent installations of ActiveAccess on other servers ensure that the AES (128 Bits) key aliases AA_Administration, MIA_DB_DESede and the issuer key aliases (e.g. VbVA< Issuer_ID >, VbVB< Issuer_ID >, RSAVbV< Issuer_ID >, ECVbV< Issuer_ID >, etc) have been transferred from the primary installation in the current instance of HSM used by the ActiveAccess which is being installed.

• Ensure that the application server is properly installed and configured

• Ensure that the database server is properly installed and you have created a database for ActiveAccess.

  Database details

  Have the database name, username and password and address at hand for the installation process.

Pre Installation Configurations¶

Download and extract the ActiveAccess installation package, provided by GPayments.

Installation parameters¶

• An AA_HOME directory is required from which ActiveAccess will load the configurations it requires for installation. Create a directory and set an AA_HOME environment variable to this directory.

  Note

  Refer to your Operating System and application server documentation for any specific instructions for setting an environment variable.

New installations¶

• In the installation package, go to the ActiveAccess directory, copy activeaccess.properties and paste it in your AA_HOME directory.
• Open activeaccess.properties and fill in the required configuration parameters.

Upgrades from v7.4.x¶

• Add the following line in the acsconfig.properties file (located in TOMCAT_HOME/bin/config)

  HSM_PASSWORD= < password >

  Replace < password > with the base64 encoded format of your HSM password.

  Warning

  After the installation, a new configuration file, activeaccess.properties, will be created automatically in the AA_HOME directory. This new configuration file combines acsconfig.properties, eb_config.properties, miaconfig.properties and regconfig.properties and these files will be removed during the installation process.

  If you have configured any parameters that are not specific to ActiveAccess, you must take a back up of these files before running the installation and move these parameters manually to activeaccess.properties.

• Back up and remove the following files from TOMCAT_HOME/lib

  • gpcomp.pki-1.1.5-3.jar
  • gpcomp.hsm-1.2.24-0.jar
  • jprov-1.1.jar
  • kmcsp-1.0.jar
  • kmjava-1.0.jar
  • lunaprovider-5.0.3-11.jar
  • nfjava-1.0.jar
  • spp-1.0.jar
  • aal2wrap-3.14.0.jar
  • commons-codec-1.9.jar

Deploying WAR packages¶

Access Control Server, Administration Server, Enrolment Server and Registration Server are distributed as WAR packages. To install these packages, deploy acs.war, enrolment.war, mia.war and registration.war packages from ActiveAccess/files to your application server.

Installation¶

To initialize the installation process, start the application server.

This process may take a couple of minutes to complete.

An installation log will be created in AA_HOME/logs/install_log.log.

The date or size of [full path of the config file in installation package]
is different from [full path of the config file in AA_HOME], compare the
content and make sure all the required and optional parameters are OK.

Installation of Individual Components¶

The Access Control Server handles greater loads than other components and may be installed on a physical machine, dedicated to transaction processing.

Administration, Registration and Enrolment servers are usually installed on the same physical machine.

To install individual components:

• Ensure that you have the prerequisites properly installed and configured for each component that is being installed individually.

• Deploy the component's WAR package to the application server.

  • Access Control Server: acs.war
  • Administration Server: mia.war
  • Registration Server: registration.war
  • Enrolment Server: enrolment.war

• Configure the installation parameters (AA_HOME directory and configuration file).

• Start the application server.

• Ensure that the AES (128 Bits) key aliases MIA_DB_DESede, AA_Administration, Card< Issuer_ID > and the issuer key aliases (e.g. VbVA< Issuer_ID >, VbVB< Issuer_ID >, RSAVbV< Issuer_ID >, ECVbV< Issuer_ID >, etc. for all card scheme providers) exist in the HSM.

  Tip

  It is important to note that the issuers and issuer keys are generated on the local HSM used by the Administration server.

  If you are installing a component on the same machine as the Administration server, these keys will be created. However, if these servers are installed on physically separate machines that use their own HSM, you will need to export these keys from the Administration server HSM and import them to the local HSM of the Access Control Server, Enrolment and Registration servers' HSM devices.

  Do not attempt to create the keys directly as it will result in creation of physically different keys and the component will not be able to interact with the database server.

Post Installation¶

On successful installation and when the application server is started, the internal components are started on the default port. These components are:

Access Control Server¶

Base URL: https://< server-address >:< port >/acs/

The following extensions can be added to the base URL:

3DS Method URL: https://< server-address >:< port >/acs/tdsmethod

Monitoring the availability of ACS: https://< server-address >:< port >/acs/ping

Administration Server¶

Base URL: https://< server-address >:< port >/mia/

Monitoring the availability of MIA: https://< server-address >:< port >/mia/ping

Registration Server¶

Base URL: http(s)://< server-address >:< port >/registration/

The Registration Server has received a GET.

Your signed XML (application/xml) should be sent via HTTP POST.

The following extensions can be added to the base URL:

Monitoring the availability of Registration: http(s)://< server-address >:< port >/registration/ping

Enrolment Server¶

Base URL: https://< serveraddress >:< port >/enrolment/< IssuerID >

Monitoring the availability of Enrolment: https://< serveraddress >:< port >/enrolment/ping

Configuration Files¶

ActiveAccess Configuration File¶

/activeaccess.properties

The ActiveAccess Configuration file, activeaccess.properties, is automatically created/updated by the ActiveAccess installation. Common options such as database information are required to be configured during installation. The following sections document all the available parameters in case you need to change the defaults.

Common Configuration Parameters¶

DBNAME, DBOWNERPASSWORD

This is the database owner name and password that you use to create the database. When you first set or change the database owner password, you may set it in clear text. You should also add (PLAIN_TEXT=) to your configuration file.

DBUSERNAME, DBPASSWORD

This is the username and password that you use to access the database. In a simple configuration this username may be the same as the database owner name. When you first set or change the database password, you may set it in clear text. You should also add (PLAIN_TEXT=) to your configuration file.

PLAIN_TEXT=

This instructs the server to read DBOWNERPASSWORD and DBPASSWORD in clear text and replace them with the encrypted values.

DBURL

For Oracle the default URL is:

jdbc\:oracle\:thin\:\@127.0.0.1\:1521\:ORCL

Replace 127.0.0.1:1521 with the IP address and port number of the Oracle instance you have installed. ORCL is the SID of the database and must be replaced with the SID you selected during the installation of the database server.

DBURL=jdbc\:oracle\:thin\:\@192.168.0.202\:1521\:ORCL

DBDRIVER

For Oracle, leave the default value unchanged as shown below:

DBDRIVER=oracle.jdbc.driver.OracleDriver

INITIALCONNECTIONS

Specifies the initial length of database connection pool allocated by the application.

MAXCONNECTIONS

Specifies the maximum length of database connection pool that can be allocated by the application.

WAITIFBUSY

Can be set to either true or false. The default is true. When set to true, connection requests exceeding the maximum connections will be queue until a connection is freed. When set to false, the application immediately returns an connection erorr if no free connection can be found in the pool.

DB_IDLE_TIMEOUT

The database idle connection time out in seconds. Idle database connections are closed in the application's connection pool after the specified time. The default is 900 seconds.

DBENCODED

If this parameter sets to false reading and writing to database is done in ISO-8859-1 character set and ActiveAccess uses its own encoding (Default value is false). Otherwise database's own encoding is used.

HSMPROVIDER

Used to specify the HSM provider name.

For ActiveAccess instances which were originally installed prior to ActiveAccess v7.4.0, the value would be nCipherKM for Thales e-Security, ERACOM for SafeNet, or SUN for Sun JCE. In ActiveAccess instances originally installed after and including v7.4.0, this parameter would be PKCS11 or SUN.

KEYSTORE_DIR

Used to specify the physical location of the HSM KeyStore (Thales e-Security or SunJCE). Use forward slash as the path separator e.g.: KEYSTORE_DIR=c:/nfast/kmdata/local

HSM_PASSWORD

Used to set the HSM password in the configuration file. This option takes precedence over the java option -Dcom.gpayments.hsm.password. The HSM password must be provided in base64 encoded format in both cases. Leave empty for a blank HSM password.

HSMENCALIAS

When the MIA/ACS Settings Encryption Key is automatically or manually retired and replaced with a new one using the PCIDSS Key Retiring Utility, the default key alias is changed. Therefore, the new key alias is specified by HSMENCALIAS.

Additional Administration Server Configuration Parameters¶

UPLOADCACHE_DIR

Used to specify a location to copy uploaded file that VASCO and RSA tokens fetched from it. Use forward slash as a path separator e.g.: UPLOADCACHE_DIR=c:/tempdir

MAX_WARNINGS

Specifies the maximum number of warning messages that the administration server will generate while processing VACSO or RSA token files before an error is returned. In other words, if processing a VASCO or RSA file creates more warnings than this value, the server will terminate processing of the file and will return an error response. If this parameter is not specified, a default value of 50 is used.

MODULE

Used for initialising of the key manager for CAP functions. Select HSM for secure computation and cryptographic functions. A value of zero results in load sharing among all nShield capable modules. Default value is 0.

PSINAME

Used for initializing the key manager for CAP functions. It is the name of the nShield installation to be initialized. Default value is gpaymentsTest.

Additional ACS Configuration Parameters¶

COMPUTERNAME

This is the computer name where the ACS is installed.

CACHING

This option specifies the caching mode for resources. The default is everyvisit.

DBENCODED

Can have two values Yes or No. If your Database is set to use encoding, set this option to Yes.

MODULE

Used for initialising of the key manager for CAP functions. Select HSM for secure computation and cryptographic functions. A value of zero results in load sharing among all nShield capable modules. Default value is 0.

PSINAME

Used for initializing the key manager for CAP functions. It is the name of the nShield installation to be initialized. Default value is gpaymentsTest.

ZLIBOFF

It can be set to either true or false. When it is set to true, ACS does not inflate ZIP objects. The default value is false.

Additional Registration Server Configuration Parameters¶

VERIFICATION

Can be set to either true or false. When the verification is true, the registration server checks the authenticity of XML messages by validating the XML signature. Disabling verification should be avoided in a production system for security reasons.

REQUEST_LOGGING

Can be set to either true or false. Used to collect request debug information, intended for testing purposes. This option should not be enabled in production environment.

MAX_WARNINGS

Specifies the maximum number of warning messages that the registration server will generate, before an error is returned. In other words, if a message sent to the registration server creates more warnings than this value, the server will terminate processing the message and will return an error response. If this parameter is not specified the default value of 50 is used.

Notification Report Collector Job Parameters:

Notification Reports are provided based on collected report files by the Notification Report Collector Job on the Registration server. In order to configure this job to collect the required data and cache report files, the following parameters must be set in activeaccess.properties:

LAST_REPORT_TIME

The last time that the notification report collector job was run

Format: DD/MM/YYYY

OFFICIAL_START_HOUR (Deprecated and is no longer used)

The hour that is used as the start hour of the day. Reports are collected based on this hour. Values: 00..23 (default: 00)

OPTOUT_MODE

The flag that specifies whether report collector should collect the last cardholder opt out only or all opt outs.

Values: LAST/ALL (default: ALL)

SCHEDULER_START_TIME

The time that the report collector job starts to collect reports based on LAST_REPORT_DATE

Format: HH:mm:ss GMT(+0:00) (default: -1 to disable job).

Example: Assume LAST_REPORT_TIME=02/02/2009, SCHEDULER_START_TIME=22:30:30, if today is 05/02/2009, report collector starts at 22:30:30 GMT(+0:00) and collects reports from 02/02/2009 00:00 to 05/02/2009 00:00

NOTIFICATION_FILE_PATH

The path on the server which the report collector job will cache for the collected report files

The default path is a NotificationReport directory, located in the deployed directory of Registration on your application server.

NOTIFICATION_REPORT_LIFETIME

The life time of cached report files on the server in DAY. As soon as the report collector job starts, it removes files if their life time period has already passed

Default: -1 to disable

NOTIFICATION_REPORT_REGEN_ISSUERIDS

A comma separated list of the IDs of the issuers that have retired their encryption key using PCIDSS Retiring Utility. As the result of retiring the encryption key of an issuer, the pre-collected notification report files are no longer valid. This list is automatically populated at the end of the utility process to indicate that notification reports should be re-collected for the specified issuers at the next run of the notification report collector job.

Additional Enrolment Server Configuration Parameters¶

CACHE:

Specify the caching mode used for caching issuer pages. (0: every visit, 1: automatically, 2: never, default value is 0.)

MAX_CACHE:

Specify the number of issuer pages that will be cached. Default value is: 100.

Providers File¶

ActiveAccess requires the default card ranges of all providers in order to process incoming 3D-Secure authentication requests. As card schemes may add new card ranges at any time, the providers file allows for the additions to be made manually, when required. The following options can be updated in providers.xml under the AA_HOME directory.

• Provider name, provider index, cname and provider ID: within the < providerInfo > element for each of the providers, there are tags for the provider's name (< providerName >), index (< providerIndex >), card scheme authentication method (< cName >), and provider ID (< providerId >). The following table shows the possible values for the aforementioned tags.

• Card Range: the card ranges for each provider are included in the providers file, in the form of minimum range and maximum range. The minimum range should always be lower than', or equal to, the maximum range, with an equal number of digits. You can add any card range to the providers file inside the tag, by copying the tag and inserting the new minimum and maximum ranges. Make sure the newly added card ranges do not overlap with another provider's card ranges. Furthermore, the tag indicates the required number of digits for card numbers, which fall within the specified card range.