Transact

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

PKI Authentication for Windows

Introduction

This page describes how to configure PKI (Public Key Infrastructure) authentication as the authentication type when installing Ephesoft Transact for Windows. 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 the Ephesoft 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 document.

Configure PKI Authentication

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

  1. Using the Windows Install Wizard (Normal installation)
  2. Using the config.properties File (Silent installation)

Using Windows Install Wizard

Follow the steps below to configure PKI authentication when using the Windows Install Wizard to install Ephesoft Transact.

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

  1. Start the installation process by running the Ephesoft Transact Install Wizard.

Figure 2. Ephesoft Transact Install Wizard

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

Figure 3. Authentication Mode

  1. Select PKI Authentication to import your PIV/CAC certificates.

Figure 4. Select PKI Authentication

The following PKI authentication options are available:

  • Provide the path to the file with PIV/CAC configurations.
  • Enter all required PIV/CAC authentication details using the Setup Wizard.
    • Click Next without attaching any files.

Certificate Details for PKI

  1. Provide the certificate details and click Next to continue. Refer to the table below for more information on configurable properties.

Figure 5. Certificate Details for PKI

Configurable PropertyDescription
Server CertThe 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.

Realm Settings for PKI

  1. In the Realm Settings for PKI section, provide the details about the realm you have configured for using PKI authentication. Hover over the text field to get more information on each parameter.
  2. Click Next to continue.

Figure 6. 2020.1 Realm Settings for PKI

Configurable PropertyDescription
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>.
Connection NameA valid username to connect and access the LDAP/Active Directory server (the username of the user responsible for interacting with the server).
Connection PasswordA valid password to connect and access the LDAP/Active Directory 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.
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 NameRole name defines which attribute is used for a role.
Role 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 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.
2019.1 and Above
X509 Auth ParameterOne of the username retriever parameters from the certificate. The available options are:

  • CN
  • PRINCIPALNAME
  • REGISTEREDID
  • RFC822NAME

Connector Settings for PKI

  1. Fill in the Connector Settings for PKI section.

Figure 7. Connector Settings for PKI

Configurable PropertyDescription
PortThe number of the PKI Connector Port.
SSL protocolThe protocol that will be used to secure a connection between the client and the server.
SSL Enable ProtocolThe supported versions of the selected protocol.
Ciphers textThe algorithm of encryption that will be used between the client and the server.
  1. Click Next to continue.

User Connectivity Settings

LDAP

For LDAP, configure the following details. You can hover over the text field on the UI to view a tooltip for each parameter.

Figure 8. LDAP User Connectivity Settings

