saml2

SAML 2.0

This guide explains how you can exchange XML metadata files with Signicat to set up a SAML 2.0 connection. To learn more about integrating using SAML 2.0, see Set up SAML.

How to exchange SAML metadata

To set up a secure connection over SAML, you must provide Signicat with a metadata file.

What is in the SAML metadata file?

A metadata file contains information about the service provider (SP) and the identity provider (IdP) involved in an authentication process. For example, the metadata stores the URL of the server where to send the response after the authentication session.

To integrate your application with Signicat using SAML 2.0, you configure the metadata in the Signicat Dashboard. You can choose between these configuration options:

Dynamic with URL: You host the metadata in your server and share the metadata URL with Signicat.
Static with Form: You upload the metadata file in the Signicat Dashboard. If you don't have a metadata, you can fill in a form in the Dashboard and have Signicat generate (and store) the metadata file.

Dynamic with URL
Static with Form

To configure a dynamic metadata URL in your account, do the following:

In the Signicat Dashboard, navigate to Products > eID and Wallet Hub > SAML 2.0 and select Add new.
Select the URL configuration method.
Fill in the configuration. You can find information about the fields in the table below.
Select Add to save the configuration.
To download the Signicat metadata file in XML format, select Get Signicat's metadata.

URL configuration fields

Registering a new Metadata URL

To fetch your metadata file, we first need to check that the URL is safe. Before adding a new Metadata URL, please contact us by creating a support ticket in the Signicat Dashboard.

Required fields are marked with an asterisk (*).

Advanced configuration

Learn more about advanced configuration in the URL configuration section of the SAML 2.0 documentation.

Metadata file example

Here is an example of a SAML 2.0 metadata file:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" ID="_9ef5602b6f9ed8b75334f563f91322d2"
                     entityID=ENTITY_ID>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        XML_SIGNATURE
    </ds:Signature>
    <md:SPSSODescriptor AuthnRequestsSigned="true" WantAssertionsSigned="true"
                        protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                <ds:KeyName>KEY_NAME</ds:KeyName>
                <ds:X509Data>
                    <ds:X509Certificate>
                        X509_ENCODED_CERTIFICATE
                    </ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                                     Location="https://*SP_CLIENT_DOMAIN*/saml/acs" index="0"
                                     isDefault="true"/>
    </md:SPSSODescriptor>
    <md:Organization>
        <md:OrganizationName xml:lang="en">ORG_NAME</md:OrganizationName>
        <md:OrganizationDisplayName xml:lang="en">ORG_DISPLAY_NAME</md:OrganizationDisplayName>
        <md:OrganizationURL xml:lang="en">ORG_URL</md:OrganizationURL>
    </md:Organization>
</md:EntityDescriptor>

After you have configured the SAML metadata in the Dashboard, you are ready to initialise a request for end-user authentication.

SAML authentication examples

When the end-user wants to authenticate to your services over a SAML connection, the service provider (your app) and the identity provider communicate by sending:

A request: AuthnRequest
A response: AuthnResponse

Below, you can find examples of requests and responses. For more examples, see the SAML examples.

AuthnRequest example

The SAML AuthnRequest can be simple. You can always add more information in the request, but the request can be as minimal as the following example (POST binding):

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:AuthnRequest xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" AttributeConsumingServiceIndex="1"
                     Destination="https://*YOUR_SIGNICAT_DOMAIN*/auth/saml/login" ForceAuthn="true"
                     ID="_b6a016332e19a825bb42917c9870c93a" IssueInstant="2021-03-09T10:26:17.210Z"
                     Version="2.0">
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        ENTITY_ID
    </saml2:Issuer>
    <ds:Signature xmlns:ds="https://www.w3.org/2000/09/xmldsig#">
        XML_SIGNATURE
    </ds:Signature>
</saml2p:AuthnRequest>

The SAML AuthnRequest request needs to be encoded for transmission. Usually, it's compressed, then Base64-encoded and finally URL-encoded. Many SAML libraries handle this automatically.

