Exact Financials

SAML: configuration

This document describes how to configure Exact Financials to use SAML authentication. When using SAML there are two important roles:

1. The identity provider (IdP), this role is fulfilled by SURFconext.
2. The service provider (SP), this role is fulfilled by Exact Financials.

Requirements:

1. Exact Financials 7.29.03
2. Progress OpenEdge 12.2
3. Apache Web Server 2.4x
4. Node.js 14.x

General flow:

1. browser request
2. Apache Web Server
3. Node.js
4. if user not yet authenticated
1. browser is redirected to IdP login page 
2. user logs in
3. IdP sends SAML assertion to Apache which redirects to Node.js
4. Node.js stores assertion in local session
5. Node.js adds SAML assertion header to request and passes it to PASOE
6. PASOE transforms SAML assertion to client principal
7. Exact Financials uses client principal to determine user and user groups
8. if user does not yet exist, user is created and added to user groups

1. Exact Financials

First ensure that Exact Financials is working normally on http. You can then map SAML attributes to Exact Financials user properties start [ System: Security / Settings ]. The SAML tab contains:

• Enabled: indicates if SAML should be used by Exact Financials

• User ID (default: urn:mace:dir:attribute-def:uid)
• Name (default: urn:mace:dir:attribute-def:displayName)
• Groups (default: urn:mace:dir:attribute-def:eduPersonAffiliation)
• E-mail (default: urn:mace:dir:attribute-def:mail)

When registering Exact Financials as service provider at SURFconext you will need to indicate that the attributes you provide here need to be included in the SAML assertion.

Note that the 'User ID' in Exact Financials can at most be 20 characters long.

2. Progress Application Server for OpenEdge (PASOE)

To enable SAML, several configuration files need to be updated:

<pas>/conf/server.xml

Since the SAML assertions are passed in the headers of a request, the default maximum header size of 8192 is too small and needs to be increased:

maxHttpHeaderSize="65536"

<pas>/webapps/ROOT/WEB-INF/oeablSecurity.properties (handled by installer)

Change the client.login.model from anonymous to saml.

Any request directed at PASOE will now need to provide a valid SAML assertion, beware that as soon as you do this you will no longer be able to access Exact Financials until you have completed everything. If you need to use Exact Financials in the mean time, you can revert the client.login.model to anonymous.

<pas>/webapps/ROOT/WEB-INF/metadata

Put the SAML metadata for your IdP and your SP here. The default names (from oeablSecurity.properties) are idp.xml and sp.xml.

For more information on metadata, see the SURFconext wiki. The SP metadata can be generated using for example samltool.com.

<pas>/webapps/ROOT/WEB-INF/oeablSecurity.csv (handled by installer)

To allow serving of all Exact Financials static content without requiring a SAML assertion, add line:

"/static/efonline/**","GET","permitAll()"

Above the line that grants rights for "/static/**"

To allow REST calls, that do not use SAML since they are protected by Authorization headers, add line:

"/web/rest/**","*","permitAll()"

Above the line that grants rights for "/web/**", also for swagger-ui, add line:

"/static/swagger-ui/**","*","permitAll()"

Below the line that permits all to /static/efonline/**.

<pas>/webapps/ROOT/WEB-INF/spring/enableSamlSecurity.xml (handled by installer)

To enable Exact Financials workspace functionality, find the section for http pattern="/web/**" and within that section find:

<headers defaults-disabled="false" disabled="false" />

Change this to:

<headers defaults-disabled="false" disabled="false">
   <frame-options policy="SAMEORIGIN" />
</headers>

To enable anonymous static content (the change to oeablSecurity.csv is insufficient), find the section for http pattern="/**" and add to that section (below headers):

<anonymous enabled="true" />

To enable anonymous REST calls (the change to oeablSecurity.csv is insufficient), find the section for http pattern="/web/**", copy it, and in the first occurrence change the pattern to "/web/rest/**" and enable anonymous access:

<anonymous enabled="true" />

<pas>/webapps/ROOT/WEB-INF/spring/samlAuthManager.xml

If the error 'PKIX failed, no trust anchors found' occurs when starting PASOE you can add the following property to the ExtendedMetadataDelegate bean

<b:property name="metadataTrustCheck" value="false"/>

After the IdP and SP constructors - see Spring documentation.

3. Apache Web Server

Since PASOE and Node.js will both be listening to http only, the outward facing web server needs to be listening to https. See the Apache documentation for enabling SSL, with a certificate file and a key file the conf file can be adjusted so that:

SSLCertificateFile server.cer
SSLCertificateKeyFile server.key

The ProxyPass module is used for this.

#
# pass all REST, SOAP and static requests directly to PASOE
#
ProxyPass /web/rest/ http://localhost:8810/web/rest/
ProxyPass /soap/ http://localhost:8810/soap/
ProxyPass /static/ http://localhost:8810/static/
#
# pass all non-REST requests for web transport to Node.js
#
Proxypass /web http://localhost:8080/web
#
# pass the assertion from IdP to Node.js
#
ProxyPass /saml/post http://localhost:8080/saml

4. Node.js

To provide PASOE with the required SAML assertion in the header, Node.js is used using the express web application framework.

Install a current LTS release from nodejs.org.

In the <pas>/openedge/saml folder, install the Node.js packages that are required for sp.js being:

• saml2-js
• express
• express-session
• memorystore
• then-request
• winston

npm install saml2-js express express-session memorystore then-request winston

Adjust the options in sp.js (in <pas>/openedge/saml) for your environment, the important options are:

• express_port - (default: 8080) this is the port that Node.js listens on, this port should only be accessible to Apache
• pasoe_port - (default: 29180) this is the port that PASOE listens on, this port should only be accessible to Node.js
• request_limit - (default: 10mb) this is the maximum size for a request, if you need to import larger files you can increase this limit
• sp_options.entity_id - this is the https url as registered with Surfconext.
• idp_options.sso_login_url - this is the https url as prescribed by Surfconext.

Start the service provider sp.js:

node sp

For normal use you will probably want to schedule this or wrap it in a service.

SOAP Web Services

The SOAP transport does not use SAML. This is configured in <pas>/conf/oeablSecurity.properties - see line soap.security.enable=none.