Howto: Configure MS365 SSO via SAML

Configuring Azure Active Directory

The first step to switch to SSO login with SAML in iAGENT is to setup an enterprise application in the azure active directory. The main steps are described in following document:

https://learning.postman.com/docs/administration/sso/saml-in-azure-ad/

The users that should be able to login in iAGENT have to be added as users to the newly created Enterprise Application.

As default reply URL the index page of the agent should be used. This URL will only be used if the authentication request does not deliver a AssertionConsumerServiceURL. The authentication request from an iAGENT-System will always deliver an AssertionConsumerServiceURL.
Following URL’s should be set as Reply URL’s:

• Default: https://<hostname>/agent/client/index.imail (Use index.jsp on developer systems. The default reply url can not contain a wildcard character)
• https://<hostname>/agent/*
• https://<hostname>/iMail/*

The wildcard URL’s are necessary to support the iAGENT deeplink mechanism. The reply URL supplied by the authentication request can be any valid URL inside an iAGENT system (to open directly a specifiy view).

If you use the test button in the Single sign-on menu you should be redirected to the login page of the iAGENT-System. No login to the iAGENT-System will be done with this test. But seeing the login page indicates that the request has been successful.

Configuring the iAGENT System

First of all the browser has to have internet access. The microsoft login server (login.microsoftonline.com) has to be reachable. Additionally the SAML-Authentication has to available (project “ecom-saml-client”). Therefore the necessary libraries have to be deployed.

Adding dependencies in Eclipse

To add the required libraries in an eclipse development environment the “build.custom.gradle” of the projects “ecom-iagent-eclipse-imail-agent” and “ecom-iagent-eclipse-routing” have to be extended by following dependency:

• runtime ‘com.novomind.ecom:ecom-saml-client:11.15.1’

Afterwards the routing server and Agent server have to be stopped and redeployed.

Adding libraries to an installed iAGENT-System

The libraries necessary for a SSO-Authentication can be found in the iAGENT-Updater in following path:

• common\standard\other\saml-client\lib\

These libraries have to be copied in following locations of the installed iAGENT-System:

• <iAGENT-Installation>/tomcat/webappsiMail/iMail/WEB-INF/lib/ (Routing-Process)
• <iAGENT-Installation>/tomcat/webappsiMailAgent/agent/WEB-INF/lib (SV-Process)

Afterwards the processes/services for the routing/agent have to be restarted.

Configuring users in iAGENT

You have to create users that are in the azure active directory in the iAGENT-System. The user name has to be the same that is used to login within office365 (username@domain, for example mmustermann@example.com). Also don’t forget to create an admin user that can login with SSO.

For accesses with system users (such as from apps or REST API), one of the following keys must be set to the value DB on the corresponding user (Individual Settings tab in User Settings):

• auth.type (for login on Supervisor and Desk)
• auth.type.agent (for login on Desk)
• auth.type.user (for login on Supervisor)

Configuring SSO Authentication

First of all download the Federation Metadata XML from your configured Enterprise Application. Almost all required informations can be found in the description.
The configuration has to be added to the Routing.conf file of the iAGENT System. The configuration concerning the SSO-Login can be changed in a running iAGENT-System.

An example configuration to be added to the Routing.conf would look like following:

Following configuration properties have to be adapted:

• external.auth.saml.sp.identifier
• external.auth.saml.ip.identifier
• external.auth.saml.ip.endpoint
• external.auth.saml.certificate.base64
• external.auth.show.login.mask

The external.auth.saml.sp.identifier can be found in the Single sign-on configuration of the Enterprise Application (“Identifier (Entity ID)”).

The external.auth.saml.ip.identifier can be found in the Single sign-on configuration of the Enterprise Application (“Azure AD Identifier”). It can also be found in the federation metadata xml file (Element “EntityDescriptor” → Attribute “entityID”).

The external.auth.saml.ip.endpoint can be found in the Single sign-on configuration of the Enterprise Application (“Login URL”). Folloing element has to be located in the xml file. Normally it is placed somewhere at the end of the file:

<SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://login.microsoftonline.com/bb3b64e1-cd0c-4d0c-a85b-fabcabfef245/saml2"/>

The value of the attribute “Location” has to be used as value.

The value for the property external.auth.saml.certificate.base64 can also be found in the federation metadata xml. Following example content contains the necessary public key in base64 format. Just copy the text content of the element “X509Certificate”.

By setting external.auth.show.login.mask to false, the login mask for iAGENT is disabled.