Transact

⌘K
  2. Home
  4. Transact
  6. System Configuration
  8. User Connectivity
  10. Single Sign-On Resources
  12. Manually Configuring SAML 2.0 SSO for Ephesoft Transact 4.5.0.x and 2019.1

Manually Configuring SAML 2.0 SSO for Ephesoft Transact 4.5.0.x and 2019.1

SSO Overview

Single sign-on (SSO) is a mechanism of access control that can be applied on multiple related, but independent software systems. With this mechanism, a user logs in once and gains access to multiple systems without being prompted to log in again for each individual application. Conversely, single sign-off is a property mechanism whereby a single action of signing out terminates access to multiple software systems.

As different applications and resources support different authentication mechanisms, single sign-on internally translates to and stores different credentials, compared to what is used for initial authentication.

Benefits

SSO has several general benefits, to include the following:

  • Reducing password fatigue from different user name and password combinations
  • Reducing time spent re-entering passwords for the same identity
  • Reduced logins for discreet systems
    • Corporate systems
    • Shared intranet/web applications
    • Web logon aggregators
  • Reduced cost to reset a password
  • Reduced time spent logging into multiple systems each time
  • Reduces multiple authentication, unnecessary user clicks, forgotten passwords, multiple profiles
  • Limited time and resources to develop IT solutions

SSO Support Information for Ephesoft Transact

This document describes how to make manual SAML 2.0 SSO configurations during a new installation of Ephesoft Transact 4.5.0.x or 2019.1.

Note: Automated SSO configuration for Ephesoft Transact does not have scheduled availability.

Ephesoft Transact has been tested with the following SSO-related components:

  • SAML 2.0 — An XML-based protocol that entails security tokens for authentication and authorization. Ephesoft Transact supports SAML 2.0, and has tested and certified the following identity providers that are compatible with Ephesoft Transact:
    • Active Directory Federation Services (ADFS)
    • Okta
    • PingFederate
    • SSOCircle
  • Transport Layer Security (TLS) — Ephesoft Transact 4.5.0.x and 2019.1 support TLS versions 1.0, 1.1 and 1.2.

There are multiple additional identity providers in the market that support SAML 2.0. Ephesoft has not tested every available identity provider or security product.

SSO Configuration Overview for Ephesoft Transact

This document describes how to make manual SAML 2.0 SSO configurations during a new installation of Ephesoft Transact 4.5.0.x or 2019.1.

Note: This document emphasizes tasks for operational deployment. At some time in the future, Ephesoft may provide a separate document that describes security and SSO concepts.

This document contains the following sections and purposes:

    • Prerequisites: Required — This section identifies the prerequisite conditions that must be in place in order to configure SSO for use with Ephesoft Transact.
    • Obtaining and Installing OpenSSL: Required — This section describes the steps for downloading and installing OpenSSL. You must complete these steps prior to performing the additional SSO configurations in this document.
    • Configuring SSL/TLS: Required — This section describes the steps for configuring multiple components of the Secure Sockets Layer (SSL) protocol or the Transport Layer Security (TLS) protocol. One or more of these components may need to be configured, depending on your current requirements and status.

Not all identity providers (IdP) will require SSL/TLS configuration, but this section provides instructions for those IdPs that do require it.

Prerequisites

Prerequisite Components

The following items are required to set up SAML 2.0 SSO authentication with Ephesoft Transact.

  1. CA Certificate — If you have access to a trusted Certificate Authority (CA), you should complete the CA process to get a CA certificate, server certificate and server private key.
  • If you do not have a trusted Certificate Authority (CA), you can create dummy CA certificates to test the setup in a lab or test environment.
  • In an ideal scenario, you should have a trusted Certificate Authority (CA).
  1. Identity Provider — You must have an installed identity provider (IdP) server that supports SAML 2.0.
    Ephesoft has tested and certified Ephesoft Transact with the following four identity providers:
  • Active Directory Federation Services (ADFS)
  • Okta
  • PingFederate
  • SSOCircle
  1. Active Directory — This document does not provide step-by-step instructions for installing or configuring Active Directory.
    If you need to set up Active Directory in preparation for configuring SSO, refer to one or more of the following articles:

Obtaining and Installing OpenSSL

OpenSSL is a robust, commercial-grade, and full-featured toolkit for the Transport Layer Security (TLS) and Secure Sockets Layer (SSL) protocols. Use OpenSSL in the case that a trusted Certificate Authority (CA) certificate is not available.

You can download OpenSSL on Windows from the Win32/Win64 OpenSSL Open Installation Project

Note: You need to install PERL on the system before using OpenSSL. Refer to the PERL website.

Configuring SSL/TLS

Introduction

This section provides detailed steps for setting up certificates for the Secure Sockets Layer (SSL) or Transport Layer Security (TLS).

SSL/TLS Setup: Server Certificates

To set up SSL/TLS protocols, you need to use either certificate issued by CA or self-signed certificates, which can be used in the TEST environment as mentioned above.

Production Environment: CA Certificates

In a production environment, you must make use of certificates issued by a trusted CA.

