Installation

Certificate

The SAML certificate must be a "globally trusted certificate" that can be accessed and verified online, or it should be installed on the machine in the "trusted person" space.

1. Stop Server

First open the IIS-Manager on Microsoft Server.

Click on 'aquaAPIPool' and stop it with the button on the right side first.After that please stop 'aquaFileServerPool', 'aquaWebservicePool' and 'aquaWebNGAppPool'.Your Server is stopped now.

2. Configuration

2.1 Add Service Provider to your SAML instance

In order to be able to redirect to aqua after successful SAML-Login, it is required to add aqua as a Service Provider to your SAML-instance. Please ask your SAML-Administrator or check the User Manual of your SAML server if you do not know how to do it for your SAML server. Please find below the proper URLs of aqua for configuring your SAML instance. AssertionConsumerService is an obligatory parameter for SAML so that SAML knows the location for redirect after successful login. SingleLogoutService is optional and only needed if you want SAML to be able to log out a given user from aqua.

AssertionConsumerService	http(s)://<aquawebServerUrl>/aquawebng/Account/saml2-acs
SingleLogoutService	http(s)://<aquawebServerUrl>/aquawebng/Account/saml2-logout

Furthermore, please download and save the IdP metadata file of your SAML instance to a local folder on aqua Backend server and aqua Web server. It will be required for configuring aqua Backend and aqua Web. A sample of an IdP-metadata file can be found here.

2.2 Configure Backend

Open Web.config file of aqua Backend. It is usually located here:C:\Program Files\andagon GmbH\aqua For IIS\Web\WebservicePlease add the following settings to <appSettings> section:

SAML.FederationMetadataPath	Path to IdP-metadata file that must be retrieved from your SAML instance (the metadata-file specifies important properties of your SAML-IdP, e.g. the SingleSignOnService or Certificates)
SAML.UsernameAttribute	Defines the attribute of the SAML response that provides the aqua username (see Section 2.2 for an example where to find this attribute, “uid” is just an example)

Example:

...  <appSettings>    ...    <add key="SAML.FederationMetadataPath" value="C:\Path\to\saml-idp-metadata.xml" />    <add key="SAML.UsernameAttribute" value="uid" />    ...  </appSettings>  ... 

Save and close Web.config

2.3 Configure aqua Web

Open aquaWebNG.config file of aqua Web. It is usually located here:

C:\Program Files\andagon GmbH\aquaWebNG\aquaWebNG

Please add the following settings to <aquaWebNGConfig> section:

SAML.FederationMetadataPath	Path to IdP-metadata file that must be retrieved from your SAML instance (the metadata-file specifies important properties of your SAML-IdP, e.g. the SingleSignOnService or Certificates)
SAML.AquaSPEntityId	Defines the service provider’s entity ID on your SAML instance

Example:

...  <aquaWebNGConfig>    ...    <add key="SAML.FederationMetadataPath" value="C:\Path\to\saml-idp-metadata.xml" />    <add key="SAML.AquaSPEntityId" value="aqua-saml-sp" />    ...  </aquaWebNGConfig>  ...  

3. Start aqua Server

After configuration, you can start your aqua server. Go back to IIS-Manager and start

'aquaAPIPool',

'aquaFileServerPool',

'aquaWebservicePool'

and 'aquaWebNGAppPool'.

4. Debugging SAML Response

In order to properly debug the SAML response, you can use saml decode tool and go through AttributeStatement list to find the desired attribute field.

Please note that the Desktop client does not support SAML.

Please note that the Sync Configuration Client do not support usernames containing special characters, particularly the "@" symbol.