# SAMLModule

## Introduction

Responsible for

*  loading, maintaining & generating metadata.
* generating outbound SAML messages (assertions, authentication & logout requests )
* consuming and validating incoming SAML requests.

When deployed the module opens http port 8080 to enable saml meta data generation.

## Configuration

{% hint style="info" %}
**Module name:** `SAML`
{% endhint %}

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th>Name</th><th>Description</th><th>Default value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>metadata_cache</code></td><td>Optional location to where remote metadata loaded, using HTTP, should be cached. The target directory folder must exist.</td><td>&#x3C;server_root></td><td>false</td></tr><tr><td><code>enable_http</code></td><td> Should metadata be available using HTTP. </td><td><code>true</code></td><td>false</td></tr><tr><td><code>internal_http_destination</code></td><td>Id of the internal HTTP module to handle HTTP-based metadata loading. </td><td><code>default</code></td><td>false</td></tr><tr><td><code>ignore_signature_validation</code></td><td>Disabled signature validation on incoming AuthnRequest &#x26; LogoutOutRequest.</td><td><code>false</code></td><td>false</td></tr><tr><td><code>reload_meta_intervall_millis</code></td><td>How often in milliseconds a reload should occur.</td><td><code>300000</code></td><td>false</td></tr><tr><td><code>reload_meta_start_delay_millis</code></td><td>How long after startup reloading of metadata should start reloading.</td><td><code>20000</code></td><td>false</td></tr></tbody></table>

{% endtab %}

{% tab title="Full example " %}

```json
{
    "name": "SAML",
    "config": {
        "metadata_cache": "/opt/fortifiedid/integrity/cache",
        "http_port": 8081,
        "metadata_template": [
            {
                "id": "myidp",
                "metadata_file_path": "/opt/fortifiedid/integrity/custom/idptemplate.xml",
                "sign_metadata_keystore": {
                    "path": "/opt/fortifiedid/integrity/custom/fortifiedid.p12",
                    "password": "secretpassword",
                    "alias": "fortifiedid",
                    "key_password": "keypassword"
                }
            }
        ],
        "metadata": [
            {
                "url": "https://samltest.id/saml/providers"
            },
            {
                "path": "/opt/fortifiedid/integrity/custom/idpdata.xml"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}

## Metadata template

Metadata to be consumed by remote party is generated based of a template file. It is referenced using the parameter *"config.metadata\_template.metadata\_file\_path*". Administration of this file is handled outside the system and must include the necessary information such as entity id, binding location etc.&#x20;

Signing of meta data, injecting certificates used and adding of SLO url is handled by the module.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="282">Name</th><th>Description</th><th>Default value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>id</code></td><td>Id to be used in URL when getting meta data. Id is used to reference the meta data.</td><td>N/A</td><td>false</td></tr><tr><td><pre class="language-json"><code class="lang-json">metadata_file_path
</code></pre></td><td>Location of the template used.</td><td>N/A</td><td>false</td></tr><tr><td><pre><code>sign_metadata_keystore
</code></pre></td><td>Object for signing the meta data when exposed to clients.</td><td></td><td>true</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"metadata_template": [{
	"id": "painkiller",
	"metadata_file_path": "idptemplate.xml",
	"sign_ref": [{
		"keystore": {
			"path": "fortifiedid.p12",
			"password": "fortifiedid",
			"alias": "fortifiedid",
			"key_password": "fortifiedid"
		}
	}],
	"encryption_ref": [{
		"keystore": {
			"path": "fortifiedid.p12",
			"password": "fortifiedid",
			"alias": "fortifiedid",
			"key_password": "fortifiedid"
		}
	}]
}]
```

{% endtab %}
{% endtabs %}

## Sign meta data key store

A single object used for signing the meta data

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="271">Name</th><th>Description</th><th>Default value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><pre><code>path
</code></pre></td><td>Location of the p12 key store</td><td>N/A</td><td>true</td></tr><tr><td><pre><code>password
</code></pre></td><td>password of the key store</td><td>N/A</td><td>true</td></tr><tr><td><pre><code>alias
</code></pre></td><td>alias used to reference in the store. </td><td>N/A -  Mandatory if multiple entries are located in the store.</td><td>true</td></tr><tr><td><pre><code>key_password
</code></pre></td><td>Password to the private key.</td><td>N/A</td><td>true</td></tr></tbody></table>
{% endtab %}

{% tab title="Second Tab" %}

```json
  "sign_metadata_keystore": {
        "path": "fortifiedid.p12",
        "password": "fortifiedid",
        "alias": "fortifiedid",
        "key_password": "fortifiedid"
    }


```