Configurable PropertyDescription
Connectivity URLA valid URL to connect to the LDAP server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
Domain NameThe domain component name for the LDAP configuration.
Domain OrganizationThe domain component organization name for the LDAP configuration
User NameA valid username to connect and access the LDAP server (the username of the user responsible for interacting with the server.
PasswordA valid password to connect and access the LDAP server (the password of the user responsible for interacting with the server).
Group Search FilterA search string for searching groups.
User Search FilterA search string for searching users.
LDAP User BaseThe relative path under which all the users’ information will be located. This attribute defines where to look for a user.
LDAP Group BaseThe relative path under which all the groups/roles information will be located. This path will be relative to the domain components specified by the user.
Microsoft Active Directory (MSAD)

For MSAD, configure the following details. You can hover over the text field on the UI to view a tooltip for each parameter.

Figure 9. MSAD User Connectivity Settings

Configurable PropertyDescription
Connectivity URLA valid URL to connect to the LDAP server. The connection URL should be in the following format: ldap://<server_address>:<port_number>.
Domain NameThe domain component name for the LDAP configuration.
Domain OrganizationThe domain component organization name for the LDAP configuration
User NameA valid username to connect and access the LDAP server (the username of the user responsible for interacting with the server.
PasswordA valid password to connect and access the LDAP server (the password of the user responsible for interacting with the server).
Group Search FilterA search string for searching groups.
User Search FilterA search string for searching users.
AD Context PathThe directory where the intended user resides. This parameter is optional and can be left empty.
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.

You have successfully configured PKI authentication using the Windows Install Wizard.

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.

Figure 10. config.properties File

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.

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

Figure 11. PIV/CAC Details

Figure 12. PIV/CAC Details cont.

Note: Connectivity details are only needed for LDAP or MSAD. Apache Tomcat does not require connection configuration.

Authentication Mode Configuration

Configurable PropertyDescription
pivcac_selected_modeThe type of authentication mode you want to use.

  • 0 for Form Authentication
  • 1 for PKI Authentication

PIV/CAC Certificates Details

Configurable PropertyDescription
pivcac_server_cert_pathThe certificate that will be used to recognize your server.
pivcac_server_cert_passwordPassword for the server certificate.
pivcac_ca_cert_pathThe certificate that will be used to recognize the certification authority.
pivcac_ca_cert_passwordPassword for the CA certificate.

PIV/CAC Realm Configuration

Configurable PropertyDescription
pivcac_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>.
pivcac_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).
pivcac_realm_connection_passwordA valid password to connect and access the LDAP/Active Directory server (the password of the user responsible for interacting with the server).
pivcac_realm_user_baseThe relative path under which all the users’ information will be located. This attribute defines where to look for a user.
pivcac_realm_user_searchA search string for searching users.
pivcac_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.
pivcac_realm_role_nameRole name defines which attribute is used for a role.
pivcac_realm_role_searchA search string for searching roles.
pivcac_realm_userSubtreeThis 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.
pivcac_realm_roleSubtreeThis 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.
2020.1 and Above
X509UsernameRetrieverParameterOne of the username retriever parameters from the certificate. The available options are:

  • CN
  • PRINCIPALNAME
  • REGISTEREDID
  • RFC822NAME

Connector Settings for PIV/CAC Configuration

Configurable PropertyDescription
pivcac_Connector_portThe number of the PKI Connector port.
pivcac_Connector_client_authTrue if the client certificate is used for authentication, otherwise false. If a server is enabled with client certificate authentication, only users who attempt to connect from clients loaded with the right client certificates will succeed. Even if a legitimate user attempts to connect with the right username and password but is not using a client application loaded with the right client certificate, that user will not be granted access.
pivcac_Connector_compressionTrue if the compression algorithm is used to compress the data, otherwise false.
pivcac_Connector_ssl_enabledTrue if the SSL protocol is used to encrypt the connection between the client and the server. False if the connection is not encrypted.
pivcac_Connector_secureTrue if communication between the client and the server is secure, otherwise false.
pivcac_Connector_ssl_protocolThe protocol that will be used to secure a connection between the client and the server.
pivcac_Connector_trust_store_file_pathLocation of the truststore file (cacert.jks).
pivcac_Connector_trust_store_passwordPassword for the truststore file (cacert.jks).
pivcac_Connector_key_store_file_pathLocation of the keystore file (servercert.jks).
pivcac_Connector_key_store_passwordPassword for the keystore file (servercert.jks).
pivcac_Connector_ssl_enabled_protocolThe supported versions of the selected protocol.
pivcac_Connector_ciphers_textThe algorithm of encryption that will be used between the client and the server.

Connectivity User Configuration

Configurable PropertyDescription
connectivity_user_connectionThe type of connection you want to use for the application.

  • 0 for LDAP
  • 1 for MSAD
  • 2 for Tomcat
connectivity_urlA valid URL to connect to LDAP /Active Directory server. The connection URL should be in the following format: ldap://<server_address>:<port_number>
connectivity_domain_nameThe domain component name for the LDAP/AD configuration.
connectivity_domain_orgThe domain component organization name for the LDAP/AD configuration.
connectivity_user_nameA valid username to connect and access the LDAP/Active Directory server (the username of the user responsible for interacting with the server).
connectivity_user_passwordA valid password to connect and access the LDAP/Active Directory server (the password of the user responsible for interacting with the server).
connectivity_group_search_attribute_filterA search string for searching groups.
connectivity_user_search_attribute_filterA search string for searching users.
connectivity_ldap_user_baseThe relative path under which all the users’ information will be located. This attribute defines where to look for a user.
connectivity_ldap_group_baseThe relative path under which all the groups/roles information will be located. This path will be relative to the domain components specified by the user.
Microsoft Active Directory only
connectivity_msad_context_pathThe directory path where the intended user resides. This parameter is optional and can be left empty.
connectivity_msad_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.

  1. Start the Ephesoft Transact installer. In the Authentication Mode screen, select PKI Authentication. Click Browse and select the file where you configured the PIV/CAC settings.

Figure 13. Select the PKI Property File

  1. Click Next. The installer will pick up information from the file and all fields relating to PIV/CAC configuration will be automatically populated.

Conclusion

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

 

Was this article helpful to you? Yes No