Transact

⌘K
  1. Home
  2. Transact
  3. Install and Upgrade
  4. Additional Resources
  5. Linux
  6. PKI Authentication for Linux

PKI Authentication for Linux

Introduction

This page describes how to configure PKI (Public Key Infrastructure) authentication as the authentication type when installing Ephesoft Transact for Linux. You can select the PKI authentication type and import your PIV/CAC certificates during installation. All provided data will be saved, updated, and mapped automatically in the following files:

  • server.xml located in <Ephesoft_Directory>/JavaAppServer/conf
  • web.xml located in <Ephesoft_Directory>/JavaAppServer/conf
  • dcma-user.connectivity.properties located in <Ephesoft_Directory>/Application/WEB-INF/classes/META-INF/dcma-user-connectivity
  • dcma-batch.properties located in <Ephesoft_Directory>/Application/WEB-INF/classes/META-INF/dcma-batch
  • config.properties (included in Ephesoft Transact installation package)

The imported certificates will be stored in the Certs folder of the Ephesoft Transact installation directory.

Figure 1. Certs Folder in /opt/Ephesoft

The Ephesoft Transact installer also provides an option to select a PKI-config.properties file to automatically fill the required fields for PIV/CAC configuration. You can provide PIV/CAC details in the properties file and then simply specify the file location during Transact installation.

Note: The Ephesoft Transact Installer is shipped as a zip file. To install the application, unzip the file and run the installer.

Prerequisites

There are no prerequisites for this article.

Configure PKI Authentication

This section provides information on how to configure PKI authentication with two methods:

  1. Using the Command-line Interface (Normal installation)
  2. Using the config.properties File (Silent installation)

Using the Command-line Interface

Follow the steps below to configure PKI authentication using the Linux command-line interface to install Ephesoft Transact.

Note: Follow these instructions when running a normal installation of Ephesoft Transact.

  1. Start the installation process by executing the installer. When prompted to install the system using the silent installer, select n.

C:\Users\breanna.fitzgerald\AppData\Local\Microsoft\Windows\INetCache\Content.MSO\B14E2198.tmp

Figure 2. Proceed with Normal Installation

  1. Follow the installation process up to the Authentication Configuration step.

Figure 3. Select PKI Authentication

  1. Enter 2 to select PKI Authentication Mode.

The following PKI authentication options are available:

  • Import PKI configurations from the properties file
  • Enter all required PIV/CAC authentication details using the command-line interface.
    • Enter n to select this option and continue with the steps below.

Certificate Details for PKI

  1. Provide the certificate details as they are prompted in the command-line interface. Refer to the table below for more information on configurable properties.

Figure 4. Certificate Details for PKI

Configurable Property Description
Username Retriever One of the username retriever parameters from the certificate.

  • Press 1 for CN
  • Press 2 for PrincipalName
  • Press 3 for RFC822Nam
  • Press 4 for RegisteredID
Server Cert A certificate that will be used to recognize your server.
Password Password for Server Certificate.
CA Cert The certificate that will be used to recognize the certification authority.
Password Password for CA Certificate.
Alias Name The name of your server certificate as specified in the Trusted Root Certification Authorities folder of the Windows Certificate Manager.
  1. Press y to change any details. Otherwise, press n to continue.

Connector Settings for PKI

  1. Provide the connector settings as they are prompted in the command-line interface. Refer to the table below for more information on configurable properties.

Figure 5. Connector Settings

Configurable Property Description
Port Number of the PKI Connector Port.
SSL protocol Protocol that will be used to secure connection between the client and the server.
SSL Enable Protocol The supported versions of selected protocol.
Cipher Text The algorithm of encryption that will be used between the client and the server.
  1. Press y to change any details. Otherwise, press n to continue.

Realm Settings for PKI

  1. Select the user connection type you want to configure.
    • Enter 1 for LDAP
    • Enter 2 for Microsoft Active Directory (MSAD)
  2. Provide the settings for the realm you have configured as they are prompted in the command-line interface. Refer to the table below for more information on configurable properties.

Figure 6. Sample Realm Settings Using LDAP