Testing Environment: Self-Signed Certificates

For a lab or test environment, you can generate your own dummy self-signed certificates for testing the Ephesoft SSO integration. This can be done using OpenSSL, as described below. OpenSSL is an open-source general-purpose cryptography library, which is used for the implementation of SSL and TLS.

Perform the following steps to create self-signed certificates using OpenSSL:

Note: In the case that cacert.pem, servercert.pem, and serverkey.pem files are already available, then you can directly proceed to Step 7 below.

1. Locate the OpenSSL CA.pl file, as this file is required to create the dummy CA certificate file.

2. Create a directory to store certificates:

mkdir certificates

3. In Linux, execute the following command:

/usr/lib/ssl/misc/CA.pl -newca

OR,

In Windows, execute the above command replacing the path of CA.pl with the Windows path.

This creates demoCA/cacert.pem (CA Certificate) and demoCA/private/cakey.pem  (private key).

Note: The generated cacert.pem is located inside the demoCA folder.

Viewing the cacert.pem file (CA Certificate)

4. Make a server certificate signing request (CSR) using the following command:

openssl req -newkey rsa:1024 -nodes -keyout newreq.pem -out newreq.pem
Using the openssl reg Command

Note: Make sure to use the same name/value in Common Name as that of the servername/hostname.
Otherwise, when trying to access the server, the browser might warn the user that the name does not match the hostname.
Also, make sure to access the server with the same hostname as mentioned here.

5. Create the server certificate — that is, sign the certificate CSR (certificate signing request) with CA using the following command:

/usr/lib/ssl/misc/CA.pl -sign

Note: Replace the path of the CA.pl file according to your operating system (Windows/Linux).

Creating the Server Certificate

The following files will be created after executing the previous steps.

  • cacert.pem (CA certificate) — created in Step 3
  • newreq.pem (Server key) — created in Step 4
  • newcert.pem (Server certificate or certificate signed by CA) — created in Step 5 above

6. For improved clarity, rename these files:

  • Rename newreq.pem to serverkey.pem
  • Rename newreq.pem to servercert.pem

The following PEM files will be available after renaming the original files:

  • cacert.pem
  • servercert.pem
  • serverkey.pem

7. Convert the servercert.pem file to PKC12 format (*.p12) using the following command:

openssl pkcs12 -export -in servercert.pem -inkey serverkey.pem -out servercert.p12 -name servercertificate

Note: The converted file (servercert.p12) acts as a server certificate and is used to generate keystore. When prompted for the Export Password, enter a password and keep the password safe.

Converting the servercert.pem File to PKC12 Format

8. Create a java keystore file by converting the p12 file to Java Keytool format by using the following command:

keytool -importkeystore -destkeystore servercert.jks -srckeystore servercert.p12 -srcstoretype PKCS12 -alias servercertificate

Note: When prompted for the destination keystore password, enter a password and keep it safe. It will be used as keystore password in the server.xml file. Also, when prompted for source keystore password, enter the export password for input servercert.p12 file created in the previous step (Step 7).

Keytool Command

9. Create a java truststore file by converting the pem file to Java Keytool format by using the following command:

keytool -import -keystore cacerts.jks -alias cacert -file cacert.pem

Note: When prompted for keystore password, enter a password and keep the password safe. It will be used as truststore password in server.xml.

Creating a Java Truststore file

These files will be used while configuring SSL/TLS on the Ephesoft Transact server.

Configuring SSL/TLS for Ephesoft Transact

Introduction

Use the steps in this section to configure SSL/TLS on Ephesoft, after you have generated the certificates with the previous chapter.

If you do not need to perform any of these SSL/TLS setup tasks, please proceed to Configuring Ephesoft Transact for SAML SSO.

SSL/TLS Setup: Configuring the Ephesoft Transact JavaAppServer (Tomcat)

As an example of SSL and TLS setup, this section describes how to use self-signed certificates from the previous chapter and to generate them for testing purposes. If you are using CA certificates in a production environment, provide the details shared by your Certifying Authority.

To configure the Tomcat Connector using CA/Self-Signed Keystore and Truststore certificates, perform the following steps:

  1. Make a backup copy of the existing XML file located in the [Ephesoft_Directory]/JavaAppServer/conf folder.
  2. Open the XML file in edit mode, and locate the existing HTTP/HTTPS connector, as shown in the snapshot.
Existing HTTP/HTTPS Connector

3. Comment the existing connector (default port 8080) and create a new connector by manually adding the following properties in the server.xml file:

