As of 4.1.0, the 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.
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 a number of ENV variables to be set before starting up the environment.
|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|
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
- Provide unique
- 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 can be used to redirect SAML users to a default dashboard once logged in.
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
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
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 should now be ready to start the environment.
It is necessary to update your IDP with the SP (the 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://
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.
Once setup, navigate to the base URL
https://<hostOfEnv>:<portOfEnv> to login to the environment through SAML
There are number of other ENV configuration values which can be set to change the SAML setup
||Used for the base redirect URL post authorization with the IDP if $TOMCAT_USES_SSL is ‘0’|
||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 the platform to identify the user being authorized. It can be any field provided by the IDP upon authorization|
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
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
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 the platform. The Platform offers four modes of authorisation 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.