Configurable Property Description
Connection URL A valid URL to connect to the LDAP server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
Connection Name A valid username to connect and access the LDAP server (the username of the user responsible for interacting with the server.
Connection Password A valid password to connect and access the LDAP server (the password of the user responsible for interacting with the server).
User Base The relative path under which all the users’ information will be located. This attribute defines where to look for a user.
User Search A search string for searching users.
User Subtree This attribute defines the search scope. Set to true to search the entire subtree rooted at the User Base entry. Set to false to request a single-level search including only the top level.
Role Base The relative path under which all the roles information will be located. This attribute defines where to look for a role corresponding to a user.
Role Name Defines which attribute is used for a role.
Role Search A search string for searching roles.
Role Subtree This attribute defines the search scope. Set to true to search the entire subtree rooted at the Role Base entry. Set to false to request a single-level search including only the top level.
Microsoft Active Directory only
MS AD Context Path The directory where the intended user resides. This parameter is optional and can be left empty.
MS AD Group Search Filter This attribute helps to filter search results and can have the following operators: |(OR), &(AND) and !(NOT). For example, ((!(cn=a*))(|cn=a*))(|(cn=ephesoft*)(&(cn=b*)))

This parameter is optional and can be left empty.

  1. Press y to make any changes. Otherwise, press n to continue.

The following message will display:

Figure 7. Configuration Successful Message

You have successfully configured PKI authentication using the command-line interface.

Using the config.properties File

Follow the steps below to configure PKI authentication using the config.properties file.

Note: Follow these instructions when running a silent installation of Ephesoft Transact.

  1. Open the config.properties file included in the Ephesoft Transact installer.

Note: You can either provide the details in the config.properties file or copy the PIV/CAC configuration section and save it in a separate configurations file. For example, create a PKI-config.properties file, as shown in figure 8 below.

Figure 8. PKI-config.properties File

  1. Refer to the tables below to configure the details required to import PIV/CAC certificates during installation.

Figure 9. PKI Authentication Details

Connection Configuration

Configurable property Description
input_pki_server_cert_path Location of the Server certificate.
input_pki_server_cert_password Password for the server certificate.
input_pki_ca_cert_path Location of the Certifying Authority certificate.
input_pki_ca_cert_password Password for the server certificate.
input_pki_alias_name Unique string to identify the keystore entity.
input_pki_connector_port_number The number of the PKI connector port.
input_pki_connector_ssl_protocol The protocol that will be used to secure a connection between the client and the server.
input_pki_connector_ssl_enabled_protocol The supported versions of the selected protocol.
input_pki_connector_chipper_text The algorithm of encryption that will be used between the client and the server.
2019.1 and Above
X509UsernameRetrieverParameter One of the username retriever parameters from the certificate.

  • Enter 1 for CN
  • Enter 2 for PrincipalName
  • Enter 3 for RFC822Name
  • Enter 4 for RegisteredID

Authentication Mode Configuration

Configurable Property Description
input_connectivity_user_connection The type of connection you want to use for the application.

  • Enter 1 for LDAP
  • Enter 2 for MSAD
  • Enter 3 for Tomcat

Note: Apache Tomcat does not require configuration.

Realm and PIV/CAC Certificate Details

Configurable property Description
input_realm_super_admin_group_name Name of the super-admin group.
input_realm_connection_url A valid URL to connect to LDAP /Active Directory server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
input_realm_connection_name A valid username to connect and access the LDAP/Active Directory server (the username of the user responsible for interacting with the server).
input_realm_user_base The relative path under which all the users’ information will be located. This attribute defines where to look for a user.
input_realm_user_search A search string for searching users.
input_realm_user_sub_tree This attribute defines the search scope. Set to true to search the entire subtree rooted at the user base entry. Set to false to request a single-level search including only the top level.
input_realm_role_base The relative path under which all the roles information will be located. This attribute defines where to look for a role corresponding to a user.
input_realm_role_name Role name defines which attribute is used for a role.
input_realm_role_search A search string for searching roles.
input_realm_role_sub_tree This attribute defines the search scope. Set to true to search the entire subtree rooted at the Role base entry. Set to false to request a single-level search including only the top level.
Microsoft Active Directory only
input_msactivedirectory_group_search_filter This attribute helps to filter search results and can have the following operators: |(OR), &(AND) and !(NOT).

For example, ((!(cn=a*))(|(cn=ephesoft*)(&(cn=b*)))

This parameter is optional and can be left empty.

You have successfully configured PKI authentication using the config.properties file.

Conclusion

You have successfully configured PKI authentication for Linux. Return to the install guide for your version and proceed with the installation process.