protocol: org.apache.coyote.http11.Http11NioProtocol
port: 8443 (change port number if required)
maxThreads: 2000
clientAuth: false
scheme: https
keepAliveTimeout: -1
connectionTimeout: 900000
secure: true
SSLEnabled: true
sslProtocol: TLS
sessionTimeout: 30
truststoreFile: (truststore file generated previously)
truststorePass: <password for trustore>
keystoreFile: (keystore files generated previously)
keystorePass: <password for keystore>
maxKeepAliveRequests: 200 
<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
port="8443" maxThreads="2000" clientAuth="false" scheme="https"
keepAliveTimeout="-1" connectionTimeout="900000" compression="on"
noCompressionUserAgents="gozilla, traviata"
compressableMimeType="text/html,text/xml,text/css,text/javascript,image/jpg,image/ico,image/png,image/jpeg,image/tiff,image/tif"
secure="true" SSLEnabled="true" sslProtocol="TLS" sessionTimeout="30"
truststoreFile="enter trust store complete path" truststorePass="enter truststore password"
keystoreFile="enter key store complete path" keystorePass="enter keystore password"
maxKeepAliveRequests="200" maxPostSize="4194304" />

Note: Ensure that you replace the path of the certificates with the actual location of the certificates.

Certificate Settings

SSL/TLS Setup: Configuring Ephesoft Transact Files

The following files need to be configured in cases where you are setting up Ephesoft Transact files for SSL/TLS:

dcma-batch.properties

Modify the base_http_url to include the https protocol, correct port and hostname.

Modifying batch.base_http_url

dcma-workflows.properties

Modify the wb.hostURL to include the https protocol, correct port and correct host.

Modifying wb.hostURL

web.xml

  • Make a backup copy of the existing web.xml file.
  • Modify the following <context-param> entries:
Parameter Name Updated Value 
port
 Enter the value matching the value in server.xml. Update this only if you have updated the port number.

 
protocol
 Enter HTTPS.
  • The Logout URL needs to be of the following format:
https://{hostname}:{port-number}/dcma/saml/logout
Logout URL

Configuring Ephesoft Transact for SAML SSO

Introduction to SAML

Ephesoft uses Spring Security SAML. Refer to the following resource for more information:

This section provides an overview of the Security Assertion Markup Language (SAML), with additional information where it applies to Ephesoft Transact.

  • SAML Overview — Security Assertion Markup Language (SAML) is an open standard for exchanging authentication and authorization data between parties, in particular, between an identity provider and a service provider.
  • Identity Provider Overview — “An identity provider offers user authentication as a service. Relying party applications, such as web applications, outsource the user authentication step to a trusted identity provider. Such a relying party application is said to be federated, that is, it consumes federated identity. An identity provider is “a trusted provider that lets you use single sign-on (SSO) to access other websites.” SSO enhances usability by reducing password fatigue. It also provides better security by decreasing the potential attack surface.”

Source — Wikipedia (8/28/18)

  • Service Provider Overview — In SAML, a service provider “is a system entity that receives and accepts authentication assertions in conjunction with a single sign-on (SSO) profile of the Security Assertion Markup Language (SAML).”

Source — Wikipedia (8/28/18)

SAML v2 Support in Ephesoft Transact

Ephesoft Transact supports Spring Security-based SAML SSO. The important components for configuring SSO are as follows:

  • applicationContext-security.xml: User can configure all Spring Security-related beans from this XML.
  • SAML IdP: A third-party IdP (Identity Provider) is required to configure the AuthenticationHandler. Metadata from Ephesoft is required to be registered with the IdP.
  • JKS Keystore: A Keystore needs to be set up for general authentication.
  • Logout URL: This parameter is required to redirect the user to a page when they click on the Ephesoft logout button.
  • Mode: This parameter can have two values; AUTHENTICATION_ONLY and AUTHENTICATION_AUTHORIZATION. Based on this parameter, Ephesoft Authorization is used.
    • If the AUTHENTICATION_ONLY parameter is used, then the provided username is used for authorization using configured connectivity.
    • If AUTHENTICATION_AUTHORIZATION is used, Ephesoft looks for Roles and IsSuperAdmin attributes in the SAML Response. The attribute names that are passed through SAML response are configurable.

Configurations for Integrating SAML-Enabled Spring Security Framework

Introduction

This section provides the details to configure Ephesoft Transact for SAML SSO. If Ephesoft Transact has already been configured, skip to the section, Configuring the ADFS Server.

The following files need to be configured:

applicationContext.xml

  • Uncomment the applicationContext-security.xml resource in applicationContext.xml to use SAML SSO.
Uncommenting applicationContext-security.xml

web.xml

  • Uncomment the springSecurityFilterChain and its filter mapping.
  • Comment out the following elements in the web.xml file:
    • SessionTimeoutFilter and its filter mapping
    • SessionTimeoutServlet and its filter mapping
    • All security-constraints and login-config nodes
    • The session-config node needs to be commented out in the xml file.
  • Configure the logout URL according to the server details.
    • The logout URL needs to follow this form:

https://{hostname}:port/dcma/saml/logout

  • The authenticationFilter and its mapping must be prior in sequence to the authorizationFilter in the filter chain.
Authentication Filter
  • Select the appropriate value for authenticationType as per the following logic:
    • 1: If only the username will be passed along as attribute in the SAML message, and authorization will be determined by Ephesoft Transact.
    • 2: If the username, group and isSuperAdmin values will be passed along as attributes in the SAML message.
