Checklist: Ephesoft with ADFS over SAML 2.0 with Authentication Type 1 and Authorization using Tomcat

Ephesoft configuration with ADFS over SAML 2.0 with Authentication Type 1 and Authorization using Tomcat

This wiki provides you details related to what all configuration needs to be taken care of when configuring Ephesoft with ADFS over SAML 2.0 with Authentication Type 1. Authentication Type 1 means we are authenticating using SSO but authorizing using Tomcat, LDAP or Active Directory. In this article we will focus on Authorization with Tomcat.

 

How Does Authentication with SSO and Authorization with Tomcat works ?

  • We only provide authentication details to the Identity Provider.
  • Identity provider verifies the validity of the user and sends back acknowledgement 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 tomcat-users.xml file.
  • Username received as response is matched with the records in 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 application.properties and if match is good then the user is provided with super admin access.

 

Pre-requisite:

  1. Active Directory Federation Services Installed
  2. Active Directory Installed.
  3. Ephesoft Transact 4.5.0.0 or onwards Installed

 

Configuration Files Required

  1. server.xml
  2. applicationContext.xml
  3. web.xml
  4. applicationContext-Security.xml
  5. dcma-batch.properties
  6. Ephesoft saml metadata file that needs to be imported at Ephesoft Side.
  7. ADFS Federation metadata file
  8. Valid KeyStore (JKS) in which we need to import ADFS certificate.
  9. application.properties file
  10. user-connectivity.properties file
  11. tomcat-users.xml file

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:

  1. You can configure any port over HTTPS. In this article we will be configuring tomcat over SSL over port 8443.
  2. Refer this article to understand how to configure tomcat over HTTPS.
  3. Refer this article to understand how to generate truststore  and KeyStore
  4. Download the sample server.xml from here
  5. Download truststore and keystore file here. Password for both files is “abhishek”.

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


application-context.xml

  • Uncomment <import resource=”classpath:/META-INF/applicationContext-security.xml” />  from application-context.xml file.
  • Above needs to be done to enable SAML configuration which is configured in applicationContext-security.xml file.

 

Note: 

  1. 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 change in logout URL  to point it to correct port and URL
  • Select 1 for authenticationType bean

Note: 

  1. Download the sample web.xml file from here.

security folder

  • Make sure you are placing your sample JKS file in this folder. By default Ephesoft Provides samlKeystore.jks which can be used to configure Ephesoft.
  • Make sure the ADFS cert is imported in the above JKS file
  • Make sure you have download FederationMetadata file in xml format from your ADFS server and placed the same in security folder.
  • Command to import ADFS cert to is keytool.exe -importcert -alias <alias name> -keystore “<Keystore path>” -file “<cert path>”
  • Hit https://<<domainname>>/FederationMetadata/2007-06/FederationMetadata.xml and get the ADFS metadata file and save it in security folder.

 

Note: 

  1. Download the sample security folder from here. Please note that ADFS Metadata file and the cert will not work at your end. This is only for reference purpose

 


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.

  • If you have created you own keystore then make sure you are providing correct name and path of the keystore file and keystore password.

  • Make sure 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

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

 

  • Based on the Secure hash algorithm make sure you comment / uncomment SHA-1 or SHA-256 which is controlled by bean as seen in below screenshot.

 

Note: 

  1. Download the sample applicationContext-Security.xml from here.
  2. Since we are only authenticating with SSO only <constructor-arg index=”0″> in epheSamlFilter bean is important to be configured.

user-connectivity.properties

  • user.connection property in this file needs to be set to 2.

Note: 

  1. Download the sample user-connectivity.properties from here.

 


tomcat-users.xml

  • Make sure that username and roles entry is present in this file.

Note: 

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

application.properties

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

 


Configuration Settings at Active Directory Federation Services

  • Follow this wiki article on understanding how configuration needs to be done at ADFS side.

Order of configuring SSO

In this section you will understand the order in which each of the above mentioned files needs to be configured.

  1. Start with generating JKS files for to configure tomcat over SSL if you do not have truststore and keystore prior.
  2. Configure tomcat over https and also make changes in dcma-batch.properties file and workflow.properties file for batch.base_http_url and wb.hostURL properties respectively.
  3. Start configuration changes in applicationContext.xml, web.xml file.
  4. Create JKS file if you want provided in the security folder.
  5. Download the ADFS certificate and FederationMetaDataFile from ADFS and place it in security folder.
  6. Make changes in applicationContext-Security file, remember to take care of the changes as mentioned above.
  7. Finally proceed with the changes in user-connectivity.properties, tomcat-users.xml and application.properties file.
  8. Download the ephesoft metadata file and import the file to create relying party trust on ADFS.
  9. Make sure all the properties are correct for relying party created and now create claim rules.
  10. Restart the ephesoft service.