Developer Pages

# SAML 2.0 Information

# Choosing SAML 2.0 bindings

The Signicat Identity Broker supports three different mechanisms, known as bindings, to exchange messages:

  1. Redirect binding: This binding is most suitable for sending SAML Requests from your service to the Signicat Identity Broker. Since there is a maximum message size, it is not suitable for sending SAML Responses back from the Signicat Identity Broker to your service.
  2. POST binding: This binding is suitable for sending SAML Requests from your service to the Signicat Identity Broker, and SAML Responses from the Signicat Identity Broker to your service.
  3. Artifact binding: This binding is suitable for sending any SAML message via a machine-to-machine backchannel. To make this binding work, the service provider and the Signicat Identity Broker must be able to communicate directly. This could mean that firewalls, proxy servers, and/or client certificates need to be configured on your side, which makes setting up and debugging this binding more difficult. We therefore advise against using this binding if possible.

Our recommended setup is that you use Redirect Binding to send SAML Requests to the Signicat Identity Broker, and POST Binding to receive SAML Responses from the Signicat Identity Broker.

In case you opt for the SAML Artifact binding to receive responses, please be aware that this means that your service will have to be able to autonomously connect to the Signicat Identity Broker via a backchannel, so that it can retrieve the response from the Signicat Identity Broker. A commonly occurring problem is that the service provider’s firewall blocks the outgoing traffic to the Signicat Identity Broker, and hence the service cannot retrieve the response. Please take this into account when troubleshooting your connection to the Signicat Identity Broker via the SAML Artifact binding.

# SAML 2.0 metadata

In SAML 2.0, metadata is exchanged between components (service providers, the Signicat Identity Broker, and identity providers) to configure how to connect and exchange messages between them. The metadata basically contains the following information:

  • Which URLs to send SAML messages to.
  • Which bindings to use for exchanging messages.
  • Which certificates can be used for checking digital signatures against, to guarantee that the messages come from the appropriate party.
  • What algorithms will be used for calculating digital signatures.

SAML 2.0 metadata is stored as a (signed) XML file in a particular format. You can find the specifications online (opens new window).

The Signicat SAML 2.0 Adapter can automatically create metadata for you, see Signicat SAML 2.0 Adapter. Most SAML 2.0 enabled third party software can automatically generate the metadata as well. If you choose to implement the SAML 2.0 protocol yourself, you may however need to construct metadata by hand.

# Example

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
                     xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                     ID="configuration id"
                     entityID="Entity id">
    <ds:Signature>
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>                <ds:DigestValue>I+hg07X8GD583Py/OhOI7iSaLbUzL7n9yCgVcpdMSsg=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>base64 signature value</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:KeyName>signing key name</ds:KeyName>
        </ds:KeyInfo>
    </ds:Signature>
    <md:SPSSODescriptor AuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo>
                <ds:KeyName>signing certificate key name</ds:KeyName>
                <ds:X509Data>
                    <ds:X509Certificate>signing certificate</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:KeyDescriptor use="encryption">
            <ds:KeyInfo>
                <ds:KeyName>encryption certificate key name</ds:KeyName>
                <ds:X509Data>
                    <ds:X509Certificate>encryption certificate</ds:X509Certificate>
                </ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP"
                                      Location="ARS endpoint"
                                      index="0"
                                      isDefault="true/false"/>
        <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
                                Location="logout endpoint"/>
        <md:AssertionConsumerService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact"
                                     Location="login endpoint"
                                     index="1"
                                     isDefault="true/false"/>
    </md:SPSSODescriptor>
    <md:Organization>
        <md:OrganizationName xml:lang="en">Organization name</md:OrganizationName>
        <md:OrganizationDisplayName xml:lang="en">Organization display anme</md:OrganizationDisplayName>
        <md:OrganizationURL xml:lang="en">Website url</md:OrganizationURL>
    </md:Organization>
    <md:ContactPerson contactType="administrative">
        <md:EmailAddress>support email</md:EmailAddress>
        <md:TelephoneNumber>support phone no.</md:TelephoneNumber>
    </md:ContactPerson>
</md:EntityDescriptor>

