Skip to content

SAML authentication

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

Enabling SAML – install

As of Platform version 4.6.0, SAML can be automatically configured using Install Options. See (SAML Install Options)[install_config_options.md#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>

SPRING_PROFILES_ACTIVE=saml
APPSERVER_SPLASHPAGE=saml/index.jsp

Enabling SAML – post-deploy

SAML can be enabled post-deploy. It requires requires some environment variables to be set before starting up the environment.

variable 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 Platform (Service Provider) to the Identity Provider (IDP). See IDP documentation for specific limitations
SAML_IDP_METADATA_FILE 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 the platform
SAML_KEYSTORE_FILE Encrypted TLS communication between an SP and IDP. Any valid keystore can be used. Default alias is serverkeystore. See securityContext.xml to modify
SAML_KEYSTORE_PASS Password for the SAML_KEYSTORE_FILE file above
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 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.

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. To generat 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 and 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>
    <async-supported>true</async-supported>
</filter-mapping>

End added for SAML -->

You are now ready to start the environment.

Metadata

Update your IDP with the SP (the Platform) metadata details to allow the SP to authorize through the IDP. This includes 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.

Log in

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

Additional configuration

SAML_BASEURL

Used for the base redirect URL post-authorization with the IDP if TOMCAT_USES_SSL is 0.

Default: http://${DELTAAPPSERVER_HOST}:${TOMCAT_PORT}

SAML_SECURE_BASEURL

Used for the base redirect URL post-authorization with the IDP if TOMCAT_USES_SSL is 1

Default: https://${DELTAAPPSERVER_HOST}:${TOMCAT_SECURE_PORT}

SAML_MAX_AUTH_AGE

Max age in seconds a SAML Authorized Assertion can live

Default: 28800

SAML_USERID_FIELDS

The fields (CSV) used by the platform to identify the user being authorized. Can be any field provided by the IDP upon authorization.

Default: 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 the Platform SAML configuration can be achieved by modification of the spring SAML configuration file at webapps/ROOT/WEB-INF/classes/saml/securityContext.xml.

Spring documentation

SAML user management

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

  • Platform-controlled user creation and group management
  • Platform-controlled user creation; IDP-controlled group management
  • IDP-controlled user creation; 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.