> For the complete documentation index, see [llms.txt](https://docs.fortifiedid.se/access/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fortifiedid.se/access/key-components/modules/saml/saml-module.md).

# SAML module

Core module when Fortified ID Access should act as a SAML Identity Provider (IdP) or SAML Broker for SAML Service Providers (SPs).

## Overview

The SAML module is responsible for:

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

## Configuration

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

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

<table data-full-width="true"><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/consumption.</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><tr><td><code>metadata</code></td><td>Configuration for consuming <a href="/access/key-components/modules/saml/saml-application.md">metadata and SP settings</a></td><td>N/A</td><td>false</td></tr><tr><td><code>app_profile</code></td><td>Configuration of SAML <a href="/access/key-components/modules/saml/saml-profile.md">application profiles</a></td><td>N/A</td><td>false</td></tr><tr><td></td><td></td><td></td><td>false</td></tr></tbody></table>
{% endtab %}

{% tab title="Example 1" %}

```json
{
    "name": "SAML",
    "display_name": "SAML module",
    "description": "SAML module",
    "config": {
        "metadata_cache": "${system.customer_home}/cache",
        "http_listener": "default",
        "metadata_template": [
            {
                "id": "myidp",
                "metadata_file_path": "${system.customer_home}/resources/idptemplate.xml",
                "sign_metadata_keystore": {
                    "path": "${system.customer_home}/resources/fortifiedid.p12",
                    "password": "secretpassword",
                    "alias": "fortifiedid",
                    "key_password": "keypassword"
                }
            }
        ],
        "metadata": [
            {
                "url": "https://samltest.id/saml/providers"
            },
            {
                "path": "${system.customer_home}/resources/myidp_data.xml"
            }
        ]
    }
}
```

{% endtab %}

{% tab title="Example 2" %}
In this example we have two SAML IdPs and we also use inclusion expression/include. With include, all SAML applications and SAML profiles will be in the respective locations. For more how inclusion expression/include works, click following [LINK](/access/configuration-reference/file-inclusion.md).

```json
{
  "name": "SAML",
  "display_name": "SAML module",
  "description": "SAML module",
  "config": {
    "metadata_cache": "${system.customer_home}/cache",
    "http_listener": "default",
    "enable_http": true,
    "metadata_template": [
      {
        "id": "default",
        "metadata_file_path": "${globals.default_saml_template}",
        "sign_ref": [
          {
            "keystore": {
              "key_password": "${globals.default_keystore_password}",
              "password": "${globals.default_keystore_password}",
              "path": "${globals.default_saml_keystore}"
            }
          }
        ]
      },
      {
        "id": "samlidp_1",
        "metadata_file_path": "${system.customer_home}/resources/samlidp_1_template_1.xml",
        "sign_ref": [
          {
            "keystore": {
              "path": "${system.customer_home}/resources/samlidp_1_keystore_1.p12",
              "password": "ha2nrgJ7qjkPbz3n",
              "key_password": "ha2nrgJ7qjkPbz3n"
            }
          }
        ]
      }
    ],
    "metadata": "@include:samltrust/",
    "app_profile": "@include:samlprofile/"
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Entries in `metadata` and `app_profile` can also include app-specific authorization. See [SAML application](/access/key-components/modules/saml/saml-application.md) and [SAML profile](/access/key-components/modules/saml/saml-profile.md).
{% endhint %}

## 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.

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

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

<table data-full-width="true"><thead><tr><th>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 metadata key store

A single object used for signing the meta data

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

<table data-full-width="true"><thead><tr><th>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_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 data-full-width="true"><thead><tr><th>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="Example" %}

```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 metadata. 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. |
| `validation_pem_path` | Path certificate used for metadata validation | N/A           | No                  |
| {% 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 %}

## Validating metadata

Meta data validation can be done setting *validation\_pem\_path.* This will only work for data loaded over HTTP.

Setting *validation\_pem\_path* enforces mandatory validation. If the metadata lacks a signature, it will be omitted.

## 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 and encrypt 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 data-full-width="true"><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 %}

## Thales Luna HSM

It’s possible to integrate with Thales Luna HSM using the Thales JSP provider. This can be a fallback option if the generic PKCS#11 integration fails.

Access authenticates to the selected Thales Luna slot as Crypto User for routine signing and encryption operations. Configure `pin` with the Crypto User PIN; Crypto Officer credentials are not required. If Crypto User authentication fails, Access stops keystore initialization instead of attempting to load the keystore with another role.

For more info see Thales doc:

<https://thalesdocs.com/gphsm/luna/7/docs/network/Content/sdk/java/jsp_overview_install.htm>

Ensure adding ***LunaProvider.jar*** to java class path. Add knowledge to libLunaAPI.so/LunaAPI.dll "java.library.path". Typically setting ***-Djava.library.path*** pointing to directory where the file is located.

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

<table data-full-width="true"><thead><tr><th>Name</th><th>Description</th><th>Defalut value</th><th data-type="checkbox">Mandatory</th></tr></thead><tbody><tr><td><code>slot</code></td><td>HSM slot</td><td>N/A</td><td>true</td></tr><tr><td><code>pin</code></td><td>Crypto User PIN for the selected HSM slot.</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></tbody></table>
{% endtab %}

{% tab title="Example" %}

```json
"keystore_thales_hsm": {
        "pin": "fluffy",
        "slot": "0",
        "alias": "<alias_of_key>"
    }
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Tested and verified with Thales Luna A7x series
{% endhint %}

### Loading of remote metadata

Failing to get metadata for the first time will result in retries every 20 seconds until metadata is loaded.

The metadata target is checked at a set interval (every 20 minutes by default) for information updates. Metadata is reloaded based on *valid until*, if present. Otherwise, it is reloaded every four hours.

### Using expansion in metadata template

The XML metadata template has some understanding of "expansion". It knows the concept of *globals.* By using *globals*, it will allow configuration like "\<md:EntityDescriptor xmlns:md="urn:oasis:names:flag\_tc:SAML:2.0:metadata" entityID="**${globals.idp1.idp\_entityid}**"".

Note that only the globals namespace is supported.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fortifiedid.se/access/key-components/modules/saml/saml-module.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.