Skip to content

SAML authentication

As of 4.1.0, the KX Delta Platform supports Single Sign On (SSO) in the form of SAML. This allows the KX Delta Platform to offload authorization to a third party Identity Provider (IDP).

Enabling SAML - install

As of KX Delta Platform version 4.6.0, SAML can be automatically configured using Install Options. See SAML Install Options for more details.

Example configuration

enable-saml=1
saml-sp-metadata-entity-id=<unique entity id>
saml-idp-metadata-file=<path to metadata xml file>
saml-keystore-file=<path to keystore file>
saml-keystore-pass=<keystore password>
saml-keystore-alias=<keystore alias>
saml-decrypt-keystore-file=<path to decryption keystore file>
saml-decrypt-keystore-pass=<decryption keystore password>
saml-decrypt-keystore-alias=<decryption keystore alias>

SPRING_PROFILES_ACTIVE=saml
APPSERVER_SPLASHPAGE=saml/index.jsp

Note: The saml-decrypt-keystore-* properties are optional. If provided in the install config, they will be populated in delta.profile automatically at install time. Assertion encryption can also be enabled post-install on an existing SAML deployment by setting the SAML_DECRYPT_KEYSTORE_* environment variables directly in delta.profile.

Enabling SAML - post deploy

SAML can be enabled post deploy. It requires a number of ENV variables to be set before starting up the environment.

Env Example Description
SPRING_PROFILES_ACTIVE saml To enable SAML SSO, the ENV must be set to saml
SAML_SP_METADATA_ENTITY_ID hostPortUID A unique ID required to identify the KX Delta Platform (Service Provider) to the Identity Provider (IDP). See IDP documentation for specific limitations
SAML_IDP_METADATA_FILE /path/to/idp_metadata_3893727.xml SAML IDPs provide a metadata file used by the SP to allow trusted communication between the SP and IDP. This should be downloaded and available to KX Delta Platform
SAML_KEYSTORE_FILE /path/to/keystore.jks Path to the JKS keystore used for SAML message signing. Any valid keystore can be used. Default alias is serverkeystore. See securityContext.xml to modify
SAML_KEYSTORE_PASS changeit Password for the SAML_KEYSTORE_FILE keystore
SAML_KEYSTORE_ALIAS serverkeystore Alias of the signing key within SAML_KEYSTORE_FILE
SAML_DECRYPT_KEYSTORE_FILE /path/to/enc_keystore.jks Path to the JKS keystore containing the private key used to decrypt SAML assertions. If not set, the signing keystore is used for decryption. Optional.
SAML_DECRYPT_KEYSTORE_PASS changeit Password for the SAML_DECRYPT_KEYSTORE_FILE keystore
SAML_DECRYPT_KEYSTORE_ALIAS saml-encryption Alias of the decryption key within SAML_DECRYPT_KEYSTORE_FILE
APPSERVER_SPLASHPAGE saml/index.jsp SAML requires a specific entry point. This must be defined as in the example column

Update delta.profile

To enable SAML the delta.profile must be updated. If you are running a multi-node deploy then the profile should be changed on any appserver node.

  • Set ENV SPRING_PROFILES_ACTIVE to saml.
  • Provide unique SAML_SP_METADATA_ENTITY_ID.
  • Set the location of the SAML_IDP_METADATA_FILE. The IDP metadata file can be retrieved from the IDP in use.
  • Set the APPSERVER_SPLASHPAGE to saml/index.jsp.

Note: The APPSERVER_SPLASHPAGE can be used to redirect SAML users to a default dashboard once logged in. 

export APPSERVER_SPLASHPAGE=dashboards/?auth=saml#b417c690-e82d-375a-ed74-484286ccfce0

SAML keystore

Create a SAML_KEYSTORE_FILE and SAML_KEYSTORE_PASS. Provided are instructions for generating a self-signed keystore.

$JAVA_HOME/bin/keytool -genkey -alias serverkeystore -keyalg RSA -keystore ./keystore

Copy keystore to SAML_KEYSTORE_FILE location and set SAML_KEYSTORE_PASS appropriately.

If using alternative certification rather than a self signed keystore, review the appropriate SSL documentation on how to create a keystore.

Ensure the alias in use is serverkeystore which matches the alias defined within the securityContext.xml file

