Developer Pages

# Java Adapter

For the Java adapter, only the Long Term Support (LTS) versions will be supported. Learn more about the LTS versions (opens new window).

# Introduction

The Java Adapter allows customers to easily integrate their existing applications with the Signicat eHerkenning Broker.

The adapter provides the following functionality:

  1. Send a SAML 2.0 Authentication Request to the Signicat eHerkenning Broker.
  2. Process a SAML 2.0 response from the Signicat eHerkenning Broker and extract the information from this response:
    1. The status (e.g. success, cancelled, error or session expired)
    2. If the status is successful:
      1. A unique, persistent identifier, called NameId, that allows you to identify returning users;
      2. The value of relay state;
      3. The level of assurance of the request;
      4. A list of attributes provided by the Identity Provider.
  3. Send a SAML 2.0 Logout Request to the Signicat eHerkenning Broker.
  4. Generate and sign SAML 2.0 compliant metadata.

The Java Adapter is an alternative to building a SAML implementation yourself. Building your own implementation is not recommended due to the potential of introducing unintended security vulnerabilities. The advantages of using our adapter instead of your own implementation are:

  1. Guaranteed compatibility with the Signicat eHerkenning Broker;
  2. Support offered to your developers through software updates and upgrades;
  3. Support for future features of SAML through a simple upgrade of the adapter library.

Finally, using the Java Adapter does not require any knowledge of the SAML protocol. The adapter should enable you to quickly start your implementation whilst providing you with a secure connection to eHerkenning and eIDAS, as well as guaranteed long term support. Please consult your Signicat partner or sales representative for more information.

# Requirements

  • Java 1.7 or higher
  • OS for adapter: OS independent (for maven and local tomcat)
  • OS for demo application:
    • Linux for Docker solution
    • OS Independent for maven or local tomcat
  • Maven version: min 3.3.9

# Getting started

The archive you have received contains everything you need to start a secure connection with the Signicat eHerkenning Broker.

First start the Demo Application, that uses the adapter, so that you can familiarize yourself with its functionality. You can start the Demo Application through Maven, Docker or a local Tomcat installation.

# Quick start guide

To start the Demo Application, just follow the instructions below.

  1. Extract the contents of the demo zip directory to your development machine.
  2. Set-up the following properties for your JRE -> jaxp.properties file:
    1. javax.xml.accessExternalSchema = all
    2. javax.xml.accessExternalDTD = all
  3. Start the Demo Application using the tool of your choice.

    1. Through Maven (only for Java 11)

      1. On the command line, go into the directory in which you extracted the zip file and run mvn spring-boot:run

    2. Through Docker

      1. On the command line, go into the directory in which you extracted the zip file and run sudo startDemo.sh
      2. Run sudo stopDemo.sh to stop the demo application.

    3. Through your local Tomcat installation

      1. Extract the contents of the demo zip directory to your development machine.
      2. Set a system property for your local Java web server named adapter.properties.file and value equal to the adapter.properties configuration file path.
      3. Copy configuration files from unzipped directory …..
      4. Adjust the adapter.properties file with your custom values for the following properties:
        1. Alter the sp.config.location setting to make it refer to your Service Provider configuration file.
        2. Alter the broker.config.location setting to make it refer to the eHerkenning Broker metadata file.
        3. Alter the services.config.location setting to make it refer to your services configuration file.
        4. Make sure your application server has read rights on the directories containing the configuration files.
        5. Adjust the keystore.file.location setting to make it refer to the KeyStore file.
        6. Make sure the KeyStore file is password protected. Set the keystore.password setting to the KeyStore encryption password.
      5. Make sure your application server runs on https (the provided ssl-keystore.jks contains an example certificate for demo ssl use).
      6. Deploy the application (rename it to adapter.war) onto your local Java web server, so that the url https://adapter.local.test-development.nl:8080/adapter (opens new window) maps to the root of the application.
      7. Open the page https://adapter.local.test-development.nl:8080/adapter (opens new window). This page should render with a “Signicat Adapter Demo” header.
      8. Open the page https://adapter.local.test-development.nl:8080/adapter/metadata (opens new window) . The expected result is a page containing a list of links to pages rendering XML documents with the metadata of all your available connections to eHerkenning Brokers. Fix any errors as indicated by the system. When the XMLs render correctly, configuration of your system is complete.

# Executing a login flow

  • Open the Demo Application by browsing to https://adapter.local.test-development.nl:8080/adapter (opens new window).
    1. Click on ‘START LOGIN’.
    2. Click on ‘OK’.
    3. Click ‘CONTINUE WITH DEFAULTS’.
    4. The expected result is a selection screen rendered by the Signicat eHerkenning Broker.
  • Select the Identity Provider of your choice and log in using that Identity Provider.
  • After logging in, you should be redirected back to your localhost environment.
    1. The Signicat eHerkenning Broker returns you to https://adapter.local.test-development.nl:8080/adapter/acs (opens new window). On this endpoint, the Demo Application uses the Signicat Adapter to process the response from the Identity Provider and stores the returned values in the user HTTP session.
    2. The ACS-servlet redirects to the Demo Application. This page shows the information obtained from the Identity Provider through the Signicat Adapter.
Last updated: 4/11/23, 2:27:56 PM UTC