# Example of SAML 2.0 messages

# Login request

<samlp:AuthnRequest 
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
    AssertionConsumerServiceURL="url for response" 
    AttributeConsumingServiceIndex="service index value" 
    Destination="url of the Signicat Identity Broker" 
    ForceAuthn="true/false" 
    ID="message id" 
    IsPassive="true/false" 
    IssueInstant="issue instant" 
    Version="2.0">
    <ds:Signature 
        xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod 
                Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod 
                Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference 
                URI="">
                <ds:Transforms>
                    <ds:Transform 
                        Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform 
                        Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </ds:Transforms>
                <ds:DigestMethod 
                    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>
                    base64 encoded digest value
                </ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>base64 encoded signature value</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:KeyName>name of the signing key</ds:KeyName>
        </ds:KeyInfo>
    </ds:Signature>
    <saml:Issuer>issuer</saml:Issuer>
    <samlp:RequestedAuthnContext 
        Comparison="minimum">
        <saml:AuthnContextClassRef>minimal LOA</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

# Login response

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                IssueInstant="2019-02-04T09:21:26Z" Version="2.0"
                Destination="your endpoint"
                ID="message id"
                InResponseTo="message id of login request">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">issuer</saml:Issuer>
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod
                    Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod
                    Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="#_0182d143-f204-3584-8a52-3c2aea597d2f">
                <ds:Transforms>
                    <ds:Transform                           Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
                        <ec:InclusiveNamespaces
                                xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#"
                                PrefixList="xacml-saml"/>
                    </ds:Transform>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>                <ds:DigestValue>digest value</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>base64 encoded signature value</ds:SignatureValue>
    </ds:Signature>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
    <saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
                    Version="2.0" ID="assertion id" 
                    IssueInstant="assertion issue instant">
        <saml:Issuer>assertion issuer</saml:Issuer>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
                         NameQualifier="name qualifier">
            </saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData
                        NotOnOrAfter="2019-02-04T09:26:26Z"
                        InResponseTo="message id of login request"
                        Recipient="your endpoint">
                </saml:SubjectConfirmationData>
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions NotBefore="2019-02-04T09:21:26Z" NotOnOrAfter="2019-02-04T09:26:26Z">
            <saml:AudienceRestriction>
                <saml:Audience>the idp that responded</saml:Audience>
            </saml:AudienceRestriction>
        </saml:Conditions>
        <saml:AuthnStatement AuthnInstant="2019-02-04T09:21:26Z">
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>
                    urn:etoegang:core:assurance-class:loa2
                </saml:AuthnContextClassRef>
                <saml:AuthenticatingAuthority>
                    the idp that authenticated the user
                </saml:AuthenticatingAuthority>
            </saml:AuthnContext>
        </saml:AuthnStatement>
    </saml:Assertion>
</samlp:Response>

# Logout request

<samlp:LogoutRequest 
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" 
    IssueInstant="2019-02-04T09:28:54Z" 
    Version="2.0"
    Destination="idp logout endpoint" 
    ID="message id" >
    <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:SignedInfo>
            <ds:CanonicalizationMethod 
                Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod 
                Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference 
                URI="">
                <ds:Transforms>
                    <ds:Transform 
                        Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform 
                        Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </ds:Transforms>
                <ds:DigestMethod 
                    Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>FMCM4CvxJWw6+3ugte2VTy/V+
                    P6RnrA0YVd6cMTNr2s=
                </ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>base64 value of the signature</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:KeyName>name of the key used to sign</ds:KeyName>
        </ds:KeyInfo>
    </ds:Signature>
    <saml:Issuer>issuer</saml:Issuer>
  <saml:NameID>id of the user that wants to logout</saml:NameID>
</samlp:LogoutRequest>

# Logout response

<samlp:LogoutResponse xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
                      IssueInstant="2019-02-04T13:16:00Z" Version="2.0"
                      Destination="your logout endpoint"
                      ID="message id" 
                      InResponseTo="message id of logout request">
    <saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">
        issuer
    </saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
    </samlp:Status>
</samlp:LogoutResponse>
Last updated: 4/11/23, 2:27:56 PM UTC

← Signicat Support →