Developer Pages

# Artifact Binding

TIP

See examples at the bottom of the page.

This document describes the steps that need to be done so that Service Providers can use the SAML HTTP-Artifact binding when communicating with the Signicat Identity Broker.

The document focuses only on the specific activities needed to enable HTTP-Artifact binding. All the other configurations required to successfully use the adapter are included in the main user guide document.

The difference between communicating using the HTTP-Artifact binding and communicating using one of the other two options (HTTP-Redirect, HTTP-POST) is that the SAML message (containing e.g. authentication request/response information) is not accessible to the user being authenticated. These messages are exchanged by establishing a machine to machine communication channel between the Service Provider and the Signicat Identity Broker.

There are two main reasons for a Service Provider to use HTTP-Artifact binding to carry out the process of authenticating/logging out a user:

  1. There are limitations on the user User-Agent that preclude or discourage the transmission of the SAML messages
  2. The risk of allowing the user or anyone that has access to user’s User-Agent to see the SAML messages is found to be unacceptable

# Enable web server two-way authentication

As a prerequisite for using HTTP-Artifact binding, the Web Server running the adapter must have mutual authentication enabled (both client and server needs to prove their identity). Below is a sample configuration to enable mutual authentication for the Tomcat web server:

<Connector
    port="8443"
    protocol="org.apache.coyote.http11.Http11Protocol"
    maxThreads="150"
    SSLEnabled="true"
    scheme="https"
    secure="true"
    clientAuth="want"
    keystoreFile="/usr/local/tomcat/configuration/core/keystore.jks"
    keystorePass="insecure"
    truststoreFile="/usr/local/tomcat/configuration/core/truststore.jks"
    truststorePass="insecure"
    sslProtocol="TLS"
/>

The above configuration should be placed inside Tomcat’s server.xml file (available under the tomcat installation path by default, in the “conf” folder).

Specific to each environment are the keystore and truststore locations and passwords. The stores should be placed in a location accessible to the Tomcat process.

Mutual TLS (where the client also needs to authenticate by using a certificate) is achieved by setting the “clientAuth” property. The value ”want” won’t force the client to authenticate to the server but will persuade the server to make the client certificates available to the servlets. The adapter will then handle the client authentication and reject the communication if no certificates have been provided.

To have the server handling the client authentication part without impacting the regular Browser users, some more configuration is required.

For Tomcat that entails placing the above Connector element inside a Server element that applies to a specific context path only. That path will be the endpoint that will receive the machine to machine requests for exchanging the SAML messages. A good name to choose is “/ars” (wich stands for Artifact Resolution Service).

The value for the “clientAuth” property can be set to “true” only after doing such configuration. If set for all context paths it will cause the server to only accept connections from clients having digital certificates, which places a serious limitation on which users are able to access the services provided by the Service Provider.

There are specific configurations that need to be done to enable mutual authentication given a specific web server. Signicat can help you find the best solution for almost all the servers available on the market.

# Configure keystore

As described in the adapter user guide, a keystore needs to be set up to contain the service provider private key. This key will be used by the adapter to sign SAML messages exchanged with the Signicat Identity Broker. To increase security, machine-to-machine messages sent using the HTTP-Artifact binding should also be signed.

An important note is that self signed certificates are not allowed with HTTP-Artifact binding.

Before configuring the Adapter to use HTTP-Artifact binding, the Service Provider must obtain a valid certificate from a trusted CA (or signed by a trusted CA). The certificate common name must contain the hostname of the machine where the adapter will be deployed. This is needed because the Signicat Identity Broker will validate that the clients have certificates matching the domain name from where the requests are sent.

The current keystore provided with the adapter contains a self signed certificate. This is acceptable, for testing purposes, only when using the HTTP-POST or HTTP-Redirect bindings.

# Configure truststore

The truststore will be used by the server to verify the clients’ identity. It contains a list of certificates to be matched with the certificates presented by the clients when making machine to machine requests.

The truststore path together with the password need to be configured in the web server configuration system, as shown in the example above for Tomcat. Upon request, Signicat can provide all the needed certificates and the Service Provider can handle the task of properly setting up the trust store.

# Enable Artifact binding in SP configuration and code

To support HTTP-Artifact binding the SignicatAdapter API includes a method for handling machine-to-machine requests coming from the Connectis Identity Broker.

