Transact

  1. Home
  2. Transact
  3. System Configuration
  4. User Connectivity
  5. Configuring Ephesoft Transact with ADFS over SAML 2.0 using Apache Tomcat

Configuring Ephesoft Transact with ADFS over SAML 2.0 using Apache Tomcat

This article describes how to configure Ephesoft Transact with Active Directory Federation Services (ADFS) over SAML 2.0 using Authentication Type 1. Authentication Type 1 means we are authenticating using SSO but authorizing using Apache Tomcat, LDAP, or Active Directory. In this article, we will focus on authorization with Apache Tomcat using port 8443.

Overview

How does authentication with SSO and authorization with Apache Tomcat work?

  • We only provide authentication details to the Identity Provider.
  • The identity provider verifies the validity of the user and sends back acknowledgment as a part of SAML Response.
  • If validation is successful the selected Authorization method is taken into consideration. If user.connection is set to value 2 then authorization happens using the tomcat-users.xml file.
  • The username received as a response is matched with the records in the tomcat-users.xml file and if matching entry is found then its roles detail is picked.
  • This role gets matches with user.super_admin=admin in the application.properties file and if the match is good then the user is provided with super admin access.

Prerequisites

  • Active Directory Federation Services (ADFS) is installed
  • Microsoft Active Directory is installed.
  • Ephesoft Transact 4.5.0.0 or above is installed

Configuration Files Required

  • server.xml file
  • applicationContext.xml file
  • web.xml file
  • applicationContext-Security.xml file
  • dcma-batch.properties file
  • Ephesoft SAML metadata file (imported on Ephesoft side).
  • ADFS Federation metadata file
  • Valid KeyStore (JKS) in which we need to import ADFS certificate.
  • application.properties file
  • user-connectivity.properties file
  • tomcat-users.xml file

User Instructions

This section details the order in which the above-mentioned files need to be configured.

  1. Start with generating JKS files to configure Apache Tomcat over SSL (if you do not already have truststore and keystore).
  2. Configure Apache Tomcat over HTTPS and make changes in the dcma-batch.properties file and workflow.properties files for batch.base_http_url and wb.hostURL properties respectively.
  3. Start configuration changes in applicationContext.xml and web.xml files.
  4. If desired, create a JKS file in the security folder.
  5. Download the ADFS certificate and FederationMetaDataFile from ADFS and place it in the security folder.
  6. Make changes in the applicationContext-Security file, as described below.
  7. Finally, proceed with the changes in user-connectivity.properties, tomcat-users.xml, and application.properties files.
  8. Download the ephesoft metadata file and import the file to create relying party trust on ADFS.
  9. Ensure all the properties are correct for relying party created and create claim rules.
  10. Restart the ephesoft service.

Refer to the Checklist Components below for detailed information on what changes to make in the configuration files.

Checklist Components

server.xml

  • Configure connection port 8443
  • Comment connection port 8080
  • Restart the Ephesoft service and verify if it works fine over https.

Note:

  • You can configure any port over HTTPS. In this article, we will be configuring Apache Tomcat over SSL using port 8443.
  • Refer to How to Set SSL/TLS in Apache Tomcat for information on how to generate truststore and KeyStore.
  • You can download the sample server.xml from here.

Below is the screenshot on how server.xml should look like:

Figure 1. Sample server.xml


application-context.xml

Remove the following comment from the application-context.xml file:

<import resource=”classpath:/META-INF/applicationContext-security.xml” />

Note: This must be done to enable SAML configuration, which is configured in applicationContext-security.xml file.

Figure 2. Remove Comment from application.context.xml

Note: You can download the sample applicationContext-security.xml file from here.


web.xml

  • Uncomment the springSecurityFilterChain filter and its filter mapping.
  • Comment out the sessionTimeoutFilter and its filter mapping
  • Comment out the SessionTimeoutServlet and its Servlet Mapping
  • Comment out all security-constraints and
  • Comment login-config nodes
  • Place authentication filter and its filter mapping below springSecurityFilterChain
  • Make a change in the logout URL to point it to correct port and URL
  • Select 1 for authenticationType bean

Note: You can download the sample web.xml file from here.


security folder

  • Ensure you are placing your sample JKS file in this folder. By default, Ephesoft provides samlKeystore.jks which can be used to configure Ephesoft.
  • Ensure the ADFS cert is imported in the above JKS file
  • Ensure you have downloaded the FederationMetadata file in XML format from your ADFS server and it is placed in the same security folder.
  • The command to import ADFS cert to is
keytool.exe -importcert -alias <alias name> -keystore "<Keystore path>" -file "<cert path>"
  • Select https://<<domainname>>/FederationMetadata/2007-06/FederationMetadata.xml and retrieve the ADFS metadata file. Save it in the security folder.

Figure 3. Security Folder

Note: You can download the sample security folder from here. This is only for reference purposes, the ADFS Metadata file and the Cert will not work at your end.

applicationContext-security.xml

  • Change the constructor arguments for epheSamlFilter bean.These constructor-arg values are based on the rule language you define in ADFS Claim Rules. Argument index 0 takes username details and argument 2 takes group details.

Figure 4. epheSamIFilter Bean

  • If you have created your own keystore, ensure you are providing the correct name and path of the keystore file and keystore password.

Figure 5. Enter KeyStore Location

  • Ensure the entityId entered here is correct and is same as what you will be defining in ADFS. EntityId is defined in the value attribute of entityId property name.

Figure 6. Enter Entity ID

  • Make changes in metaDataFilter Bean and metaData filter. Ensure to use correct metadata bean as defined in this file.  Ensure you provide correct name for the FederatinMetadata.xml file

Figure 7. Change metaDataFilter Bean

  • Based on the Secure hash algorithm, comment or uncomment SHA-1 or SHA-256, depending on which is controlled by the bean. Refer to the screenshot below.

Figure 8. Edit Comment 

Note: You can download the sample applicationContext-Security.xml file from here. As we are only authenticating with SSO the <constructor-arg index=”0″> in epheSamlFilter bean is important to be configured.

user-connectivity.properties

The user.connection property must be set to 2.

Note: You can download the sample user-connectivity.properties file from here.

 


tomcat-users.xml

  • Ensure the username and roles entries are present in this file.

Figure 9. Confirm Username and Roles Entries

Note: 

  1. It is not mandatory to mention the password for the username record entered in this file.
  2. The values in the username and role name are two mandatory fields for authorization.

application.properties

  • This file is used to define Super Admin Group Names.
  • Two properties that require change are user.super_admin (where we define super admin groups) and update_super_admin_group (where we will need to change the flag to true).

Active Directory Federation Services Configuration Settings

Refer to ADFS Configuration Requirements for information on configuring ADFS settings.

Was this article helpful to you? Yes No