link
Developer Pages

# About SAML 2.0

Page contents

# Introduction

Security Assertion Markup Language (SAML) is an XML-based standard for exchanging authentication and authorisation data between security domains. This is normally between an identity provider like id.signicat and a service provider (the customer). SAML is a product of the OASIS Security Services Technical Committee (opens new window).

SAML assumes that the end-user has enrolled with at least one identity provider. This identity provider is expected to provide local authentication services to the end-user. However, SAML does not specify the implementation of these local services; indeed, SAML does not care how local authentication services are implemented.

SAML has been a de facto standard protocol for identity management and is now supported by most of the biggest actors in the computer industry. For detailed information about SAML and access to several white papers, visit this page (opens new window) on the OASIS website.

Signicat supports the SAML 2.0 standard fully, via a gateway commonly referred to as the 'SAML gateway' or 'SAML2 gateway'. If you are using an identity federation service such as Microsoft ADFS or Oracle Identity Federation, then you are most likely interested in Signicat's SAML2 gateway.

# Authentication using SAML 2.0

Signicat's SAML2 gateway provides authentication of Internet users over the SAML2 protocol, between service providers (SP) and Signicat as the identity provider (IdP). The SAML2 gateway is integrated with Signicat's ID portal, which means that Signicat can provide authentication over the SAML2 protocol for all ID methods we are supporting today and also new ID methods that we plan to support in the future.

The service provider must establish a SAML2 federation service on their side. Examples of such federation services are:

Setting up a SAML2 authentication service between an SP and an IdP requires no programming and no third-party client kits, only configuration. The IdP and other communication parameters between SP and IdP should be configured in this SAML2 federation service.

# Using the SAML 2.0 protocol

Establishing a SAML2 configuration requires an agreement with Signicat. After the agreement is signed, we will create a SAML2 configuration for your application(s).

After the SAML2 configuration is established you need to define the SAML2 configuration in the federation system. During the integration, the service provider and Signicat exchanges SAML2 metadata. In the metadata both sides expresses trust for each other. The metadata also describes the type and format of the SAML-request and SAML-response. Metadata for the SP side is available from the federation system. These metadata should be sent as an attachment to support@signicat.com.

When Signicat receives these metadata, they will be deployed in the SAML2 configuration. After deployment we will send a url containing Signicat's metadata in return.

# Single sign-on

The SAML2 gateway also supports global sessions, which is a necessary feature for single sign-on. The SP may register any number of applications and any number of "session domains" in the configuration on Signicat's side.

A session domain describes the rules for global user sessions and defines which applications participate in the session. An application could participate in only one session domain at a time.

When a user has authenticated themselves using strong eID and created a session, they may access all applications participating in the same session domain, without a new eID authentication. The user session is valid until the user explicitly logs out or the session times out.

The timeout rules are defined in the session domain. If the session for a user times out, they are automatically logged out from all applications belonging to the same session domain.

# SAML certificate renewal

Signicat renews its SAML signing certificates every second year (years ending in odd numbers). This section describes the impact of the certificate renewal on Signicat's Connectors and Applications.

# Signicat's connectors (SAML 1.1)

Customers using older versions of Signicat Connectors will be affected by the renewal of Signicat's SAML certificates. This applies to the following versions of the Connectors:

  • on Java platform: Java client kit, v. 2.3.2 or lower
  • on .NET platform: Signicat.Basic.Service v.1.11 .. or lower
  • on .NET platform: Signicat.Basic v.1.0.1.10 or lower

Every time Signicat renews the SAML signing certificates, these customers must replace the old SAML signing certificates with the new ones or add the new ones to the Connector’s truststore.

Customers using newer connectors than the above mentioned will not be affected by the renewal of the SAML signing certificate.

# Signicat authentication using the SAML 2.0 protocol

Customers integrated with the Signicat authentication service using the SAML2 protocol will be affected by the renewal of Signicat's SAML certificates.

Every time Signicat renews the SAML signing certificates, these customers must renew the SAML2 metadata from Signicat.

# SAML certificates

The SAML certificates on preprod.signicat.com, preprod.eu01.signicat.com, eu01.signicat.com and id.signicat.com are different. All certificates are issued by the same CA.

The CA certificate can be downloaded below. The certificate is also embedded in some of the client connectors.

