# Set up SAML
Page contents
# Overview
When setting up the integration, the service provider and Signicat exchange SAML 2.0 metadata (trust establishment). In the metadata both sides express trust for each other. The metadata also describes the type and format of the SAML 2.0 request and SAML 2.0 response.
You can choose your preferred method to establish trust in the SAML 2.0 configuration in the Signicat Dashboard. You have the option to either host or upload the metadata. Learn more about this in the Set up a SAML connection section.
# Set up a SAML connection
This section outlines the steps necessary to establish a SAML 2.0 connection with Signicat.
If you are new to Signicat, you can learn more about how to get started in the initial setup instructions.
# Exchange the metadata
In SAML2.0, you establish connections by exchanging metadata between the service provider (SP) and the identity provider (IdP). Metadata should be formatted as described in the SAML 2.0 OASIS specification (opens new window).
To set up a secure connection over SAML 2.0, you have to provide Signicat with a metadata file. Signicat offers two ways of exchanging metadata:
- URL (dynamic): this means that the metadata file is hosted by you. With this option, you generate the metadata file on your own, make it available somewhere, and provide Signicat with the URL to access the file. With this option, the metadata file will be read dynamically, and if you update it with new certificates the only thing you will have to do is update the hosted file on the URL you provided.
- Form (static): this option can be used if you don't plan on hosting your metadata file yourself. You can generate the file and upload it to the Dashboard or fill in the form in the Dashboard to have Signicat generate the metadata file for you. If you choose this option and need to update your metadata file with new certificates, you will have to re-upload the file manually on the Dashboard.
If you don't have a SAML 2.0 metadata file
If you are not able to create a metadata file, fill in the form in the Dashboard to provide Signicat with information about the SAML 2.0 connection you want to establish. We use this information to build a metadata file for you.
# Add the metadata
To add your metadata configuration:
- In the Dashboard, go to eID Hub > SAML 2.0 (opens new window) and select Add new.
- Select the method to configure the metadata. You can choose between:
- Fill in the configuration. You can find information about each field in the next section.
- Select Add to save the configuration.
Get Signicat's metadata
Select the Get Signicat's metadata button to get the Signicat's metadata XML file. Load this metadata in your application.
# Example of metadata file
# URL configuration
The advantage of opting for a dynamic exchange of metadata is that whenever your certificates change, they are updated automatically, as Signicat will periodically fetch the metadata from the URL configured.
# Standard URL configuration fields
When configuring the URL metadata, fill in the following fields:
| Field name | Description |
|---|---|
| Name* | Name of the connection. |
| Application URL | URL of the service provider application. |
| Metadata URL* | A valid URL link to the service provider metadata. |
| Select a LoA contract* | Select the mapping between levels of assurance that must apply to this configuration. See Level of Assurance contracts for more information. |
* Required fields are marked with an asterisk (*).
# Advanced URL configuration fields
| Advanced field name | Description |
|---|---|
| Want root signed even if the assertions are also signed | We recommend to always sign the root. If your application cannot handle multiple signatures, you may opt to disable signing of the root when signing the assertions. |
| Use a transient format for the NameID | If you only want a transient "NameID", tick this box. |
| Include the SAML Assertion of the IdentityProvider if available | If you use a SAML 2.0-based ID method, you may opt to receive the original SAML 2.0 assertion from the ID method. |
| Encrypt assertion | If you want to receive an EncryptedAssertion instead of an Assertion for added security, select this option. Note that some ID methods require you to receive an EncryptedAssertion. You can select which algorithm to use for key and data encryption:
|
| Select attribute filter | Select an attribute filter, to filter out attributes from the response. They must be configured in Attribute filters. |
| Response attribute mappings | You can choose to customise the name of the attributes received in the response body. You can provide none or many name-to-name mappings. |
# Cache duration
You can control the maximum length of time Signicat caches the metadata retrieved from the URL configuration by setting the cacheDuration in the metadata file, as specified in the OASIS SAML 2.0 documentation (opens new window).
The default cacheDuration of the metadata is set to 4 hours. This means that, if you update the metadata, it could take up to 4 hours before Signicat uses the new metadata.
The highest value supported is 4 hours and the lowest value supported is 5 minutes. That means that, in case a cacheDuration larger than 4 hours is specified, it will refresh every 4 hours. Likewise, if a duration smaller than 5 minutes is specified, it will refresh every 5 minutes.
On the EntityDescriptor you can add an (optional) attribute cacheDuration:
<attribute name="cacheDuration" type="duration" use="optional"/>
The duration should be formatted as described here (opens new window).
For example, to set the metadata cacheDuration to 30 minutes, add the cacheDuration="PT30M" attribute to your metadata, as shown:
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
cacheDuration="PT30M"
entityID="someEntityId">
...
</md:EntityDescriptor>
# Form configuration
To share a metadata file with Signicat, you need to upload a valid metadata XML file for the service provider in the Upload service provider metadata section. You can then include any additional configuration by filling in the Standard and Advanced configuration fields.
If you are not able to provide a metadata file, you can use the Standard and Advanced configuration fields to fill in information about the SAML 2.0 connection.
# Standard Form configuration fields
When configuring the Form metadata, fill in the following fields:
| Field name | Description |
|---|---|
| Name* | Name of the connection. |
| Application URL | URL of the service provider application. |
| Entity ID* | Unique identifier for the service provider (required). |
| Select a LoA contract* | Select the mapping between levels of assurance that must apply to this configuration. See Level of Assurance contracts for more information. |
* Required fields are marked with an asterisk (*).
# Advanced Form configuration fields
| Field name | Description |
|---|---|
| Want assertions signed | If ticked, assertions will be signed. |
| Want root signed even if the assertions are also signed | We recommend to always sign the root. If your application cannot handle multiple signatures, you may opt to disable signing of the root when signing the assertions. |
| Use a transient format for the NameID | Tick this box if you only want a transient NameID. |
| Include the SAML Assertion of the IdentityProvider if available | If the ID methods that you use are SAML 2.0-based, you may opt to receive the original SAML 2.0 assertion of the ID method. |
| Encrypt assertion | If you want to receive an EncryptedAssertion instead of an Assertion for added security, select this option. Note that some ID methods require you to receive an EncryptedAssertion. You can select which algorithm to use for key and data encryption:
|
| Assertion consuming services* | At least one assertion consuming service must be configured. Provide a location URL and a binding type (REDIRECT / POST / ARTIFACT). |
| Single logout services | Enter the location URL and binding type (REDIRECT / POST / ARTIFACT) of any applicable single logout services. |
| Artifact resolution services | Enter the location URL, binding type and index of any applicable artifact resolution services. |
| Attribute consuming services | Enter name, index, description (optional) and at least one attribute |
| Certificate* | Upload all relevant certificates for the connection (at least one). Information about the certificates, such as issuer and expiration date, is displayed when they are uploaded. |
| Client organisation | Enter organisation name, display name, and URL. |
| Hosting party organisation | Provide organisation name, display name, and URL. |
| Contact people | Provide details about the contact people in your organisation. In Type of contact person, specify whether they are part of support, a technical department, name, phone number, and more. |
| Response attribute mappings | You can customise the name of the attributes received in the response body. You can provide none or many name-to-name mappings. |
| Select attribute filter | Select which attributes you want to filter out, if any. They must be configured in Attribute filters. |
| Select default broker service | Select which default broker service to use. This can be configured in the Dashboard in Advanced > Broker services (opens new window). |
* Required fields are marked with an asterisk (*).
# Learn more
Explore the SAML 2.0 documentation to discover request examples and learn about advanced topics.