# Installation

### **Certificate** <a href="#stop_server" id="stop_server"></a>

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** <a href="#stop_server" id="stop_server"></a>

First open the IIS-Manager on Microsoft Server. &#x20;

<figure><img src="http://aquawiki.andagon.com/pictures/drex_installation_2_custom.png" alt=""><figcaption></figcaption></figure>

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.&#x20;

### **2. Configuration** <a href="#id-2__configuration" id="id-2__configuration"></a>

**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.&#x20;

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

&#x20;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](http://aquawiki.andagon.com/sample.html).&#x20;

**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: &#x20;

{% code overflow="wrap" %}

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

{% endcode %}

Save and close **Web.config**&#x20;

**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:&#x20;

<pre class="language-xml" data-overflow="wrap"><code class="lang-xml"><strong>...  &#x3C;aquaWebNGConfig>    ...    &#x3C;add key="SAML.FederationMetadataPath" value="C:\Path\to\saml-idp-metadata.xml" />    &#x3C;add key="SAML.AquaSPEntityId" value="aqua-saml-sp" />    ...  &#x3C;/aquaWebNGConfig>  ...  
</strong></code></pre>

### **3. Start aqua Server** <a href="#id-3_start_aqua_server" id="id-3_start_aqua_server"></a>

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

'aquaAPIPool',&#x20;

'aquaFileServerPool',&#x20;

'aquaWebservicePool'&#x20;

and 'aquaWebNGAppPool'.&#x20;

### **4. Debugging SAML Response**  <a href="#stop_server" id="stop_server"></a>

In order to properly debug the SAML response, you can use [saml decode tool](https://www.samltool.com/decode.php) and go through AttributeStatement list to find the desired attribute field.

{% hint style="info" %}
Please note that the Desktop client does not support SAML.&#x20;
{% endhint %}

{% hint style="info" %}
Please note that the Sync Configuration Client do not support usernames containing special characters, particularly the "@" symbol.
{% endhint %}