Example authorisation URL

To initiate an authentication flow using SAML, you typically redirect the end-user to the authorisation URL. Depending on the SAML binding, you send the request in a different format. For example, for POST binding you can generate an authorization URL like this:

POST https://<YOUR_SIGNICAT_DOMAIN>/auth/saml/login

and pass the following in the body of the request:

SAMLRequest is your encoded AuthnRequest request.
RelayState is optional and can be used to retain state information to return to after authentication.

AuthnResponse example

Example of a SAML response AuthnResponse after the end-user logged in with eHerkenning:

<?xml version="1.0" encoding="UTF-8"?>
<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" Destination="https://*SP_CLIENT_DOMAIN*/saml/acs" ID="_8ecbe9dcd8c6e4765d5b6bd9cf5f2010" InResponseTo="_6dee7048f7b558987b5d9900e1b20832" IssueInstant="2023-12-11T12:35:48.235Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">https://*YOUR_SIGNICAT_DOMAIN*/auth/saml</saml2:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        XML_SIGNATURE
    </ds:Signature>
    <saml2p:Status>
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </saml2p:Status>
    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="_03c096c04b157811ec2af48c91e4d618" IssueInstant="2023-12-11T12:35:48.263Z" Version="2.0" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
        <saml2:Issuer>https:/*YOUR_SIGNICAT_DOMAIN*/auth/saml</saml2:Issuer>
        <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
            XML_SIGNATURE
        </ds:Signature>
        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="urn:etoegang:HM:00000003244440010000:entities:9713">k5QDBPNavooSgsxQNCITxSnQc5oo37cqev726-Iz1-Y=</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="_6dee7048f7b558987b5d9900e1b20832" NotOnOrAfter="2023-12-11T12:37:48.263Z" Recipient="https://*SP_CLIENT_DOMAIN*/saml/acs"/>
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotBefore="2023-12-11T12:35:43.263Z" NotOnOrAfter="2023-12-11T12:37:48.263Z">
            <saml2:AudienceRestriction>
                <saml2:Audience>ENTITY_ID</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AttributeStatement>
            <saml2:Attribute Name="name">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Gerarda Josephina Kierkegaard</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="firstName">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Gerarda Josephina</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="lastName">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Kierkegaard</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="email">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">email@example.com</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="pseudo">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">03659FB1FAE5D26DB2D28866C1A4FE7F4E1CD5E62DD2552EE3D3B11D4C27163D@9162F54B3B07284AC4E147A849DEAEE4</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="kvkNr">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">24444001</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="rsin">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">819935177</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="serviceID">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">urn:etoegang:DV:00000003244440010000:services:9121</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="serviceUUID">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">cf1c1457-cc97-4b47-a324-25d1a97db3cb</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="intermediateKvkNr">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">24444002</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="companyName">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Signicat</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="intermediateCompanyName">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xsd:string">Intermediary</saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
        <saml2:AuthnStatement AuthnInstant="2023-12-11T12:35:48.264Z" SessionIndex="14779d0d-08bb-4929-95a2-499363b122f7">
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport</saml2:AuthnContextClassRef>
                <saml2:AuthenticatingAuthority>urn:etoegang:HM:00000003244440010000:entities:9713</saml2:AuthenticatingAuthority>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
    </saml2:Assertion>
</saml2p:Response>

Next steps

This guide introduced how the eID and Wallet Hub works in a nutshell. Next, we recommend learning more about SAML 2.0 and exploring the eIDs documentation.

SAML 2.0

Find out more about SAML, an XML-based standard for exchanging authentication and authorisation data between security domains.

Supported eIDs

View and learn how to integrate with the eIDs

SAML 2.0

How to exchange SAML metadata

URL configuration fields

Form configuration fields

Metadata file example

SAML authentication examples

AuthnRequest example

Example authorisation URL

AuthnResponse example

Next steps