The specific SAML certificate that was issued with the above CA certificate can be found below:

# Frequently asked questions

# I use OIDC, what do I do?

OIDC is unaffected by this change

# I only use Signicat for signature, what do I do?

The SAML signing certificate is the certificate used by Signicat for SAML signing responses.

# What is a "SAML Signing" certificate?

The SAML Signing certificate is the certificate used by Signicat for signing SAML responses.

# I use SAML2, what do I need to do?

You need to replace existing Signicat metadata with new metadata. Contact support@signicat.com to receive new metadata or change your metadata manually by replacing the certificate in our metadata with the new certificate. For further information, refer to How to prepare for a SAML2 certificate change.

# What version of the connector do I use?

For .NET: Find the signicat.basic.dll, check the properties for version. For Java: Locate signicat-client-lib-X.X.X.jar. The version number should be in the file name.

# I don’t use any of Signicat's connectors, what do I do?

If your integration uses Signicat's root CA, you don’t need to do anything. If you use the leaf-certificate, consider adding the root CA or add the new certificate in your integration manually.

# How to prepare for a SAML2 certificate change

The Identity provider (IdP) metadata from Signicat can be found at https://{env}.signicat.com/gateway/{servicename}/saml2/metadata.

When Signicat changes the SAML certificate on Signicat's side, the metadata will automatically be updated with the new SAML certificate.

Signicat changes the SAML certificate every odd year. The Service Provider (SP) must therefore implement and plan for a certificate switch together with Signicat. If the IdP signs the SAML messages with a certificate that the Service Provider does not trust, authentication will fail.

Some Service Provider software products support having multiple certificates installed at once, others rely on a synchronous switch. If your software requires the latter, we recommend agreeing on a suitable time for the switch with Signicat Support to reduce risks.

# How to change the certificate in the metadata manually

An example of Signicat IdP metadata looks like this:

<md:EntitiesDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
	<md:EntityDescriptor entityID="https://preprod.signicat.com/gateway/demo/saml2/metadata">
		<md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
			<md:KeyDescriptor>
				<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
					<ds:X509Data>
						<ds:X509Certificate>MIIDuzCCAqOgAwIBAgIBGTANBgkqhkiG9w0BAQsFADBJMQswCQYDVQQGEwJOTzEUMBIGA1UEChML U2lnbmljYXQgQVMxJDAiBgNVBAMTG1NpZ25pY2F0IEV4dGVybmFsIENBICgyMDQ4KTAeFw0xOTA1 MDMxMzUzNThaFw0yMTA1MDIxMzUzNThaMHgxCzAJBgNVBAYTAk5PMQ8wDQYDVQQIDAZOb3J3YXkx EjAQBgNVBAcMCVRyb25kaGVpbTERMA8GA1UECgwIU2lnbmljYXQxETAPBgNVBAsMCFNpZ25pY2F0 MR4wHAYDVQQDDBV0ZXN0LnNpZ25pY2F0LmNvbS9zdGQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw ggEKAoIBAQC5nM8y4WChls6+3diLpcCmXoxcWakzS0TRnA1P01mRe77jidon7rXWmF1ZXrGllFv6 D1uXAT5mPdTNTY5yn5pkjNxuhfRv804l01rP3Pr695zIGB4CR+BPKQZ03Pjb8SEwF9sRSk4t5uyF w+HUnY7D3Q76Ub/5A51FU5/s0zrkovgW85e1bJfuqd48hWr+oGmfyx4L2Y8oh2AAuoMN0lV/rD4C d6HrLPv6M4CHIlbwbgouX1bASe7J9k8euhMt4J0xpngS5Ui4/nZnanRWmFT2l4rYOzkLrh5ICSBq gAgQmJa2adiRveH2JYfv0iQhIZCRIo/9hfFPS+hr2HC8Wqk3AgMBAAGjfzB9MAkGA1UdEwQCMAAw CwYDVR0PBAQDAgXgMCMGCWCGSAGG+EIBDQQWFhRTaWduaWNhdCBDZXJ0aWZpY2F0ZTAdBgNVHQ4E FgQU2aBHKuzZiHt18CH7nzQOVn+cS/wwHwYDVR0jBBgwFoAUstl+DZ605NwX3br661U41SHRS/Yw DQYJKoZIhvcNAQELBQADggEBAB5A+U2YqB9ynevJkEOAcZEyBLay3XNAJhYvUSWgJz5pnnWrgRrv 5Zir/yH6Nw5Z0NynLoQQqNhpl5zNI8HyvYc1eWGD+fbdD5/l+BGUYmcscOXQW8WMo/G9F+I9AVoy BAs1tjyjbTlRCcCFOCziPJfbBCAF5/hFOWeMCQ/XeZNLZ2CgCrjUInSQQtukY3kB7x6jwqRTBefx 0MtrSGGQVQfNeTztI9Dyqlko8hJEWQLFdDJp1dSJnz7xVtuqXqrUEQYXb1b7KG3Kc3Wx+e7Pxbhr eM2J0XNXDWORJ02vtZ+L1h/vV2feI7K0riP/wUZY+aGopCMGp4c0V/D5UCZGN7w=</ds:X509Certificate>
					</ds:X509Data>
				</ds:KeyInfo>
			</md:KeyDescriptor>
			<md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://preprod.signicat.com/gateway/demo/saml2/ars/soap" index="0" isDefault="true" />
			<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser" />
			<md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser" />
			<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser" />
			<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser" />
		</md:IDPSSODescriptor>
	</md:EntityDescriptor>
