Buypass Code Service Connector installation guide
- Georg Johansen
- Lise Kristoffersen
Overview
Buypass Code Service Connector (SC) is the physical access point to the Buypass Code solution for
merchants. The SC uses a regular SSL certificate issued by Buypass to perform point-to-point
encryption when communicating with Buypass Code Servers located centrally at Buypass.
A unique signing certificate is used to identify a SC. The signing certificate is generated by Buypass
and should be used on all SC’s so that all requests are signed.
The SC is a light weight access point for Radius traffic, and mostly routes the traffic to Buypass Code
Servers for further processing. It also handles directory lookup using instructions based on
configurations that the merchant enters into Buypass Code Manager.
SC supports the following authentication protocols: PAP, CHAP, MSCHAPv2.
Technical requirements
- Software requirements
- Windows 2012 (R2) / Windows 2016 / Windows 2019
- Active internet connection
- Hardware requirements
- CPU - Pentium class processor 1 GHz or faster
- HD - 200MB of available hard disk space
- RAM - 2GB of available RAM
- Network connectivity
- Buypass SC needs read access to your Directory Server via LDAP / LDAPS. Service account credentials are entered in Buypass Code Manager.
- Buypass SC needs to communicate with Buypass Code Servers via https (port 443) to IP addresses 185.62.160.148 and 185.62.162.148.
- The access point/Radius client needs to communicate with the SC via Radius (default UDP port 1812).
Installation and configuration
There are three phases for installation/configuration of the SC. The SC has to be installed and configured. LDAP and RADIUS configurations have to be established in Buypass Code Manager. And finally the point of access (RAS, NAS, VPN etc.) has to be configured to use the SC.
Installation of Buypass Code Service Connector
A Service Connector install wizard can be downloaded from Buypass Ekstranett. Please make sure you have access to the signing certificate sent by e-mail and the certificate password sent by SMS from number 1960. Also make sure you have admin access to the server.
- Start the wizard and press "Next".
- Find the signing certificate and enter the certificate password. Press "Next" and then "Install". The necessary files will be installed in C:\bps\ and a service named "bpcode-sc" will be installed.
- Check the "Start service" checkbox and press "Finish".
- Verify that the SC has started by opening C:\bps\log\trace\sc_trace_TIMESTAMP.log and check that the last rows look like the following:
- You can also try to authenticate and verify that the authentication is logged in C:\bps\log\trace\sc_trace_TIMESTAMP.log.
Buypass Code Manager
- LDAP configuration
The LDAP configuration is used to lookup user information using a Directory Service via LDAP/LDAPS, e.g. Active Directory from Microsoft. The Directory Service should contain mobile numbers and/or App-ID for users.
For more information about LDAP configuration, see LDAP / HTTP look up.
- RADIUS configuration
The RADIUS configuration define which access points/RADIUS clients are allowed to send requests to the SC.
For more information about RADIUS configuration, see Radius clients doc.
- Point of access/RADIUS client
The local point of access/RADIUS client has to be configured to communicate with the SC via RADIUS. The IP-address has to point to the SC and the Shared Secret has to be the same as the one in the RADIUS configuration in Buypass Code Manager.
For more information about integrating Buypass Code with other products, see Integration Guides at Installation Guides
Upgrading guide
This section describes how to upgrade from an earlier version of the Service Connector.
- Start the install wizard and press "Next".
- The install wizard will automatically find your certificates and config, press "Install".
- The upgrade is finished. Check the "Start Service" box and press "Finish" to start the service.
- Verify that the SC has started by opening C:\bps\log\sc_trace_TIMESTAMP.log and check that the last rows look like the following:
- You can also try to authenticate and verify that it is logged in C:\bps\log\trace\sc_trace_TIMESTAMP.log.
Service Connector configuration parameters
If you wish to modify the default configurations this is done in C:\bps\config\properties\cnl\bpc\sc\scconfig-local.properties. The "bpcode-sc" service has to be restarted before new configurations become active.
| Parameter and default value | Description |
|---|---|
| Log paramater | |
| cfg.gen.general.logger_type=1 | Specifies what logger type to use 0 - void logger 1 - console logger (stdout/stderr) 2 - file logger, specified by file_log_dir |
| cfg.gen.general.file_log_dir=/bps/log/ | Specify log path for log, only used if logger_type is 2 |
| cfg.gen.general.tracer_type=1 | Specifies what tracer type to use 0 - void tracer 1 - console tracer (stdout/stderr) 2 - file tracer, path specified by file_trace_dir |
| cfg.gen.general.trace_level=8 | Trace lever for the server, primary used for debuging 0 - no trace .. 8 - maximum trace |
| cfg.gen.general.file_trace_dir=/bps/log/trace/ | Specify log path for trace, only used if tracer_type is 2 |
| cfg.gen.general.print_properties=true | Specifies if configurations should be written to trace on start up of Service Connector. |
| Networking configuration | |
| cfg.gen.io.client_socket_read_wait=30000 | Specifies socket timeout for read operations against Buypass Code Server – in milliseconds |
| cfg.gen.io.max_raw_message_bytesize=2097152 | Maximum packet size between the SC and the Buypass Code Server server (in bytes) |
| cnl.bpc.sc.rasurl=https://ras.buypass.no/ras2/ | Specifies the Buypass Code Server (RAS) URL |
| cnl.bpc.sc.auth_port=1812 | Specifies the Radius Authentication port |
| cfg.gen.io.bind_ip= | Can be used on a multi-homed host for only accepting connect requests to one of its addresses. If not set, it will default accepting connections on any/all local addresses |
| cnl.bpc.sc.proxy.url= | An optional parameter defining the HTTP proxy to use. If no port is present the default port is 8080. E.g. (http://proxy.hostname:8080) |
| Start up | |
| cnl.bpc.sc.halt_on_startup_remote_initialization_e rror=true | Specifies if SC should stop if it can’t contact the Buypass Code Server |
| Radius duplicate handling | |
| cnl.bpc.sc.duplicate_window_time=30000 | Duplicate package handle timeout in milliseconds |
| cnl.bpc.sc.duplicate_window_size=5000 | Duplicate package handle max cache size |
| Key and certificate configuration | |
| cnl.bpc.sc.keystore.path= /bps/tools/jarsigning/512keystore | Specifies the physical path to the signing certificate used by the service connector. This file authenticates this instance of the service connector |
| cnl.bpc.sc.keystore.alias=AUTO | Specifies the key file alias. If the key file contains only one entry, please set this value to AUTO. If the key file contains more than one entry, the correct alias must be specified |
| cnl.bpc.sc.keystore.type=AUTO | Specifies key file type JKS - Java Key Store PKCS12 - PKCS12 key file AUTO - auto detect key file type based on file extension (PKCS12 files has .p12 extensions, JKS has no extension) |
| cnl.bpc.sc.keystore.password=test123 | Specifies the signing certificate password |
| cnl.bpc.sc.encryption_certificate.path= /bps/tools/jarsigning/512.crt | Physical path to encryption certificate used to encrypt kommunication between the SC and Buypass Code Server |
| cnl.bpc.sc.node_id=0 | Specify when you use more than one Service Connector per Service Connector certificate to guarantee unique ID per SC |
Server logging
All trace log files can be found in C:\bps\log\trace\
All access log files can be found in C:\bps\log\access\
Error log files can be found in C:\bps\log\error\ or C:\bps\bpcode-sc\winservice\log\
Configuration parameters for log rotation
The SC can rotate/archive log files based on time and/or size. The table shows configuration parameters and examples of different configurations. Choose one for each type of log and put it in C:\bps\release\[version]\config\properties\cnl\bpc\sc\scconfig-local.properties.
| Parameters and example configurations | Description |
|---|---|
| Trace log | |
| cfg.gen.general.tracer_type=6 | Specifies type of log rotation 6 = Time based (or time and size based) 7 = Size based |
| cfg.gen.general.tracer_history=3 | Specifies the number of archive files to store |
| cfg.gen.general.tracer_rollover_pattern=hourly | Specifies how often rotation should happen minutely = Every minute hourly = Every hour daily = Every day weekly = Every week monthly = Every month |
| cfg.gen.general.tracer_max_size=5mb | Specifies maximum size of active file before rotation happens. Size in km, mb or gb |
| Example of configurations for trace log | |
| Time dependent | |
| cfg.gen.general.tracer_type=6 cfg.gen.general.tracer_history=3 cfg.gen.general.tracer_rollover_pattern=hourly | Rotates every hour with maximum 3 archive files |
| Size dependent | |
| cfg.gen.general.tracer_type=7 cfg.gen.general.tracer_history=10 cfg.gen.general.tracer_max_size=5mb | Rotates when active file is 5mb with maximum 10 archive files |
| Time dependent with size limit | |
| cfg.gen.general.tracer_type=6 cfg.gen.general.tracer_history=3 cfg.gen.general.tracer_rollover_pattern=hourly cfg.gen.general.tracer_max_size=5mb | Rotates every hour or when active file is 5mb with maximum 4 archive files |
| Access log | |
| cfg.gen.general.access_logger_type=6 | Specifies type of log rotation 6 = Time based (or time and size based) 7 = Size based |
| cfg.gen.general.access_history=3 | Specifies the number of archive files to store |
| cfg.gen.general.access_rollover_pattern=hourly | Specifies how often rotation should happen minutely = Every minute hourly = Every hour daily = Every day weekly = Every week monthly = Every month |
| cfg.gen.general.access_max_size=5mb | Specifies maximum size of active file before rotation happens. Size in km, mb or gb |
| Example of configurations for access log | |
| Time dependent | |
| cfg.gen.general.access_logger_type=6 cfg.gen.general.access_history=3 cfg.gen.general.access_rollover_pattern=hourly | Rotates every hour with maximum 3 archive files |
| Size dependent | |
| cfg.gen.general.access_logger_type=7 cfg.gen.general.access_history=10 cfg.gen.general.access_max_size =5mb | Rotates when active file is 5mb with maximum 10 archive files |
| Time dependent with size limit | |
| cfg.gen.general.access_logger_type=6 cfg.gen.general.access_history=3 cfg.gen.general.access_rollover_pattern=hourly cfg.gen.general.access_max_size =5mb | Rotates every hour or when active file is 5mb with maximum 4 archive files |
| Error log | |
| cfg.gen.general.logger_type=6 | Specifies type of log rotation 6 = Time based (or time and size based) 7 = Size based |
| cfg.gen.general.logger_history=3 | Specifies the number of archive files to store |
| cfg.gen.general.logger_rollover_pattern=hourly | Specifies how often rotation should happen minutely = Every minute hourly = Every hour daily = Every day weekly = Every week monthly = Every month |
| cfg.gen.general.logger_max_size=5mb | Specifies maximum size of active file before rotation happens. Size in km, mb or gb |
| Example of configurations for error log | |
| Time dependent | |
| cfg.gen.general.logger_type=6 cfg.gen.general.logger_history=3 cfg.gen.general.logger_rollover_pattern=hourly | Rotates every hour with maximum 3 archive files |
| Size dependent | |
| cfg.gen.general.logger_type=7 cfg.gen.general.logger_history=10 cfg.gen.general.logger_max_size=5mb | Rotates when active file is 5mb with maximum 10 archive files |
| Time dependent with size limit | |
| cfg.gen.general.logger_type=6 cfg.gen.general.logger_history=3 cfg.gen.general.logger_rollover_pattern=hourly cfg.gen.general.logger_max_size=5mb | Rotates every hour or when active file is 5mb with maximum 4 archive files |
Troubleshooting
If installation fails for some reason, start by looking for error messages in the log files
C:\bps\log\trace\
C:\bps\log\error\
C:\bps\bpcode-sc\winservice\log\
The following are examples of error messages, what they mean and how to solve the error.
- Wrong password
Above error means that the signing certificate password is wrong. Verify that the password sent to you by SMS is the same as the password found in C:\bps\config\properties\cnl\bpc\sc\scconfiglocal.properties for attribute cnl.bpc.sc.keystore.password. Note that 0 (zero) and O as well as I (upper case i) and l (lower case L) can easily be mixed.
- Unable to load certificate
Above error means that the signing certificate can’t be loaded by the SC. Verify that the signing certificate that was sent by mail is located in C:\bps\tools\jarsigning\ and that the cnl.bpc.sc.keystore.path attribute in CC:\bps\config\properties\cnl\bpc\sc\scconfig-local.properties points to the certificate.
- Port in use
Above error means that the port that the SC is trying to use for Radius communication is already in use by another application. Close the application that is using the port or set another port that the SC can use for Radius communication by specifying it for attribute cnl.bpc.sc.auth_port in C:\bps\config\properties\cnl\bpc\sc\scconfig-local.properties (requires version 7.26.X.X).