Transact

  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 PropertyDescription
Username RetrieverOne 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 CertA certificate that will be used to recognize your server.
PasswordPassword for Server Certificate.
CA CertThe certificate that will be used to recognize the certification authority.
PasswordPassword for CA Certificate.
Alias NameThe 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 PropertyDescription
PortNumber of the PKI Connector Port.
SSL protocolProtocol that will be used to secure connection between the client and the server.
SSL Enable ProtocolThe supported versions of selected protocol.
Cipher TextThe 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 PropertyDescription
Connection URLA valid URL to connect to the LDAP server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
Connection NameA valid username to connect and access the LDAP server (the username of the user responsible for interacting with the server.
Connection PasswordA valid password to connect and access the LDAP server (the password of the user responsible for interacting with the server).
User BaseThe relative path under which all the users’ information will be located. This attribute defines where to look for a user.
User SearchA search string for searching users.
User SubtreeThis 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 BaseThe 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 NameDefines which attribute is used for a role.
Role SearchA search string for searching roles.
Role SubtreeThis 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 PathThe directory where the intended user resides. This parameter is optional and can be left empty.
MS AD Group Search FilterThis 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 propertyDescription
input_pki_server_cert_pathLocation of the Server certificate.
input_pki_server_cert_passwordPassword for the server certificate.
input_pki_ca_cert_pathLocation of the Certifying Authority certificate.
input_pki_ca_cert_passwordPassword for the server certificate.
input_pki_alias_nameUnique string to identify the keystore entity.
input_pki_connector_port_numberThe number of the PKI connector port.
input_pki_connector_ssl_protocolThe protocol that will be used to secure a connection between the client and the server.
input_pki_connector_ssl_enabled_protocolThe supported versions of the selected protocol.
input_pki_connector_chipper_textThe algorithm of encryption that will be used between the client and the server.
2019.1 and Above
X509UsernameRetrieverParameterOne 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 PropertyDescription
input_connectivity_user_connectionThe 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 propertyDescription
input_realm_super_admin_group_nameName of the super-admin group.
input_realm_connection_urlA 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_nameA 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_baseThe relative path under which all the users’ information will be located. This attribute defines where to look for a user.
input_realm_user_searchA search string for searching users.
input_realm_user_sub_treeThis 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_baseThe 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_nameRole name defines which attribute is used for a role.
input_realm_role_searchA search string for searching roles.
input_realm_role_sub_treeThis 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_filterThis 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.

Was this article helpful to you? Yes No