</md:EntitiesDescriptor>

(example from https://preprod.signicat.com/gateway/demo/saml2/metadata (opens new window))

To change the certificate, locate the <ds:X509Data> tag and replace its content with the new certificate supplied by Signicat.

You can find the new certificate in the section on SAML certificates on this page.

Simply open the certificate and the metadata in your text editor and replace the contents of the <ds:X509Data> tag.

If you are uncertain or have problems with this process, feel free to contact Signicat Support for assistance with updating the metadata.

# Supported bindings

The Signicat SAML 2.0 gateway supports the HTTP-Redirect, HTTP-POST and artifact bindings.

# HTTP redirect

With this binding, the request or response is attached to the URL as a SAMLRequest or SAMLResponse parameter respectively, with standard encoding (deflated, Base64-encoded and URL-encoded). It is protected by HTTPS if the URL provided in the metadata is HTTPS; however, it will still appear in client side logs and also as HTTP referrer in certain cases.

Use of this binding is fine for requests that do not provide personal information as pre-filled parameters, but not recommended for responses, both because of security and because of the limited assertion size that the query string allows.

# HTTP POST

The SAML request or response is still encoded in the standard way, but this time it appears in the message body rather than the header. In this way, it will not be logged by tools that log URLs. However, the assertion is still transferred to the client and is therefore vulnerable to any malware that infects clients and extracts this kind of information.

# Artifact

This binding has quite a bit of overhead, but is the binding of choice for maximum security. No meaningful information is transferred to the client; rather, an artifact (SAMLArt) is sent. The opposite endpoint then contacts the ArtifactResolutionService specified in the metadata and extracts the SAML request or response via a back channel.

# Standard response fields

The following fields are always provided with a SAML 2.0 response from Signicat. They may be blank if the underlying ID method does not provide the information, but they are never omitted.

All response parameters have a NameFormat of urn:oasis:names:tc:SAML:2.0:attrname-format:basic.

Attribute name Example Description
national-identity 05054512345 National identification number. Never replaced by other variable; other unique identifiers go in the NameID field (see below)
national-identity-country NO Country code as per the national identification number (ISO 3166-1 Alpha-2). This is not necessarily the end-user's nationality.
common-name Doe, John Name of the person identified as it appears in the response from the ID method.
given-name John First name of the person identified, after name splitting performed by Signicat.
surname Doe Last name of the person identified, after name splitting performed by Signicat.
email john.doe@example.com E-mail address as returned by the ID method.

# Specifying authentication contexts

The SAML2 gateway supports specifying authentication methods from the SAML Request by means of the RequestedAuthnContext element. If the authentication context matches exactly one authentication method, only that method will be displayed; otherwise, it will produce a method selection screen. An authentication context that doesn’t match any methods will produce an error message.

There are two ways of invoking an AuthnContext, depending on what you are hoping to achieve.

# AuthnContextClassRef

If you are interested in displaying a selection of authentication methods based on a particular class reference, this is the element of choice. The class reference is expressed as a URN, for example urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI or urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport. The class reference must match at least one of the authentication methods defined in your service. Contact support@signicat.com if you are unsure what class reference to use or if you wish to set up a custom class reference.

Another useful attribute is Comparison. It is defined in the RequestedAuthnContext element and can have the values exact, minimum, maximum or better.

  • Comparison="exact" means that the SAML2 gateway will display those authentication methods that match the AuthnContextClassRef, with no further ado. This is the default value.
  • Comparison="minimum" will extract the signicat.security-level attribute for those methods that match the AuthnContextClassRef and compare it to the authentication methods available in the service. Only those that have a security level equal to, or higher than, the extracted level will be displayed.
  • Comparison="maximum" will extract the signicat.security-level attribute for those methods that match the AuthnContextClassRef and compare it to the authentication methods available in the service. Only those that have a security level equal to, or lower than, the extracted level will be displayed.
  • Comparison="better" will extract the signicat.security-level attribute for those methods that match the AuthnContextClassRef and compare it to the authentication methods available in the service. Only those that have a security level higher than the extracted level will be displayed.

Example:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" Destination="https://id.customer.com/gateway/customer/saml2/sso/browser" ID="id-b5f96406-9934-4cc4-a1b3-897ca35aed13" IssueInstant="2014-11-01T22:42:23.584Z" Version="2.0">
    <saml:Issuer>http://login.customer.com/adfs/services/trust</saml:Issuer>
    <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"></samlp:NameIDPolicy>
    <samlp:RequestedAuthnContext Comparison="exact">
        <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

# AuthnContextDeclRef

This element specifies a single authentication uniquely. Its format is also a URN, namely urn:signicat:SAML:2.0:ac:ref:service_name:method_name. The Comparison attribute will have no impact on AuthnContextDeclRef.

Example:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" Destination="https://id.customer.com/gateway/customer/saml2/sso/browser" ID="id-b5f96406-9934-4cc4-a1b3-897ca35aed13" IssueInstant="2014-11-01T22:42:23.584Z" Version="2.0">
    <saml:Issuer>http://login.customer.com/adfs/services/trust</saml:Issuer>
    <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"></samlp:NameIDPolicy>
    <samlp:RequestedAuthnContext>
        <saml:AuthnContextDeclRef">urn:signicat:SAML:2.0:ac:ref:demo:nemid</saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

# Specifying prefilled information

Some methods accept prefilled information (aka prefilled parameters), which in most cases enables the end-user to omit certain steps. This is useful when for example the end-user must enter the same information in a repetitive way, for example phone number, date of birth, national identification number etc. Instead, the service provider can pre-populate these parameter fields with the correct information, so that these fields are already filled in for the end-user. For information about prefilled parameters per ID method, see Demo Service > Supported URL parameters.

Signicat supports two ways of passing along this information, depending on what your federation agent supports.

# Extensions

This is the preferred way of handling prefilled parameters. Extensions is an optional element in SAML 2.0 allowing arbitrary information to be passed to the identity provider (see section 3.2.1 of the SAML v2.0 standard (opens new window)). Within the Extensions element, simply specify a signicat:Prefilled element, like this:

<signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="subject">05054512345</signicat:Prefilled>

Example:

<samlp:AuthnRequest xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified" Destination="https://id.customer.com/gateway/customer/saml2/sso/browser" ID="id-b5f96406-9934-4cc4-a1b3-897ca35aed13" IssueInstant="2014-11-01T22:42:23.584Z" Version="2.0">
    <saml:Issuer>http://login.customer.com/adfs/services/trust</saml:Issuer>
    <samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"></samlp:NameIDPolicy>
    <Extensions>
        <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="subject">05054512345</signicat:Prefilled>
        <signicat:Prefilled xmlns:signicat="urn:signicat" Parameter="phone">11223344</signicat:Prefilled>
    </Extensions>
</samlp:AuthnRequest>

# URL modification

Some federation agents do not support Extensions and some (most notably Shibboleth) do not allow the parameters to be set dynamically. In those cases, Signicat provides a second, somewhat more roundabout way, which is URL modification. With this scheme, you will need to create a new set of metadata for each anticipated parameter.

The scheme does have its limitations:

  • Since you will need to create a new set of metadata for each anticipated parameter, this scheme works best if you have a limited set of parameters to choose from.
  • The scheme will not work with ADFS. ADFS enforces the rule that no more than one endpoint can use the same certificate to sign SAML assertions and hence, adding the second set of metadata will fail.

# Procedure

First, you need to download the appropriate metadata from https://env.signicat.com/gateway/service_name/saml2/metadata. It will look something like this:

<?xml version="1.0" encoding="UTF-8"?>
<md:EntitiesDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    <md:EntityDescriptor entityID="https://preprod.signicat.com/gateway/demo/saml2/metadata">
        <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <md:KeyDescriptor>
                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                        <ds:X509Certificate><!-- omitted for brevity --></ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </md:KeyDescriptor>
            <md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://preprod.signicat.com/gateway/demo/saml2/ars/soap" index="0" isDefault="true"></md:ArtifactResolutionService>
            <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser"></md:SingleLogoutService>
            <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser"></md:SingleLogoutService>
            <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser"></md:SingleSignOnService>
            <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser"></md:SingleSignOnService>
        </md:IDPSSODescriptor>
    </md:EntityDescriptor>
</md:EntitiesDescriptor>

Create a second set of metadata, modifying the md:SingleSignOnService URLs. Make sure that you modify the entityID as well.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntitiesDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    <md:EntityDescriptor entityID="https://preprod.signicat.com/gateway/demo/saml2/metadata/nordea">
        <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <md:KeyDescriptor>
                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                        <ds:X509Certificate><!-- omitted for brevity --></ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </md:KeyDescriptor>
            <md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://preprod.signicat.com/gateway/demo/saml2/ars/soap" index="0" isDefault="true"></md:ArtifactResolutionService>
            <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser"></md:SingleLogoutService>
            <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser"></md:SingleLogoutService>
            <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser?prefilled.bank=nordea"></md:SingleSignOnService>
            <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser?prefilled.bank=nordea"></md:SingleSignOnService>
        </md:IDPSSODescriptor>
    </md:EntityDescriptor>
</md:EntitiesDescriptor>

Now add this as an endpoint in your federation agent. It will automatically pre-fill the value that you specified.

# Specifying profile and language

Each endpoint is configured on Signicat's side with a default profile and language. However, it is possible to specify it at the customer’s side by modifying the URLs in the metadata. See above for more information on how to modify metadata.

The URLs of the md:SingleSignOnService elements need to be modified like this: https://env.signicat.com/gateway/service_name/saml2/sso/browser/profile_name/language

For example,https://preprod.signicat.com/gateway/demo/saml2/sso/browser/topheader/sv will use the profile topheader and Swedish language.

<?xml version="1.0" encoding="UTF-8"?>
<md:EntitiesDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata">
    <md:EntityDescriptor entityID="https://preprod.signicat.com/gateway/demo/saml2/metadata">
        <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
            <md:KeyDescriptor>
                <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
                    <ds:X509Data>
                        <ds:X509Certificate><!-- omitted for brevity --></ds:X509Certificate>
                    </ds:X509Data>
                </ds:KeyInfo>
            </md:KeyDescriptor>
            <md:ArtifactResolutionService Binding="urn:oasis:names:tc:SAML:2.0:bindings:SOAP" Location="https://preprod.signicat.com/gateway/demo/saml2/ars/soap" index="0" isDefault="true"></md:ArtifactResolutionService>
            <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser"></md:SingleLogoutService>
            <md:SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/slo/browser"></md:SingleLogoutService>
            <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser/topheader/sv"></md:SingleSignOnService>
            <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://preprod.signicat.com/gateway/demo/saml2/sso/browser/topheader/sv"></md:SingleSignOnService>
        </md:IDPSSODescriptor>
    </md:EntityDescriptor>
</md:EntitiesDescriptor>

Alternatively, you can also specify the default language in the Extensions parameter:

<samlp:Extensions>
    <lang>sv</lang>
</samlp:Extensions>

# Error handling

All situations except for a successful authentication are handled through an error response. As per the SAML specification, this response has a major code, a minor code and a status message.

# Major code

Code Description
urn:oasis:names:tc:SAML:2.0:status:Success No error. The call was a success.
urn:oasis:names:tc:SAML:2.0:status:Responder The part responsible for the error is the Signicat SAML2 Gateway.
urn:oasis:names:tc:SAML:2.0:status:Requester The part responsible for the error is the client.

# Minor code

Code Description
urn:oasis:names:tc:SAML:2.0:status:AuthnFailed The responding provider was unable to successfully authenticate the principal.
urn:oasis:names:tc:SAML:2.0:status:NoAuthnContext The part responsible for the error is the Signicat SAML2 Gateway.
urn:oasis:names:tc:SAML:2.0:status:NoPassive Indicates that the responding provider cannot authenticate the principal passively, as has been requested.
urn:oasis:names:tc:SAML:2.0:status:RequestDenied The SAML responder or SAML authority is able to process the request but has chosen not to respond. This status code may be used when there is concern about the security context of the request message or the sequence of request messages received from a particular requester.
urn:oasis:names:tc:SAML:2.0:status:UnknownPrincipal The responding provider does not recognise the principal specified or implied by the request.

# Status message

The status message consist of two parts, an internal Signicat error code and a description. The format is as follows:

<error code>; <description>

# Status codes and messages originating from the Signicat SAML2 Gateway

Code Description
urn:signicat:error:saml2.0:systemerror A system error occurred on the server.
urn:signicat:error:saml2.0:nonexistententity The service provider entity with given entityId is not registered.
urn:signicat:error:saml2.0:authncontextempty Found no authentication methods that complies with the requested authentication contexts.
urn:signicat:error:saml2.0:authncontextmismatch Method did not match requested AuthnContext.
urn:signicat:error:saml2.0:validationfailure Failed while validating SAML1 response from Signicat's ID portal.
urn:signicat:error:saml2.0:session:nocurrent No current session.
urn:signicat:error:saml2.0:session:subjectmismatch Subject in current session did not match requested subject.
urn:signicat:error:saml2.0:session:credentialsfailed The session credentials check failed.
urn:signicat:error:saml2.0:session:nonexistent The session did not exist.
urn:signicat:error:saml2.0:session:nameidmismatch Session subject and requested NameID does not match.

# Status codes and messages originating from Signicat's ID portal

Code Description
urn:signicat:error Unspecified error.
urn:signicat:error:internal Internal system error.
urn:signicat:error:out-of-sequence The request was unexpected at this time.
urn:signicat:error:usercancel The process was aborted by the end-user.
urn:signicat:error:userreject The process was rejected by the end-user.
urn:signicat:error:userpostpone The process was postponed by the end-user.
<saml2p:Status>
    <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder">
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailed"></saml2p:StatusCode>
    </saml2p:StatusCode>
    <saml2p:StatusMessage>urn:signicat:error:usercancel; The process was aborted by the end-user</saml2p:StatusMessage>
</saml2p:Status>

# Finnish Trust Network specifics

Due to requirements from Traficom, you are required to use Full Message-Level Encryption for authentication with the Finnish Trust Network (FTN). Follow these instructions:

# Prerequisites

  • Your SAML 2.0 Service Provider (SP) software must support encrypted assertions (see supported algorithms below). Support for encrypted assertions in SP software is normally enabled by configuring an encryption key and a certificate, but the process can vary depending on the software you are using.
  • You must have an encryption certificate. It must be an X.509 certificate with a key length of at least 1024 bits (RSA).

Important

The encryption certificate is just a means of transporting a public key, it does not need to be issued by a publicly trusted CA and can even be self-signed. It is your responsibility as a service provider to handle the private key of your certificate in a secure, compliant manner.

  • Your metadata must contain your encryption certificate (see metadata section below).

# Encryption algorithms

By default, Signicat supports the following algorithms related to SAML2 assertion encryption in FTN.

Encrypted data algorithms:

  • A128CBC-HS256
  • A256CBC-HS512
  • A128GCM
  • A256GCM

EncryptedKey algorithms:

  • http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p

If you can’t use any of these algorithms, contact us and we will help you find an alternative.

# Metadata

As stated in the prerequisites, the SP metadata must contain an encryption certificate.

The encryption certificate must either be in a KeyDescriptor element without a "use" attribute,

<KeyDescriptor>
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
            <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
    </ds:KeyInfo>
</KeyDescriptor>

or in a KeyDescriptor element with a "use" attribute specifying that it is for encryption.

<KeyDescriptor use="encryption">
    <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
            <ds:X509Certificate>...</ds:X509Certificate>
        </ds:X509Data>
    </ds:KeyInfo>
</KeyDescriptor>

# Implementation

# 1. Test encryption in pre-production

  1. Send the following information to Signicat:
    • Updated SP metadata (in XML format) for pre-production. The metadata can be linked to one of your existing EntityIDs or a new one.
    • The desired encryption algorithms.
  2. Signicat will enable assertion encryption for your entity.
  3. Test encrypted assertions in your pre-production environment.

# Roll out to production

  1. Once you have tested encrypted assertions in pre-production, notify Signicat that you are ready to roll out to production. When you send this notification, include the updated SP metadata (in XML format) for production. The metadata can be linked to one of your existing EntityIDs or a new one.
  2. Signicat will enable assertion encryption in production.

# SAML 2.0 response example

The following example is the response from an authentication performed with Danish NemID.

<saml2p:Response xmlns:saml2p="urn:oasis:names:tc:SAML:2.0:protocol" xmlns:xs="http://www.w3.org/2001/XMLSchema" Destination="http://toolbox.signicat.com:3000/assert" ID="ID2597tkwpe0nug5f8z9ohh1zrd1s6zzk8jnwo077wd8kjw902qr" InResponseTo="_8a11b69b729159c671be8e54cb9b823433601007d5" IssueInstant="2015-08-28T06:53:58.221Z" Version="2.0">
    <saml2:Issuer xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion">
        https://qa.signicat.com/gateway/signicat/saml2/metadata
    </saml2: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:CanonicalizationMethod>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"></ds:SignatureMethod>
            <ds:Reference URI="#ID2597tkwpe0nug5f8z9ohh1zrd1s6zzk8jnwo077wd8kjw902qr">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
                    <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="xs"></ec:InclusiveNamespaces>
                    </ds:Transform>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
                <ds:DigestValue>dw+AB9RXfgEg7ZHNgFCRCESpLWY=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
            oQ8aITfI6FwdTZXW9g6r8cP1zzquPk13FwlkfI9CHEoQSjmK/gSJxz6jBj/FfWesSn9iBsB/7hSz
            PHpsfEd4lEp6iUi7vMXe5a7SO3hsRVduh3CG1iX0WzPgiRpVw6iYMUHLOiTJX5jL7ouW601Wrhv3
            AZgWzqBRSZ8aUSDQxkAlFIklnW3oOKLRuUpaRjRfySmBjZu3c9LktUM8H8YKGsx5U4oyowk6rBW0
            wv7zE0UONGaDMKrgn1UucuFfo19+d7ipP7RPR7ojwugzasFt5hWSNvOLoQfj/rmGkUrKtJD53n8s
            abgq4GADzB+Ox7kUlU5eiNkw3JIkE3wge82EGg==
        </ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate>
                    MIIDuzCCAqOgAwIBAgIBDDANBgkqhkiG9w0BAQsFADBJMQswCQYDVQQGEwJOTzEUMBIGA1UEChML
                    U2lnbmljYXQgQVMxJDAiBgNVBAMTG1NpZ25pY2F0IEV4dGVybmFsIENBICgyMDQ4KTAeFw0xNTA1
                    MTIxMjU2NDZaFw0xNzA5MjMxMjU2NDZaMHgxCzAJBgNVBAYTAk5PMQ8wDQYDVQQIDAZOb3J3YXkx
                    EjAQBgNVBAcMCVRyb25kaGVpbTERMA8GA1UECgwIU2lnbmljYXQxETAPBgNVBAsMCFNpZ25pY2F0
                    MR4wHAYDVQQDDBViZXRhLnNpZ25pY2F0LmNvbS9zdGQwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAw
                    ggEKAoIBAQC/qGp77ITFy8aEbaYPUcC3QbN6/vPzZIs884W+YNLn/kzqw9FKdIGOxmbRAWVzzJH8
                    rQLAYi1bokBpHQ6WRWEf8H51uvWec0rrmYzEOZbW/41wAuAgErDD6UNDH5/2QGnS7NG2kxVqUxW/
                    Vi7yJ5ggaGi8CqZVl2mov7C7ZO/7r+hJSNhz78v4+keCVWSZD3uuuJhivf6mQfeJQTRDal6+Zz9o
                    aOjwWqbMvH8OSDZKFxMRv4fLnXKvrxK8mdUhXT58QwH6XuovUb0TGHwOc++RlaiQ7nz4uIgEj1Ln
                    DXlMsFoeO+4KB6mNMnKvCya7PPseE99BMH5KPhU2oPAxPj1fAgMBAAGjfzB9MAkGA1UdEwQCMAAw
                    CwYDVR0PBAQDAgXgMCMGCWCGSAGG+EIBDQQWFhRTaWduaWNhdCBDZXJ0aWZpY2F0ZTAdBgNVHQ4E
                    FgQUMPWij9jAi5QLQHuaJXNcN1ONJ2AwHwYDVR0jBBgwFoAUstl+DZ605NwX3br661U41SHRS/Yw
                    DQYJKoZIhvcNAQELBQADggEBADnyy8VjSOXmfbbbOwfFZu4gDfYReYxFKBsCSsSjEAJXSccpNc68
                    jq31+OifcdaDte1v9v4ILz2BK6VJPSNjX2pG2HFxC9RgBrGSQ0hUfL6yQCsMvSQw/ogeweLj8ce9
                    wcHa0Pntok1EPpPmKcGTmP94KjAlCM6p849+1B0OjA/Muqi6TNa5MzoDX9H96VrK7BB/Yjpqk6HQ
                    3be7+JoKAc+tjVEOxzivEvRDbGMDn0pNwLVIl4OB7QquMEvfRxxgQl/sBnsk99OTHgd5uI6A/nlm
                    SRqm9WZyzUwNMuHcOaHLosgc2x1iCQmfKIYVxPuBsXZTgo/Nw2d+KECDNI5IKt8=
                </ds:X509Certificate>
            </ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
    <saml2p:Status>
        <saml2p:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"></saml2p:StatusCode>
    </saml2p:Status>
    <saml2:Assertion xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion" ID="ID62nswqka2ta637x44wbs5n2k6wcpvtcty9rx6rwo6r4q4capsa" IssueInstant="2015-08-28T06:53:59.908Z" Version="2.0">
        <saml2:Issuer>
            https://qa.signicat.com/gateway/signicat/saml2/metadata
        </saml2:Issuer>
        <saml2:Subject>
            <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified" NameQualifier="NEMID">9208-2002-2-508510535239</saml2:NameID>
            <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml2:SubjectConfirmationData InResponseTo="_8a11b69b729159c671be8e54cb9b823433601007d5" NotOnOrAfter="2015-08-28T06:54:29.908Z" Recipient="http://toolbox.signicat.com:3000/assert"></saml2:SubjectConfirmationData>
            </saml2:SubjectConfirmation>
        </saml2:Subject>
        <saml2:Conditions NotOnOrAfter="2015-08-28T06:54:29.908Z">
            <saml2:AudienceRestriction>
                <saml2:Audience>https://toolboxnode.net</saml2:Audience>
            </saml2:AudienceRestriction>
        </saml2:Conditions>
        <saml2:AuthnStatement AuthnInstant="2015-08-28T06:53:45.661Z" SessionIndex="1vt4mlwddg216bsixrlgdcvii3gde4j22wd6g86vippujikg8">
            <saml2:AuthnContext>
                <saml2:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:SoftwarePKI</saml2:AuthnContextClassRef>
                <saml2:AuthnContextDeclRef>urn:signicat:SAML:2.0:ac:ref:signicat:nemidjs</saml2:AuthnContextDeclRef>
            </saml2:AuthnContext>
        </saml2:AuthnStatement>
        <saml2:AttributeStatement>
            <saml2:Attribute Name="surname" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"></saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="national-identity" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">0705852669</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="given-name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"></saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="signicat.national-id" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">0705852669</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"></saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="national-identity-country" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">DK</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="common-name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">Kali Kula</saml2:AttributeValue>
            </saml2:Attribute>
            <saml2:Attribute Name="signicat.unique-id" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml2:AttributeValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">9208-2002-2-508510535239</saml2:AttributeValue>
            </saml2:Attribute>
        </saml2:AttributeStatement>
    </saml2:Assertion>
</saml2p:Response>
Last updated: 20/09/2023 12:20 UTC

← About SAML 1.1 →