Authentication Type
If authenticationType=1 (i.e. Authentication Only), roles need to be defined as per the property defined in user-connectivity.properties (<Ephesoft_Installation_directory>\Application\WEB-INF\classes\META-INF\dcma-user-connectivity\user-connectivity.properties). The user.connection property defines where the roles will be mapped.
If user.connection=0, roles for the user will be mapped in LDAP
user.connection=1, roles for the user will be mapped in AD
user.connection=2, roles for the user will be mapped in tomcat-users.xml(<Ephesoft_Installation_directory>\JavaAppServer\conf\tomcat-users.xml)
If authenticationType=2 (i.e. Authentication and Authorization are done by IdP) and the group is not received from ADFS server, then, by default the system will use the group defined in default_group property of application.properties (<Ephesoft_Installation_directory>\Application\WEB-INF\classes\META-INF\application.properties).
User Connection Properties

Note: Mapping roles for the user in AD is a feature that is only available in Ephesoft Transact 4.5.0.2 and later releases.
This AD role-mapping function is not supported in releases prior to Release 4.5.0.2.

Multiple Group Support in web.xml

By default, when using SSO, Ephesoft Transact presumes that every user will be associated with a single group. To enable a single user with multiple groups for authentication Type = 2, certain configuration changes are required.

Follow the steps in SAML SSO | Multiple Groups Support to make such configurations for multiple groups.

samlKeystore.jks

A Java Keystore (JKS) is a repository of security certificates. SAML exchanges involve usage of cryptography for signing and encryption of data. This keystore will contain a certificate and private key that will be used to digitally sign the SAML messages and to encrypt their content.

A default keystore with the name samlKeystore.jks is provided in the application. However, the user can also create a custom keystore.

Create a private key

  1. Open the command prompt at keytool path and run the following command for generating the private key for customKeystore.

C:\Program Files\Java\jdk1.7.XXXX\bin>keytool.exe -genkeypair -alias “alias for private key” -keypass “password for key” -keystore “path to keystore”

  1. Enter “nalle123”.
  2. Complete the following prompts as applied to your organization.

After confirming all the added information, the private key will be added to the keystore.

  • Place this newly created customKeystore.jks file at the following location:

“EPHESOFT_HOME/application/WEB-INF/classes/security/”

4. Update the applicationContext-security.xml file as described below.

Note: Ephesoft recommends that you record separately the alias for the private key created and the corresponding password. These are required for an upcoming task.

applicationContext-security.xml

  1. In the bean “epheSamlFilter”, update the value of the constructor argument which you have added in IdP, as per the below logic. The third constructor argument must be true for superadmin access, otherwise this must be false. If this is from IdP, a claim name can be passed to indicate whether the user is superadmin or not. That claim name can be specified here.
  • Index=0: Path of Username Attribute passed in SAML message.
  • Index=1: Path of Group Attribute passed in SAML message.
  • Index=2: Path of IsSuperAdmin Attribute passed in SAML message.

Note: If you are using authenticationType=2, the constructor arg 2 should be false. Otherwise, it grants access to all users as super admin.

<bean id="epheSamlFilter" class="com.ephesoft.dcma.webapp.SamlFilter">
<constructor-arg index="0" value="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"/>
<constructor-arg index="1" value="http://schemas.microsoft.com/ws/2008/06/identity/claims/role"/>
<constructor-arg index="2" value="true"/>
</bean>
  1. In the beans “successRedirectHandler” and “failureRedirectHandler”, the user can set URLs for successful and failed authentications respectively. By default, it is configured as /home.html.
  2. In the bean “keyManager”, the constructor arguments need to be populated according to the following logic:
  • First constructor argument: the path of keystore needs to be added here (Default: classpath:security/samlKeystore.jks). If you have created new keystore, specify that keystore.
  • Second constructor argument: the password of keystore needs to be added here (Default: nalle123).
  • Third constructor argument: the private key and corresponding password created in the previous section need to be added in the map constructor (Default: <entry key=”apollo” value=”nalle123″ />).
  • Fourth constructor argument: the private key to be used needs to be provided here (Default: apollo).

Note: You can add more than one private key in the map constructor in the third argument. Just mention which key you need to use for the current scenario in the fourth argument.

Note: Java keystore Information and respective keystore passwords can be encrypted. The complete procedure is described in How to Encrypt Passwords in Ephesoft Files.

To use encryption, you also need to uncomment the following commented bean set in the applicationContext-security.xml file.

certStorePasswordDecryptor Bean

Here, in the beans “certStorePasswordDecryptor” and “certPasswordDecryptor”, replace the string “EncryptedPassword” with your encrypted password value, keeping the quotation marks (example: “nROcbAKcSGR7CsxrlNVZSA==”).

Then, comment out the similar bean “keyManager” right below the above-mentioned lines:

Commenting Out keyManager
  1. Update the “metadataGeneratorFilter” bean as shown below. Perform these steps to configure the metaGeneratorFilter.

a. This task requires the entityId, which the customer must provide to Ephesoft. The customer security administrator typically provides the entityID.

An entityID is a globally unique name for a SAML entity. Specific requirements for the entityId differ according to the requirements of the specific identity provider.