web.xml

Modify the web.xml to enable Spring security filters. Located at ~/kxinstall/delta-bin/software/Tomcat_X_Y_Z/apache-tomcat-X.Y.Z/webapps/ROOT/WEB-INF/web.xml.

Uncomment the section titled ‘Added for SAML; uncomment’.

<!-- Added for SAML; uncomment
<filter>
    <filter-name>springSecurityFilterChain</filter-name>
    <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class>
    <async-supported>true</async-supported>
</filter>
<filter-mapping>
    <filter-name>springSecurityFilterChain</filter-name>
    <url-pattern>/*</url-pattern>    
</filter-mapping>

End added for SAML -->

You should now be ready to start the environment.

Metadata

It is necessary to update your IDP with the SP (the KX Delta Platform) metadata details to allow the SP to authorize through the IDP. This includes information include the EntityID of the SP; message encryption details and various URLs for redirection. Depending on the IDP; this may be possible by uploading the SP metadata file; available at https://<hostOfEnv>:<portOfEnv>/saml/metadata.

This provides an XML describing the SP which your IDP may accept. If the IDP does not accept an XML, it may be necessary to populate the SP configuration manually on the IDP. This data will be available in the downloaded XML. See your IDP for further details on how to configure an SP.

Login

Once setup, navigate to the base URL https://<hostOfEnv>:<portOfEnv> to login to the environment through SAML

Additional configuration

There are number of other ENV configuration values which can be set to change the SAML setup

Env Default Description
SAML_BASEURL http://${DELTAAPPSERVER_HOST}:${TOMCAT_PORT} Used for the base redirect URL post authorization with the IDP if $TOMCAT_USES_SSL is ‘0’
SAML_SECURE_BASEURL https://${DELTAAPPSERVER_HOST}:${TOMCAT_SECURE_PORT} Used for the base redirect URL post authorization with the IDP if $TOMCAT_USES_SSL is ‘1’
SAML_MAX_AUTH_AGE 28800 Max age in seconds a SAML Authorized Assertion can live
SAML_USERID_FIELDS principal The fields (csv) used by KX Delta Platform to identify the user being authorized. It can be any field provided by the IDP upon authorization
SAML_USE_EMAIL false If true then SAML principal email is used to reverse lookup userid in Control for login. Requires unique email address for users in Control. Ignored if SAML_USERID_FIELDS is not set to 'principal'.

Netscaler

If the deployment lives behind a proxy/load balancer such as a Netscaler and offers a public interface facing URL; it will be necessary to update the SAML_BASEURL/SAML_SECURE_BASEURL.

These are used by the IDP to redirect an authorization response to the correct location; in this case the public facing access URL.

Further advanced configuration of KX Delta Platform SAML configuration can be achieved by modification of the spring saml configuration file at webapps/ROOT/WEB-INF/classes/saml/securityContext.xml.

See Spring documentation on how to do so here.

SAML user management

Upon authorization by the IDP, a user may or may not exist within KX Delta Platform. KX Delta Platform offers four modes of authorization with respect to user creation and group assignment.

  • KX Delta Platform controlled user creation and group management
  • KX Delta Platform controlled user creation; IDP controlled group management
  • IDP controlled user creation; KX Delta Platform controlled group management
  • IDP controlled user creation and group management.

This is configured via the CONTROL_SSO:DEFAULT configuration parameter and IDP controlled groups assertion key. See KX Control documentation for full details.

SAML Assertion Encryption

As of version 5.0.0, the KX Delta Platform supports SAML Assertion Encryption. When enabled on the IDP, assertions returned to the Service Provider are encrypted, providing an additional layer of security for user authentication data in transit.

A dedicated decryption keystore can be configured independently of the signing keystore using the SAML_DECRYPT_KEYSTORE_* environment variables introduced in this release. Where no dedicated decryption keystore is configured, the signing keystore is used for decryption, so existing deployments require no changes to adopt this feature.

Overview

Assertion encryption requires:

  1. A dedicated encryption key pair (certificate and private key) generated on the Service Provider side.
  2. The public certificate from that key pair uploaded to the IDP so it can encrypt assertions.
  3. The private key made available to the KX Delta Platform via a JKS keystore, referenced by the SAML_DECRYPT_KEYSTORE_* environment variables.

Environment variables

The following environment variables control assertion decryption. They are optional — if omitted, the platform uses the signing keystore (SAML_KEYSTORE_*) for decryption as well.

Env Example Description
SAML_DECRYPT_KEYSTORE_FILE /path/to/enc-keystore.jks Path to the JKS keystore containing the private key used to decrypt SAML assertions. If not set, the signing keystore is used for decryption.
SAML_DECRYPT_KEYSTORE_PASS changeit Password for the SAML_DECRYPT_KEYSTORE_FILE keystore
SAML_DECRYPT_KEYSTORE_ALIAS saml-encryption Alias of the decryption key within SAML_DECRYPT_KEYSTORE_FILE

Note: SAML_KEYSTORE_FILE, SAML_KEYSTORE_PASS, and SAML_KEYSTORE_ALIAS remain mandatory. The SAML_DECRYPT_KEYSTORE_* variables are optional, but if any one is set, all three must be provided.

Generating a dedicated encryption key pair

The following steps generate a separate key pair for assertion encryption and import it into a JKS keystore.

1. Generate the key pair

openssl req -newkey rsa:2048 -nodes \
  -keyout enc-server-key.pem \
  -x509 -days 365 \
  -out enc-server-crt.pem \
  -subj "/CN=DELTA_CN"

2. Convert to PKCS12

openssl pkcs12 -export \
  -in enc-server-crt.pem \
  -inkey enc-server-key.pem \
  -out enc-keystore.p12 \
  -name saml-encryption \
  -password pass:changeit

3. Convert PKCS12 to JKS

keytool -importkeystore \
  -srckeystore enc-keystore.p12 \
  -srcstoretype PKCS12 \
  -destkeystore enc-keystore.jks \
  -deststoretype JKS \
  -alias saml-encryption \
  -storepass changeit \
  -srcstorepass changeit

This produces the following files:

File Purpose
enc-server-key.pem Private key (keep secure, not shared)
enc-server-crt.pem Public certificate — upload to IDP
enc-keystore.p12 Intermediate PKCS12 keystore
enc-keystore.jks JKS keystore referenced by SAML_DECRYPT_KEYSTORE_FILE

Configuring the IDP

The public certificate (enc-server-crt.pem) must be uploaded to the IDP so it can encrypt assertions directed at the KX Delta Platform. The exact steps vary by IDP — consult your IDP's documentation for how to upload a Service Provider certificate and enable assertion encryption.

Note: After uploading the certificate and enabling encryption in the IDP, a restart of the KX Delta Platform AppServer is required for the changes to take effect.

Configuring delta.profile

Add the following to delta.profile alongside the existing SAML_KEYSTORE_* variables:

export SAML_KEYSTORE_FILE=/path/to/keystore.jks
export SAML_KEYSTORE_PASS=changeit
export SAML_KEYSTORE_ALIAS=serverkeystore

export SAML_DECRYPT_KEYSTORE_FILE=/path/to/enc-keystore.jks
export SAML_DECRYPT_KEYSTORE_PASS=changeit
export SAML_DECRYPT_KEYSTORE_ALIAS=saml-encryption

Startup behaviour and log verification

On startup, the Tomcat log will confirm whether a dedicated decryption keystore has been loaded or whether the signing keystore is being used as a fallback.

Dedicated decryption keystore configured:

INFO  com.fd.security.Saml2Config - Loading keystore file /path/to/keystore.jks
INFO  com.fd.security.Saml2Config - Loading decryption keystore file /path/to/enc-keystore.jks

Fallback to signing keystore (no SAML_DECRYPT_KEYSTORE_* variables set):

INFO  com.fd.security.Saml2Config - Not configured to load specific keystore file for SAML decryption, will use same keystore as for signing.
INFO  com.fd.security.Saml2Config - Loading keystore file /path/to/keystore.jks

If any of the mandatory SAML_KEYSTORE_* variables are missing, the AppServer will fail to start. Check deltaError.log for messages such as:

Caused by: org.springframework.util.PlaceholderResolutionException: Could not resolve placeholder 'SAML_KEYSTORE_PASS' in value "${SAML_KEYSTORE_PASS}"