Developer Pages

# Security and Validations

# Sessions

The adapter stores data for security validations in the user session. Regenerating and invalidating sessions is the responsibility of the service provider.

We recommend that the application server defines and enforces a timeout for all user sessions.

When generating a new session we recommend that either a standard framework or the existing mechanism of the application server is used so that the sessions IDs are secure: sufficiently long, random and unique across all of the users.

For creating cookies we recommend that the application server is configured to set appropriate domain and path properties. Additionally, the cookies should be configured for “HttpOnly” and have the secure flag set to “true”.

Another recommendation for handling sessions on the server side is to configure the application server to use cookies for session tracking (as opposed to URL rewriting).

# Input Validation

Upon finishing the authentication/authorization process the adapter will provide the API caller with a Response object containing information about the user and the authentication status. The service provider needs to perform proper validation of the response data to make sure that it can be trusted, before using any of that data.

Special care is needed when handling the RelayState data as it is sent outside of the SAML message and therefore is not protected by the message signature or by any other SAML protocol security mechanisms.

# Character Escaping

For security reasons the RelayState parameter will have all XML specific characters escaped.

# Authentication

We recommend that the ACS endpoint always use the HTTPS protocol. This endpoint is the one receiving the authentication response (containing the user assertions) so it must be handled via a secure connection.

When using ARTIFACT binding the adapter will perform a backchannel call to the broker in order to fetch the SAML message corresponding to an artifact ID. This communication should happen over a secure connection and must use mutual authentication with certificates. We recommend that these certificates be stored in a password protected keystore and that the keystore itself be stored in a secure location, accessible only to trusted system administrators.

To control the details of the backchannel connection we recommend using the java.security file available on the machine where the application is running. This file defines the protocol to be used (it should be at least TLS1.2) together with specific ciphers to be used for encryption.

# Access Control

Upon successful user authentication the adapter will provide a Response object containing the authentication status together with a number of assertions about the user. We recommend that you check all of the information contained in the Response object before granting any permissions to the user. It is mandatory to check the status field to make sure that the login was done successfully.

Authorizations to your system should be granted by taking the assertion information into account. The user should not be allowed to perform any action for which they are not authorized according to the information provided following their authentication process.

# SSL Certificates and Signing Certificates

We strongly recommend that you use different certificates for signing and for SSL transport.

# Exception: eHerkenning

eHerkenning environments require that the same certificate is used for both ssl client authentication and signing.

# Polymorphic Pseudonym and Identity Decryption Keys

The adapter does not do polymorphic. In order to support it, it will need to be implemented inside the application that uses the SDK. However, in order to help the implementer know when decryption is necessary, the nameQualifier of the attribute needs to be checked for the following values for BSN or PseudoID (please keep in mind that these values can change depending on the Eherkenning version):

urn:etoegang:1.12:EntityConcernedID:BSN
urn:etoegang:1.12:EntityConcernedID:PseudoID

Also, the NameId would be derived from one of these two attributes so a new parameter has been introduced NameIdNameQualifier, which should also be checked for the above two values and when the value matches the NameId should be polymorphically decrypted.

# SHA-256

The adapter uses SHA-256 for signing messages; although unlikely please keep in mind that SHA-256 is vulnerable to a “preimage attack” https://en.wikipedia.org/wiki/SHA-2 (opens new window)

# Errors and Logging

The adapter tries to handle the error cases internally as much as possible, but there are situations when it cannot take the appropriate measures. In such situations an exception is thrown to the caller of the adapter API (e.g. missing configuration files). We recommend that you catch and handle all exceptions on your side and that you take special measures to make sure these exceptions are not exposed publicly, as they could include information that is privacy and security sensitive.

# Handling Errors

No output messages should provide sensitive information; do not output stack traces, session IDs, user information or information about the version of the framework and of the tools that you are using.

# Logging

The adapter is using the slf4j facade to handle the logging events, which means that at runtime you can specify any API implementation of your choice.

To adjust the logging to fit your needs please use the configuration property file of your chosen framework.

Regardless of the framework you select, we recommend that you follow the guidelines below for securely handling your logging:

  • Each log event must contain enough relevant information so that it enables a detailed investigation of the event timeline
  • The logged messages must not be processed or executed as code, neither in the application itself nor in any other application that processes or shows the messages
  • Security logs must not be viewable or editable by unauthorized personnel
  • To prevent log injection attacks please verify that all non printable symbols are encoded in the log
  • Create separate entries between log fields from trusted and untrusted sources
  • Create integrity checks for security logs in order to prevent unauthorized modification
  • Use proper log rotation and store the logs on a different partition than the application

Please note that the Demo Application should not be taken as a reference for following these guidelines. The logging in the Demo Application is configured for ease of debugging and of understanding the inner works of the Connectis Adapter.

# Cryptography

We recommend that you:

  • have an explicit policy when it comes to cryptographic keys management (e.g. generation, distribution, revocation, and expiration)
  • verify that the cryptographic keys lifecycle is properly enforced
  • store all sensitive information (e.g. personal information) encrypted and that you perform all communication that includes such information via protected channels. For example TLS should be used for the ACS endpoint that provides access to the user assertions.

# Server Certificates

We recommend that you follow these guidelines for handling server certificates:

  • all TLS connection failures are logged
  • for all the client connection certificates all the certificate paths are built and verified with trust anchors and revocation information
  • all connections to external systems that involve sensitive information or functionality are authenticated

# Server Resources

The adapter configuration files (.properties and .xml) need to be stored on the server storage partition in order for the adapter to be able to read them correctly.

When it comes to server resources we recommend that you:

  • verify all untrusted files
  • do not store configuration files or any other sensitive resources under webroot
  • configure the Web Application Server to deny access to remote resources and systems outside of its scope

# Server Limits

All server limits should be known and tested. Please make sure that you analyze and monitor all activity on the server and prevent unusual behaviour or attacks.

# Server API Headers

If your application has API endpoints please make sure that at least the two headers are added to the response:

  • X-Content-Type-Options: nosniff
  • Content-Disposition: attachment; filename="api.json" (or the equivalent)

# Web Application Administration

For any web application we strongly recommend that the web administration and management functions are only available to the web service administrators. This should be always be verified before going live with any web application and after any significant permissions configuration change.\

Last updated: 6/22/23, 9:00:44 AM UTC

← Getting Started →