The following changes need to be done to enable HTTP-Artifact binding communication between the Service Provider and the Signicat Identity Broker:

  1. If not already present, please add the “<Binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact</Binding>” entry to the “SupportedBindings” list, the “ArtifactResolutionServiceIndex” value and the “sslKeyName” attribute to the Service Provider configuration file.
  2. The “PreferredBinding” property from the Service Provider configuration file needs to be set to “urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact”.
  3. The Service Provider configuration file needs to have an “artifactResultionServiceUrl” attribute that contains the path previously configured for two-way authentication (i.e. “ars”) to a servlet that calls the continueArtifactResolve() method defined in the SignicatAdapter API class.
  4. Perform the metadata exchange, as detailed in the Adapter documentation; if you have performed the exchange in the past you will need to perform it again so that the Signicat Identity Broker can use the information configured in the previous steps.

# Examples

Here are some examples of how such configuration files should look:

# CS example

public void Index()
{
    MvcHttpContext context = new MvcHttpContext(ControllerContext.HttpContext);
    IHttpRequest request = context.Request;
    string spEntityId = request.GetMandatoryNonEmptyParameter(StartLoginController.SpEntityId);
    DemoSession.PutDemoDataInSession(ControllerContext.HttpContext.Session, new DemoData(spEntityId));
    ConnectisAdapter.Login(context.Response, spEntityId)
        .WithRelayState(request.GetParameter(StartLoginController.RelayState))
        .WithServiceIndex(
            int.Parse(request.GetParameter(StartLoginController.ServiceIndex), CultureInfo.InvariantCulture))
        .WithLevelOfAssurance(int.Parse(request.GetParameter(LoaLevel), CultureInfo.InvariantCulture))
        .WithIdpEntityId(request.GetParameter(IdpEntityId))
        .WithScopedIdpEntityId(request.GetParameter(ScopedIdpEntityId))
        .WithBinding(SamlBinding.Post) // Force to use POST binding for sending the request
        .StartLogin();
}

# Java example

ConnectisAdapter
    .login(request, response, spEntityId)
    .withRelayState(relayState)
    .withIdpEntityId(idpEntityId)
    .withServiceIndex(serviceIndex)
    .withLevelOfAssurance(loaLevel)
    .withScopedIdpEntityId(scopedIdpEntityId.isBlank() ? null : scopedIdpEntityId)
    .withBinding("urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST")
    .startLogin();
};

# SDK example

<?xml version="1.0" encoding="UTF-8"?>
<ServiceProvider>
    <ServiceProviderDefinition entityId="urn:etoegang:DV:00000003244440010000:entities:7799"
                               contactEmail="technicalsupport@signicat.com"
                               contactName="Signicat Service Desk"
                               contactPhone="0880120222"
                               organizationName="Signicat AS"
                               organizationDisplayName="Adapter"
                               organizationUrl="https://signicat.com"
                               assertionConsumerServiceUrl="https://your-website.nl/adapter/acs"
                               artifactResolutionServiceUrl="https://your-website.nl/adapter/ars"
                               signingKeyName="e3688f9d9bc21109bcfa8df7bc2d353b216d25bc"
                               encryptionKeyName="e3688f9d9bc21109bcfa8df7bc2d353b216d25bc"
                               notBeforeGracePeriodInSeconds="120"

                               sslKeyName="tumbprint"/>
    <!-- sslKeyName, this is has to be the same certificate that will be used by your application server for serving HTTPS traffic on the Artifact Resolution Service endpoint. -->
    <Bindings>
        <SupportedBindings>
            <Binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact</Binding> <!-- Add HTTP-Artifact to SupportedBindings -->
            <Binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST</Binding>
            <Binding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect</Binding>
        </SupportedBindings>
        <PreferredBinding>urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact</PreferredBinding>  <!-- set HTTP-Artifact as the PreferredBinding -->
    </Bindings>
    <DefaultServiceIndex>1</DefaultServiceIndex>
    <ArtifactResolutionServiceIndex>1</ArtifactResolutionServiceIndex>
</ServiceProvider>

Note

You can find your own general SDK services file at "$CONFIGURATION_LOCATION/Config/Sps/Services.xml" in your adapter.

Last updated: 9/20/23, 12:13:17 PM UTC

← EHerkenning 1.13 →