Update the entityId with the value that pertains to the user’s metadata, which is to be uploaded at the identity provider (IdP).

Update the entityBaseURL with hostname and port number values. This will be the public DNS address, and contains https:// at the beginning and /dcma at the end.

<bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
       <constructor-arg>
              <bean class="org.springframework.security.saml.metadata.MetadataGenerator">
                     <property name="entityId" value="urn:super:ephesoft:ggn" />
                     <property name="requestSigned" value="true" />
                     <property name="entityBaseURL" value="http://{hostname}:{portNumber}/dcma" />
                     <property name="extendedMetadata">
                           <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
                                  <property name="signMetadata" value="true" />
                                  <property name="idpDiscoveryEnabled" value="false" />
                           </bean>
                     </property>
              </bean>
       </constructor-arg>
</bean>

Configure the “metadata” Metadata configuration can be done in one of the following ways:

a. Save IdP metadata in a file and place it in the following folder:

“EPHESOFT_HOME/application/WEB-INF/classes/security”

b. Update the bean as shown below and specify the classpath as “/security/<filename.xml>”.

c. To disable signature verification, set the metadataTrustCheck property to false.

<bean id="metadata" class="org.springframework.security.saml.metadata.CachingMetadataManager">
 <constructor-arg>
  <bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
       <constructor-arg>
        <bean class="org.opensaml.saml2.metadata.provider.ResourceBackedMetadataProvider">
              <constructor-arg>
               <bean class="java.util.Timer"/>
              </constructor-arg>
              <constructor-arg>
               <bean class="org.opensaml.util.resource.ClasspathResource">
              <constructor-arg value="/security/FederationMetadata.xml"/>
               </bean>
              </constructor-arg>
              <property name="parserPool" ref="parserPool"/>
        </bean>
       </constructor-arg>
       <constructor-arg>
<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
              <property name="requireLogoutResponseSigned" value="true"/>
       </bean>
       </constructor-arg>
       <property name="metadataTrustCheck" value="false"/>
  </bean>
 </constructor-arg>
</bean>

d. Using the IdP metadata URL, modify the “metadata” bean and use ExtendedMetadataDelegate and HttpMetadataProvider as shown below. Also, define the metadataTrustCheck as false to skip signature validation. Update the metadata URL to the IdP metadata URL that is provided in the following code:

https://<ADFSServer>/FederationMetadata/2007-06/FederationMetadata.xml

<bean id="metadata" class="org.springframework.security.saml.metadata.CachingMetadataManager">
 <constructor-arg>
  <list>
   <bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
       <constructor-arg>
        <bean class="org.opensaml.saml2.metadata.provider.HTTPMetadataProvider">
         <constructor-arg>
              <value type="java.lang.String">https://ADFSServer/FederationMetadata/2007-06/FederationMetadata.xml</value>
         </constructor-arg>
         <constructor-arg>
              <!-- Timeout for metadata loading in ms -->
              <value type="int">5000</value>
         </constructor-arg>
         <property name="parserPool" ref="parserPool"/>
        </bean>
       </constructor-arg>
       <constructor-arg>
       <bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
              <property name="requireLogoutResponseSigned" value="true"/>
       </bean>
       </constructor-arg>
         <property name="metadataTrustCheck" value="false"/>
   </bean>
  </list>
 </constructor-arg>
</bean>
  1. SHA-256 Support: By default, the application is configured to provide SAML configuration with SHA-1. To configure SHA-256, comment the bean for SHA-1 and uncomment SHA-256 bean.
SHA Settings

Testing at the SSOCircle

Perform the following steps to test Ephesoft at the SSOCircle (IdP).

  1. Create an account at the SSOCircle and log in.
  2. Add the service provider’s metadata in the SSOCircle.

You can download Ephesoft metadata using the following path:

http://{ephesoft_ip}:{port}/dcma/saml/metadata 

  • The entityID should be the FQDN that is registered at the SSOCircle.
  • The SSOCircle metadata is available from the following sample XML file: idp-meta.xml.

Configuring Ephesoft Transact and ADFS

Configuring Ephesoft Transact for the ADFS Server

Before completing these steps, ensure that the following prerequisites are in place:

  • Ensure that Ephesoft Transact has already been configured on HTTPS.
  • Ensure that the Ephesoft Transact server is running prior to downloading metadata.
  • In the case that a broken page is displayed while downloading Ephesoft metadata, this means that the Ephesoft server did not start correctly. Resolve any errors that caused a failure by using the following log file:
  • <Ephesoft_HOME>/Application/logs/dcma-all.log

Follow these steps to configure ADFS settings on Ephesoft Transact:

Obtain the ADFS Metadata

  1. Download the ADFS metadata from the default URL:

https://<ADFSServer>/FederationMetadata/2007-06/FederationMetadata.xml 

No Ephesoft-related configuration is required for downloading the ADFS metadata.

  1. Copy the downloaded metadata at the following path:

[Ephesoft_Directory]/Application/WEB-INF/classes/security

Import the ADFS Certificates to Ephesoft Transact

