Skip to content

SAML workflow

From version 4.1.0, KX Platform supports Single Sign On (SSO) via Security Assertion Markup Language (SAML).

The SSO procedure authenticates a user’s credentials by way of a third-party Identity Provider (IDP). This is done through an exchange of digitally-signed XML documents.

Logging in

To log in using SSO, navigate to the base URL (https://server:port), where a global platform sign-in option is available.

Screenshot

Clicking Sign in redirects you to the IDP. Once authorization is complete, the KX application suite becomes available.

Screenshot

From here it is possible to navigate to any permissioned application without the need for a further sign in.

Logging in using Service Provider (SP) authentication is still supported. The URL for the individual application (e.g. https://server:port/control) will display the classic SP login splash.

Logging out

Logging out can be done via either the IDP or the SP.

To configure logging out: from the user-administration dropdown select Global Logout for the IDP; Local Logout for the SP.

Screenshot

SSO user and group configuration

User creation and group assignment can be controllled via the Platform or a 3rd party IDP. It is necessary to ensure the configuration in both the KX Platform and the 3rd party IDP is compatible with valid to ensure when users authenticate, the KX Platform can appropriately assign the necessary permissions with respect to the group information provided in the IDP SAML Assertion.

To this end there are four supported KX Platform user & group configuration options

Platform controlled user creation and group assignment

Authentication is offloaded to 3rd party IDP, but user and group assignment are still managed within the KX Platform.

To enable this mode

  • CONTROL_SSO:DEFAULT config parameter should set the value createUser to false
  • The IDP must not provide a groups key in the SAML assertion.

Additional considerations

  • Users must be pre-created in the KX Platform (as user/auth type SAML).
  • Groups are assigned manually within the KX Platform.
  • A users group assignment will not be affected by the configuration in CONTROL_SSO:DEFAULT config parameter

Screenshot

Platform controlled user creation; IDP controlled group assignment

Authentication and group management is offloaded to 3rd party IDP, but user creation is managed within KX Platform.

To enable this mode

  • CONTROL_SSO:DEFAULT config parameter should set the parameter createUser to false
  • The IDP should provide a groups key in the SAML assertion containing group information. See IDP group configuration for acceptable group formats

Additional considerations

  • User should be pre-created in the Platform
  • User Groups are provided in the IDP SAML assertion and those in the CONTROL_SSO:DEFAULT config parameter

Screenshot

IDP controlled user creation; Platform controlled group assignment

Authentication and user creation is offloaded to 3rd party IDP, but group assignment is managed with KX Platform.

To enable this mode

  • CONTROL_SSO:DEFAULT config parameter should set the value createUser to true
  • The IDP must not provide a groups key in the SAML assertion.

Additional considerations

  • Users may or may not already exist within the deploy
  • Groups are assigned to those in CONTROL_SSO:DEFAULT on user creation
  • Subsequent changes to the CONTROL_SSO:DEFAULT have no affect to user group settings

Screenshot

IDP controlled user creation and group assignment

Authentication, user creation an group assignment is offloaded to 3rd party IDP.

To enable this mode

  • CONTROL_SSO:DEFAULT config parameter should set the value createUser to true
  • The IDP SAML assertion should provide a groups key for groups a user is a member of. This will update for each subsequent login to the KX Platform.

Additional considerations

  • Users may or may not already exist within the deploy
  • Groups are assigned to those in the SAML assertion IDP group configuration and those in CONTROL_SSO:DEFAULT groups key config parameter
  • Any modifications are picked up on next login

SAML assertion groups key

By default the groups key expected within the SAML assertion is groups. This can be modified by updating the CONTROL_SSO:DEFAULT config parameter to include a key 'groupsKey' with the value which should be used for obtaining user group information from the SAML Assertion.

SAML custom group information parsing

By default the KX Platform supports groups formatted as a CSV in a single groups attribute, or as a multi-attribute child value set. If further structures need to be supported, this can be provided via a custom analytic hook. To do so a custom q process is needed to parse to the SAML assertion.

To configure custom assertion parsing

  • Edit the ${DELTA_WEBAPPS}/ROOT/WEB-INF/classes/saml/securityContext.xml. Update the samlAuthenticationProvider bean by uncommenting the customAssertionParse property, setting to true. Set the xmlParseConnection property to the instance/connection group to do the parsing, and finally set xmlParseAnalytic as the analytic to do the xml parsing. This analytic will receive the xml SAML assertion to parse out the group information as required.
  • This process must return a dict with with the required groups information. By default this key is groups, but can be customized see IDP group configuration for further info. The value should be a string list containing groups information for the associated user.
  • A bounce of the KX Platform is required pick up changes.

Deployment

Full details on how to deploy an SSO environment can be found in the KX Platform Deployment Guide, Appendix G.

SSO users

For SSO users authentication is offloaded to 3rd party IDP. In KX Control therefore while the Authentication & Access Control tab will be available to be seen, all of the fields will be disabled for these users.

Screenshot

Back to top