Using SAML Authentication - EcoSys - Administration & Configuration - Hexagon

EcoSys System Administration

Search by Category
Administration & Configuration
EcoSys Version

This section describes the process of setting up EcoSys as a Service Provider (SP) initiated SSO to work with any SAML 2.0 compliant Identity Provider (IdP).

EcoSys supports the following SAML profiles:

  1. Web Browser SSO Profile

  2. Single Logout Profile

Both these profiles are supported via HTTP redirect/POST bindings. SOAP bindings are currently not supported. Only authentication is currently supported, not any authorization (security groups) or user data synchronization.


  1. Enable SSL/HTTPS on the application server. Please refer to your application server’s documentation for more information on how to do this.

    If SSL/HTTPS is being enabled through a reverse proxy arrangement, ensure that the application server is aware of the proxy so that URLs can be constructed correctly. Again, please refer to your application server’s documentation for more information on how to do this.

  2. If you are using Oracle Java v8b161 or prior, configure the JDK to use unlimited strength cryptography. For more information, refer to Oracle’s JCE documentation.

  3. The Identity Provider’s (IdP) metadata file (XML file). Please contact your IdP provider for this file. If your IdP both signs and encrypts assertions, please see 6.4 (Known issues/Common pitfalls).

  4. The private key that EcoSys will use to sign SAML requests and responses (PKCS12 file or a Java keystore). Please refer to your certificate authority administrator or server administrator for this key. The certificate for this key must be trusted by the IdP.

  5. The PKCS12 file/Java keystore password

  6. If you have a certificate file (*.cer) that the IdP uses, place it on the app server in C:\EcoSys\ESFM_HOME.

After EcoSys has been configured as a Service Provider (SP), native users will only be able to log in to the application with /login_native appended to the URL. For example: https://host:port/ecosys/login_native

Configure EcoSys as a SAML Service Provider

If EcoSys has been configured to run in clustered mode, all steps (1-9) in this section must be performed on each server in the cluster.

  1. Add the following properties to the ESFM_HOME\ file


  2. Enable SAML logging configuration in the EcoSys log4j2.xml file. The template file has 2 sections for SAML that are commented out. The log file paths might need to be corrected.

  3. Restart the application on the server.

  4. For a single application server go to https://myserver:port/ecosys to the "Configure EcoSys…" screen.

  5. For multiple servers, either use the host address for each direct server or use the Load-Balancer URL but ensure that:

    1. The endpoint address on all servers shows up as http://load-balancer.

    2. Messages are sent back to the unique server that originated the request.

  6. Under the ‘Identity Provider (IdP) metadata’ section, use the ‘Choose File’ button to upload the IdP’s metadata file.

  7. Under the ‘Configuration and metadata for this Service Provider’ section –

    1. Use the ‘Choose File’ button to upload a private key. EcoSys will use this file to sign requests and responses.

    2. Enter the private key’s password.

    3. Enter details for the organization name, URL and the contact address.

  8. Click ‘Configure SAML SP’. You should see the following page if everything was configured without error -

    The configuration is written to ESFM_HOME/SAML on the server.

  9. Restart the application server

    The ESFM_HOME/SAML folder on the server has the following structure –

    The ‘metadata/SP’ sub-folder contains a file called ‘SPMetadata.xml’ - this is the SAML Service Provider’s (EcoSys’) metadata file and should be used to configure the necessary ‘trust relationship’ on the IdP and "claim rules." Please consult your Identity Provider for information on how to do this. Note that the EcoSys SP only supports the SHA-256 signature hash algorithm.

  10. Edit the file ESFM_HOME/SAML/ with a text editor. If you have the IdP certificate from pre-requisite step 6 above then add the following setting to the file on its own line. Change the path as necessary.$ESFM_HOME\<name>.CER

    If you don’t have a certificate from the IdP then uncomment this existing setting –


    After EcoSys has been configured as a SP when someone tries to access EcoSys –

    1. The user will be redirected to the IdP for authentication

    2. If authentication is successful, the IdP will send the user details in the form, outlined by the claim rules of the IdP, back to EcoSys.

After the setup process is completed, the $ESFM_HOME/SAML folder will contain a 'template’ in oiosaml-sp-log4j2.xml file that can also be used to configure EcoSys' log4j2.xml file.

Configure the Identity Provider. Refer to your IdP administrators for this step.

EcoSys can be configured to work with any SAML 2.0 compliant Identify Provider. Refer to your IdP administrator and/or documentation for more information on this process. See Appendix: A for an example of IdP configuration using ADFS.

Note the recommendations when configuring the IdP:

  1. Use the SP metadata provided by EcoSys to import into the relying trust.

  2. Ensure the hash algorithm used for the relying trust is SHA-256.

Configuring Users to Authenticate Via SAML

Users authenticated by the IdP need to be further authorized in EcoSys. This means that in the scenario described above in step 6, where the IdP sends the user details in the form username@domain.suffix

  • A user with the same login ID must exist within EcoSys.

  • The user’s authentication mode must be configured as custom.

Follow these steps to import user details from your IdP to EcoSys–

  1. Create a new spreadsheet by selecting ‘User’ as the subject area.

  2. Add the following columns to it –

    1. Authentication Mode (use default value ‘Custom’)

    2. First Name

    3. Last Name

    4. Login Name

    5. Main Menu (Name) (either use a default value, or specify one)

    6. License (use an appropriate default value)

  3. Export user details from the IdP, preferably in Excel format containing at least the First Name, Last Name and the Login Name ( in this example)

  4. Import the Excel file into the spreadsheet created in step 1.

You might need to configure security groups for these newly imported users.

Troubleshooting SAML

If the SAML exchange between EcoSys and the IdP were to fail for any reason, you will see an error page that looks like the following –

The EcoSys SP produces two log files in the ESFM_HOME/SAML/logs folder on the server –

  • oiosaml-sp.log – this logs requests handled by the SP

  • oiosaml-sp-audit.log – this logs exchanges between the SP and the IdP

To configure the SP’s logging level, edit the file ESFM_HOME/SAML/oiosaml-sp.log4j.xml.

The default log level for both these log files is set to ERROR, which means that only error events are logged to them. To see more detail in these log files, set the log level to DEBUG as suggested in the ‘oiosaml-sp.log4j.xml’ file –

<param name="Threshold" value="ERROR" /> <!-- change this to DEBUG when you want to debug authentication issues -->

The application will need to be restarted for the new logging level to take effect.

If you need to verify how SAML has been configured, use the System Configuration utility and search for the term ‘saml’. You should see the following –

Known issues/Common pitfalls

  1. If SSL/HTTPS is being enabled through a reverse proxy arrangement, ensure that the web server is aware of the proxy so that URLs can be constructed correctly (see step 1).

  2. Ensure that the application server’s Java VM is configured to use unlimited encryption strength algorithms (see step 4).

  3. Ensure that the EcoSys is set up to use SHA-256 hashing on your IdP (see step 6).

  4. If your IdP uses self-signed certificates, enable(uncomment) the following property in the file ESFM_HOME/SAML/ and restart the application -


  5. When you logout of EcoSys (as a SAML user), you are typically taken to the IdP’s authentication page. If you’d like to be redirected to a different site instead, enable(uncomment) the following property in the file ESFM_HOME/SAML/ and restart the application -