To export the certificate from ADFS, view the section Exporting the Certificate from the ADFS Server.

To import ADFS certificates, use the following command:

keytool.exe -importcert -alias adfssigning -keystore samlKeystore.jks -file adfsCertificate.cer

Configuring the ADFS Server for Ephesoft Transact

Follow these steps to set up the ADFS Server for operation with Ephesoft Transact.

  1. Download the Ephesoft Transact metadata from the following path:

https://<ephesoft_ip:port>/dcma/saml/metadata

  1. Add the Relying Party Trust with the following steps:

a. In ADFS, navigate to the following folder:

AD FS\Trust Relationships

b. Right-click the Relying Party Trusts folder under ADFS\Trust Relationships. The following snapshot illustrates this navigation.

Relying Party Trusts Folder

c. From the popup menu, click Add Relying Party Trust…

The Add Relying Party Trust Wizard appears.

Add Relying Party Trust Wizard
  1. Choose (select) the Import data about Relying Party from a file option and select the metadata XML file saved in step 1.
  2. Provide a display name and click Next by choosing the default setting.
Entering a Display name
  1. Click Finish to complete this part of the setup. The Edit Claim Rules dialog should open automatically. Alternatively, you can right click the added relying party name and select Edit Claim Rules….
  2. Add the following claims.

a. NameId: Sends the Name ID.

i. Rule Name: NameId

ii. Choose “SAM-Account-Name” as the LDAP Attribute and “Name ID” as the Outgoing claim type.

b. FirstName: Sends name details.

i. Rule Name: FirstName

ii. Choose “SAM-Account-Name” as the LDAP Attribute and “Name” as Outgoing claim type.

c. Group: Sends group details.

Define this rule as per your configuration. For example, the user can be a member of multiple groups. The service provider expects a single group — namely ‘Enterprise’.

Sending all groups will be irrelevant to the service provider.

A filter can be defined for this scenario by the two following rules:

i. This rule retrieves all groups and adds them as an incoming claim for the next rule.
The output of this claim will be used by the next rule for processing.
Add Rule Name as ‘Get all groups user belongs’.
Define the Custom Rule as follows:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]

=> add(store = "Active Directory", types = ("http://schemas.microsoft.com/ws/2008/06/identity/claims/role"), query = ";tokenGroups;{0}", param = c.Value);

ii. Filtering Groups — Define a filter to restrict groups sent in claims.

— Select the Pass Through or Filter an Incoming Claim

— Add the Rule Name as Filter Groups.

— In the field, Pass through all claims that start with specific value, specify Enterprise.

The group claim rules need to be configured only if authenticationType=2 is set in the web.xml file.

In the web.xml file, if the authenticationType is 1 (that is — SSO Authentication Only), then Authorization will be handled by Ephesoft Transact.
ADFS just needs to send the username as a claim to Transact.

Note: The constructor argument value, which is cited in the topic applicationContext-security.xml, can be found in ADFS. While editing claim rules, you can find the claim name by selecting the View Rule Language button. You can copy the claim name from the shown rule and paste directly from ADFS into the Ephesoft Transact epheSamlFilter to avoid mistakes.

  1. Open the Relying Party Trust by double-clicking it. In the Advanced tab, change Secure Hash Algorithm to SHA-1/SHA-256, to be as configured in Ephesoft Transact.

Exporting the Certificate from the ADFS Server

  1. In ADFS, select the Certificate option under ADFS/Service.
  2. Double click the certificate to export. Navigate to the Details tab, click Copy to File and save this as a DER-encoded certificate in your file system.

Note: The exported certificates can be saved to any accessible path on your file system. This exported certificate from ADFS needs to be imported in samlKeystore.

Certificate > Details Tab
Certificate Export Wizard

Successful Configuration

When accessing the Ephesoft Transact page, the user will be redirected to the ADFS login screen.

ADFS Login Screen

On successful authentication, the user will be redirected to the Ephesoft Transact page.

Configuring Okta with Ephesoft Transact

Creating the Okta Developer Account

Perform the following steps to configure Okta for inter-operation with Ephesoft Transact.

  1. Create a developer account at Okta if you have not already done so. You can sign up at Okta.
  1. Launch Okta.
  2. Click the Admin tab and click Add Applications.
Admin Applications screen
  1. Click the Create New App button.
Create New App
  1. Select SAML 2.0 and then click Create.
Select SAML 2.0 for the new app
  1. Configure the settings for the new SAML 2.0

a. Enter General Settings and click Next.

General Settings screen
  1. Enter SAML Settings and define the following fields.
SAML Settings screen

a. Single sign on URL should be of the following form:

http://{hostname}:{portNo}/dcma/saml/SSO

b. Audience URI (SP Entity ID) should be any unique Entity ID. Please note down its value as it will be needed while configuring Ephesoft Transact.

c. In Attribute Statements, the username must be added. It is necessary for authorization in Ephesoft Transact. Note down the attribute name you have given in Name tag as it is necessary in a later task, while configuring Ephesoft Transact.

8. Click Show Advanced Settings and check (enable) Enable Single Logout. Define additional settings as follows:

