Manual SDK Configuration

Setup

To properly use the adapter in your application please follow these steps:

1. Create a java keystore if you don’t have one already
2. Copy the sp-client-saml-x.x.jar from ($PROVIDED_FOLDER\lib\) to your external library folder
3. Copy configuration folder $PROVIDED_FOLDER to the configuration location of your Java Server
4. Copy the keystore to $PROVIDED_FOLDER\configuration\core\
5. Add the following system property to your Java Web Server adapter.properties.file with the value “$CONFIGURATION_LOCATION\configuration\adapter.properties”
6. Edit the $CONFIGURATION_LOCATION\configuration\adapter.properties file with the following configuration:

#saml connections configuration
sp.config.location=$CONFIGURATION_LOCATION/configuration/sps/$YOUR_SP_FILE_NAME.xml
services.config.location =$CONFIGURATION_LOCATION/configuration/sps/services.xml
broker.config.location=$CONFIGURATION_LOCATION/configuration/idps/$CONNECTIS_BROKER_FILE_NAME.xml
loa.config.location=$CONFIGURATION_LOCATION/configuration/core/LevelOfAssurance.xml
signing.algorithms.config.location=$CONFIGURATION_LOCATION/configuration/core/SigningAlgorithms.xml

#error codes and internationalization
messages.file.location = $CONFIGURATION_LOCATION/configuration/core/
messages.file.name=messages
application.locale=default

#certificates and keys
keystore.file.location=./configuration/core/keystore.jks
keystore.password=insecure
keystore.type=jks
truststore.file.location=./configuration/core/truststore.jks
truststore.password=insecure
truststore.type=jks

certificates.check.expiration=true

Configure your service provider

This section will describe how to configure your service provider.

Your Service Provider is described by two xml files, both of them found under “$CONFIGURATION_LOCATION/configuration/sps/”:

• $YOUR_SP_ENTITY_ID.xml
• services.xml

The $YOUR_SP_ENTITY_ID.xml file contains the following information (property names are case sensitive):

• entityId - the entity id that you want your service to have (please note that some federations require specific formats)
• contactEmail - Contact email of your service
• contactName - The name of your service
• contactPhone - Phone number for your service
• organisationName - The name of your organisation
• organisationDisplayName - The name that you want to display for your organisation
• organisationUrl - URL of your organisation
• assertionConsumerServiceUrl - The endpoint to which you want the IdPs to return the login response
• singleLogoutServiceUrl - The endpoint to which you want the IdPs to return the logout response
• signingKeyName - The name of your certificate configured at the previous step, used for signing SAML protocol messages, SHA256 or SHA1 of the certificate is also accepted
• sslKeyName - The name of your certificate configured at the previous step, used for ssl communication, SHA256 or SHA1 of the certificate is also accepted
• encryptionKeyName - The name of your certificate configured at the previous step, used for encrypting SAML protocol messages, SHA256 or SHA1 of the certificate is also accepted
• SupportedBindings - A list of the supported communication protocols for your service
• PreferredBinding - The default communication protocol that your service uses
• DefaultServiceIndex - The default service index that your service provider will use
• ArtifactResolutionServiceIndex - The service index that your service provider will use for its Artifact Resolution Service; if your service provider supports artifact binding (in the SupportedBindings list) then this value must be configured

The services.xml file contains the definition of all service indexes for all SPs that you have configured. It contains the following information (property names are case sensitive):

• serviceIndex - The service ID
• entityId - The service provider entity ID that the serviceIndex is for
• AcceptIdpInitiatedResponse - Specifies if your service accepts IdP initiated response
• Passive - Specifies if your service accepts passive login
• ForceAuthn - Specifies if your service accepts force authentication
• LevelOfAssurance - The Level of Assurance for your service
• LevelOfAssuranceComparison - The Level of Assurance comparison level
• DefaultBrokerEntityId - The entity ID of the default IdP that your service communicates with.

You can test that the data you have entered is correct by visiting the service provider metadata endpoint. See the corresponding section for details.

Optional: use a different language for the error messages.

• Set application.locale property in the adapter.properties file to reflect the country code of the language.
• Create a new file in the directory referred by messages.file.location, with the name obtained by adding the language suffix (language-locale) to the value of messages.file.name setting in adapter.properties (e.g. messages_nl-NL.properties for Dutch messages).

Exchange metadata with the Signicat eHerkenning Broker

This section will provide information about the metadata exchange process.

The metadata exchange is a bidirectional agreement between an SP and an IdP that they communicate with each other.

To properly exchange the metadata:

• Go to the metadata endpoint of the desired Service Provider
• Save the response to an XML file
• Send the XML file to Signicat Technical Support asking that it is added to the list of supported SPs

By default the adapter already has a couple of IdPs configured that you can communicate with. If you wish to communicate with another one (e.g. switch to using the production IdP) you need to do the following:

• Ask Signicat Technical Support for the metadata file
• Copy the metadata file to “$CONFIGURATION_LOCATION/configuration/idps/” and configure adapter.properties by adding a new entry under broker.config.location (broker.config.location is a comma-separated values list of such paths).

For example if under $CONFIGURATION_LOCATION/configuration/idps/ you have one file “broker.xml” then “adapter.properties” should contain the following line: broker.config.location=$CONFIGURATION_LOCATION/configuration/idps/broker.xml

The Signicat Technical Support will provide you with a new metadata file: broker_prod.xml. Copy the file under $CONFIGURATION_LOCATION/configuration/idps/ and change the “adapter.properties” to look like this: broker.config.location=$CONFIGURATION_LOCATION/configuration/idps/broker.xml,$CONFIGURATION_LOCATION/configuration/idps/broker_prod.xml

Your SP will be able to communicate with both IdPs after this step.