{% endtab %}
{% endtabs %}

## Sign ref - key store

Configuration, array, for key pairs used to sign SAML messages. Multiple key stores is supported. Each entity is placed in the `sign_ref` array. Key store must be in PKCS#12 format.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th width="271">Name</th><th>Description</th><th>Default value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><pre><code>path
</code></pre></td><td>Location of the p12 key store</td><td>N/A</td><td>true</td></tr><tr><td><pre><code>password
</code></pre></td><td>password of the key store</td><td>N/A</td><td>true</td></tr><tr><td><pre><code>alias
</code></pre></td><td>alias used to reference in the store. </td><td>N/A -  Mandatory if multiple entries are located in the store.</td><td>true</td></tr><tr><td><pre><code>key_password
</code></pre></td><td>Password to the private key.</td><td>N/A</td><td>true</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"sign_ref": [
              {
                "keystore": {
                  "path": "fortifiedid.p12",
                  "password": "fortifiedid",
                  "alias": "fortifiedid",
                  "key_password": "fortifiedid"
                }
              }
            ]
```

{% endtab %}
{% endtabs %}

## Encryption ref - key store

Same as sign ref, `sign_ref`, but for encryption.

{% tabs %}
{% tab title="Properties" %}
See sign ref properties.
{% endtab %}

{% tab title="Second Tab" %}

```json
"encryption_ref": [
              {
                "keystore": {
                  "path": "file.p12",
                  "password": "fortifiedid",
                  "alias": "fortifiedid",
                  "key_password": "fortifiedid"
                }
              }
            ]
```

{% endtab %}
{% endtabs %}

## Meta data consumption

Setting up trust with an external party is done by consuming it's meta data. This can be done by either a file or using an url.

{% tabs %}
{% tab title="Properties" %}

| Name         | Description                | Default value | Mandatory           |
| ------------ | -------------------------- | ------------- | ------------------- |
| `path`       | File path to the meta data | N/A           | Either path or url. |
| `url`        | HTTP url to the metadata.  | N/A           | Either path or url. |
| {% endtab %} |                            |               |                     |

{% tab title="Example" %}

```json
"metadata": [  
          {
            "url": "https://samltest.id/saml/providers"
          },
          {
            "url":"https://remotelocation/metadata/mdx/role/sp.xml"
          },
          {
            "path": "sp_meta.xml"
          },
          {
            "path": "localsp_meta.xml"
          }
        ]
```

{% endtab %}
{% endtabs %}

## Generating metadata

In order to get metadata generated by the system point your browser to:

http\://\<host>:\<port\_if\_any>/saml/metadata/\<config.metaDataTemplate.id>

## Integrating with a HSM

Integrity can use a HSM to sign messages. It is done through JAVA PKCS#11 standard interface.

Configuration elements are to be located at same level as "*keystore*" property.

{% tabs %}
{% tab title="Properties" %}

<table><thead><tr><th>Name</th><th>Description</th><th>Defalut value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>provider_path</code></td><td>File path to the HSM provider implementation file. </td><td>N/A</td><td>true</td></tr><tr><td><code>pin</code></td><td>HSM pin. </td><td>N/A</td><td>true</td></tr><tr><td><code>alias</code></td><td>Alias handle. </td><td>N/A</td><td>true</td></tr><tr><td><code>key_password</code></td><td>Private key password. Use same value as pin if missing. </td><td>N/A</td><td>true</td></tr><tr><td><code>certificate_pem_path</code></td><td>If present Integrity will read the certificate from file. Must be in PEM format. If missing, certificate is read from HSM. </td><td>N/A</td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"keystore_hsm": {
                  "provider_path": "<path_to_providerfile>",
                  "pin": "the_pin",
                  "alias": "my_key_alias",
                  "key_password": "tha_password"
                }
```

{% endtab %}
{% endtabs %}

File for SAML IDP metadata template can be downloaded here:

{% file src="<https://content.gitbook.com/content/fpgCFwnJkjDvao7QGYEX/blobs/lRJfDTYGQrg1M0MjRGyH/meta_template.xml>" %}

### Loading of remote meta data

Failing to get meta data for the first time will result in retries every 20 seconds until meta data is loaded.&#x20;

Meta data target is checked  on set intervall (every 20 minutes by default) for information update.  Meta data is reloaded based on *valid until*, if present. Otherwise every four hours.

### Using expansion in meta data template

XML meta data template has some understanding of "expansion". It knows the concept of *globals.* By using *globals* it will allow for conffiguration like "\<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="**${globals.idp1.idp\_entityid}**"".&#x20;

Note that only globals is supported.