Advanced Settings in SAML 2.0 setup

a. Single Logout URL — must be in the following form:

http://<hostname>:<port>/dcma/saml/SingleLogout

b. SP Issuer — the issuer for the service provider and must be in the following form:

http://<hostname>:<port>/dcma/saml/metadata

c. Signature Certificate — use the following steps to upload the public key certification exported from the samlKeystore.jks file:

i. Click Next.

ii. In Step 3 Feedback, check (enable) the setting for: I’m an Okta customer adding an internal app.

iii. Click Finish.

Select a reason for this SAML 2.0 app
  1. Once the configuration is completed successfully, the following screen appears with Sign On settings:
Sign On settings for the SAML 2.0 App
  1. Copy the URL. This is required later when configuring Ephesoft Transact.

Because Okta metadata is hosted at https, the public key needs to be imported in JRE cacerts. Perform the following steps to import the public key into cacerts:

a. Navigate to the https URL of the Okta app.

b. Press Ctrl+Shift+I (the letter I as in India) and navigate to the Security

Security tab

c. Click View Certificate. Browse to the Details Click Copy to File.

Save this as a DER-encoded certificate in your file system.

Certificate > Details screen
Certificate Export Wizard
Selecting the file save location

d. Import this certificate in cacerts.

i. Navigate to {InstallDir}\Dependencies\jdk\bin and open the command prompt here.

ii. Run the following command to import the Okta certificate in cacerts.

{InstallDir}\Dependencies\jdk\bin>keytool.exe -import -file "path to downloaded okta certificate" -keystore {InstallDir}
\\Dependencies\jdk
\jre\lib\security\cacerts

Assigning People in the Okta Account to Ephesoft Transact

Perform the following steps to assign people to Ephesoft Transact, which will give them permission to use the application.

  1. Click the People tab and click Assign to People.
Admin People tab in SAML 2.0 setup

The screen displays the people who are currently in your directory.

Viewing current people for the SAML 2.0 app
  1. Click Assign for the user you want to assign. Enter the username to set the login requirement. This user is now assigned to Ephesoft Transact.
Viewing usernames for the app
  1. Click Done to close this screen, or repeat these steps to assign additional people.

Adding People to the Okta Account

Perform the following steps to add additional people to your Okta account.

  1. Click Directory and then select People.
Directory > People navigation
  1. Click Add Person and then enter details.
Add Person to provide details as prompted

Configuring Ephesoft Transact to Operate with Okta

To configure Ephesoft Transact for operation with Okta, edit or set up the applicationContext.xml and web.xml files, as would be required if setting them up for other identity providers (IdPs).

  1. In the tomcat-users.xml file, add the username, password, and role for the user.
  • This is a required setting for authentication and authorization in Ephesoft Transact.
  • The username should be the first name of the Okta user.
  1. In the applicationContext-security.xml file, make the following changes:
  • In the epheSamlFilter bean, add the name of the attribute that you added in Okta.
epheSamlFilter bean
  • In the metadataGeneratorFilter bean, enter entityID as configured in Okta.
metadataGeneratorFilter bean
  • In the metadata bean, add the URL of the Okta metadata which was copied to an Ephesoft folder location while adding Ephesoft Transact in Okta (a previous procedure).
metadata bean
  • By default, the application is configured to provide SAML configuration with SHA-1.
  • For additional information about configuring SHA, refer to the earlier topic:
certStorePasswordDecryptor bean
  • Here, in the beans “certStorePasswordDecryptor” and “certPasswordDecryptor”, replace the string “EncryptedPassword” with your encrypted password value, keeping the quotation marks (example: “nROcbAKcSGR7CsxrlNVZSA==”).

Also, comment out the similar keyManager bean, which is immediately below the above-mentioned lines:

keyManager bean
  1. Save all above changes in the applicationContext-security.xml
  2. Start the Ephesoft Transact server.

On hitting any of the Ephesoft Transact URLs, the user will be redirected to the Okta Sign In page.

Okta Sign In screen
  1. With successful Okta authentication, the user will be redirected to the Ephesoft Transact login page.

Exporting the Self-signed Certificate from Keystore

  • Open the Key Tool in the command prompt. (Key tool is available in the JDK.)
  • Execute the following command:
keytool -export -alias <name of the entry to process> -storepass <password of keystore> -file <ephesoft.cer> -keystore <path to keystore file>

Troubleshooting SAML 2.0 SSO in Ephesoft Transact

General Troubleshooting Tasks

General troubleshooting may entail one or more of the following configuration issues or activities:

Error: Description and Resolution
1. Server Startup issues

Issue — This issue that may occur on server startup. Errors are observed with the PKIX path building having failed:

sun.security.provider.certpath.
SunCertPathBuilderException:
unable to find valid certification path to requested target

Resolution — This issue originates with the misconfiguration of certificates.

  • Your https endpoint certificates presented by the IdP could not be verified.
  • Please validate if the IdP certificates have been imported properly in cacerts.
2. IdP Login Page not displaying

Issue — With this issue, the user is not redirected to the IdP login page upon opening any screen.

Resolution — In the web.xml file, determine if the springSecurityFilterChain is not commented. Also, verify that the filter and its mapping precede the authenticationFilter.
3. Access Denied screen is shown despite successful authentication

Issue — With this issue, the user is getting successfully authenticated with IdP. Although the user has privilege to access the screen, the Access Denied page is shown in error.

Resolution — In the web.xml file, verify if the authenticationFilter and its mapping is defined prior to the authorizationFilter.
4. User is redirected to a broken page

Issue — With this issue, the user gets successfully authenticated on the IdP, but is redirected to a broken page.

Resolution — The broken page is displayed in cases where there are some missing configurations.

  • Verify that the entityBaseURL property is specified in the metadataGeneratorFilter.
  • If ADFS is configured, verify that the NameID claim is being passed in SAML message. This is mandatory to be passed for ADFS.
5. No redirection to the SSO Login screen upon login to Transact, with Access Denied message

Issue — With this issue, and after configuring SSO, the Ephesoft Transact page is not redirected to the SSO login page. An Access Denied error is displayed.

Resolution — Follow these steps as a possible resolution to this issue:

1. Verify that the applicationContext-security.xml resource is uncommented in the applicationContext.xml file (<Ephesoft Installation Directory>\Application). The following snapshot illustrates this configuration:

Uncommenting applicationContext-security.xml in applicationContext.xml file

 

 

 

2. Verify that the springSecurityFilterChain filter is uncommented in the web.xml file located at [Ephesoft_Directory]\Application\WEB-INF.

The following snapshot illustrates this configuration:

springSecurityFilterChain filter in web.xml file

Note:   The springSecurityFilterChain filter is responsible for redirection to the SSO login page.

3. Ensure that the springSecurityFilterChain filter is the first filter in the web.xml file. If it is placed at the end, move it to be the first filter.
6. Broken page does not correspond to the sent message

Issue — In this issue, the broken page in the InResponseToField of the response does not correspond to the sent message.

Resolution — Verify that the same URL is used for sending the request and receiving the response. Typically, this issue arises when the authentication request is initialized from a localhost address or http scheme, while the response is received at a public hostname or https scheme.
7. Broken page appears after idle period

Issue — In this issue, an application redirect to a broken page is shown after the system is idle for a period of time.

Resolution — Verify the following settings to resolve this behavior:

  1. Comment the session-timeout node defined in the web.xml file.
  2. In the applicationContext-security.xml file, add a property maxAuthenticationAge to the bean class WebSSOProfileConsumerImpl:
  • The maxAuthentication age(in seconds) determines the maximum session time set for the IdP.
  • The default value is 7200 seconds.
  • This value should match the value that was set at the IdP.
8. SuperAdmin privileges are granted to non-SuperAdmin users

Issue — In this issue, users that do not have the superadmin role may be granted superadmin privileges.

Resolution — Verify the index=2 setting in the epheSamlFilter bean in the applicationContext-security.xml file Determine if this value is true.

  • If set to true, it grants all users with superadmin privileges.
  • To resolve this issue, modify the value to either false or an empty string.
9. General Log Monitoring

If there are any issues encountered during configuration or authentication, please check the logs in the following location:

  • <Ephesoft-Installation-Directory>/Application/logs/dcma-all.log

Follow the instructions defined inside the logs. If the problem persists, share the following information with Ephesoft Support:

  • INFO level logs
  • SAZ file — Collect the Fiddler trace while accessing your application and authenticating to Azure AD and share this SAZ file.

Logging for SAML Requests

To obtain more logging information about SAML requests, add the following lines to the log4j.xml file placed under directory <Ephesoft_HOME>/Application/log4j.xml. Adding the following lines will provide INFO-level logs for SAML requests and responses in the dcma-all.log.

<Logger name="org.opensaml"
level="INFO" additivity="false">
<AppenderRef ref="CORE"/>
</Logger>
<Logger name="org.springframework.security.saml"
level="INFO" additivity="false">
<AppenderRef ref="CORE"/>
</Logger>

Getting the Fiddler Trace

To use Fiddler, which is a free web debugging proxy from Telerik, navigate to the following page for download and installation: Download Fiddler Classic.

Note: Account registration is required.

After you have installed Fiddler, perform the following steps to start the capture:

  1. Go to http://fiddler2.com/home (.NET2 or .NET4 is fine).
  2. Once installed, go to Tools > Fiddler Options > Https
  3. Check Decrypt HTTPS traffic, and click Yes for the popup screens, as prompted.

You will receive a few pop-up screens that are required in order to install the Fiddler root certificate. The Fiddler root certificate allows Fiddler to function as an intermediate agent in the HTTPS session.

  1. Click Yes to continue.
  2. Click Clear Cache on the Fiddler
  3. Click Edit > Remove All Sessions.
  4. Open your favorite browser. Verify it is capturing data in Fiddler.
  5. Reproduce the issue in the browser.
  6. Stop the Fiddler trace once it is done.
  7. Save the Fiddler trace as an SAZ file.