Skip to main content
Kinetic Community

Configuring SAML Support

Overview

This is a step-by-step guide on configuring SAML authentication support in Kinetic Request CE.

Details

  1. Enable Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files
    1. Go to the download page and download the relevant files.
    2. Install them as directed by the README.txt into the JRE used by Tomcat.
  2. Configure Tomcat to use SSL (optional if an SSL-enabled proxy or load-balancer is between the IDP and Tomcat):
    1. Copy cacerts to $TOMCAT_HOME/conf as "keystore.jks":
      1. cp $JAVA_HOME/lib/security/cacerts $TOMCAT_HOME/conf/keystore.jks
    2. Change keystore.jks password:
      1. keytool -storepasswd -new <keystorepass> -storepass changeit -keystore $TOMCAT_HOME/conf/keystore.jks
    3. Import your CA Certificate (optional if using a global CA, required if using an internal CA such as Active Directory):
      1. Retrieve a Base64 encoded certificate for your CA, e.g. mydomain.cer
      2. keytool -import -alias mydomainCA -file <certificate-file.cer> -trustcacerts -keystore $TOMCAT_HOME/conf/keystore.jks -storepass <keystorepass> -noprompt
    4. Generate a new SSL Certificate Request:
      1. Decide on an alias, e.g. acme. Use that in place of <server-alias>
      2. keytool -genkey -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -alias <server-alias> -storepass <keystorepass> -keystore $TOMCAT_HOME/conf/keystore.jks
    5. Submit your certificate request to your Certificate Authority and get a Base64 encoded certificate back.
    6. Import your signed certificate:
      1. keytool -import -alias <server-alias> -file <server-cert.cer> -keystore $TOMCAT_HOME/conf/keystore.jks -storepass <keystorepass>
    7. Enable the SSL Connector:
      1. Edit the $TOMCAT_HOME/conf/server.xml file.
      2. Edit the existing 8443 connect or add a new one as seen below:
      3. <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
                       maxThreads="150" SSLEnabled="true" scheme="https" secure="true"
                       clientAuth="false" sslProtocol="TLS"
                       keystoreFile="conf/keystore.jks" keystorePass="<keystorepass>" keyAlias="<server-alias>" />
  3. Configure Tomcat to use a proxy port and scheme IF you're off-loading SSL from tomcat. For example, you skipped Step 2 (Configure Tomcat to use SSL) but your implementation still uses SSL. This step is necessary to make the IDP Authentication Response message Destination attribute match exactly the SSL URL you specify later in step 5.4. If you skip this step you may run into the following error in your application.log file:
    SAML message intended destination endpoint 'https://ce.acme.com/kinetic/space-slug/app/saml/SSO/alias/space-slug' did not match the recipient endpoint 'http://ce.acme.com:443/kinetic/space-slug/app/saml/SSO/alias/space-slug'
    
     
    1. IMPORTANT NOTE: Be sure when doing this that the proper network routing and firewall rules are set so end users cannot access the server directly on the specified port and that they're forced to route through the load balancer or reverse proxy. This is important from a security perspective as Tomcat will assume all of the traffic going through this port is secured.
    2. Edit the $TOMCAT_HOME/conf/server.xml file:
    3. Edit the the Connector that your load balancer / reserve proxy forwards to and add: secure="true" scheme="https" proxyPort="443". See the example below:
    4. <Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
                     maxThreads="150" 
                     scheme="https" 
                     secure="true"
                     proxyPort="443"
       />
  4. Configure Kinetic Request CE System
    1. Change to your Request CE Data Directory (default is $TOMCAT_HOME/webapps/kinetic/WEB-INF/config/)
    2. Open the security.properties file in a text editor
    3. Configure your Request CE keystore:
      1. (optional) Change the keystore password:
        1. keytool -storepasswd -new <keystorepass> -storepass changeit -keystore ./keystore.jks
      2. NB: This keystore is in your data directory - not the Tomcat config directory.
      3. In security.properties:
        1. Uncomment and set security.keystore.path and security.keystore.password.
        2. Uncomment security.keystore.defaultKey.
      4. Enable the SAML Security Strategy:
        1. In security.properties uncomment the line containing the SamlSecurityStrategy.class to enable it.
  5. Configure your Kinetic Request CE Space
    1. Copy security.SPACESLUG.properties-example to security.<spaceslug>.properties, e.g. security.acme.properties
    2. Enable SAML for the space by uncommenting security.saml.enabled
    3. (optional) Uncomment and configure your SAML attribute mapping.
      1. NB: You will need to know what attribute name will be mapping "email" and "displayName" in order to configure this.
    4. Configure your Service Provider:
      1. Uncomment security.saml.sp.url and set it. It must end with the "app" path location and no trailing slash. Example: https://request.mycompany.com/kinetic/mycompany/app
        1. NOTE: This URL is the basis for your SP Metadata URL. Your IdP administrator will need this URL to properly add this site as a trusted service provider. Example: https://request.mycompany.com/kinetic/mycompany/app/saml/metadata/alias/mycompany
      2. (optional) Override the Space's Service Provider Entity ID by uncommenting and setting security.saml.sp.entityid. This is useful if you have multiple environments connecting to the same IDP.
    5. Configure your IDP(s)
      1. Uncomment security.saml.providers and give your IDP a key, e.g. "adfs"
      2. Determine how you will provider Kinetic Request CE your IDP metadata: HTTP or File-based.
      3. Create a provider configuration, copy one of the two examples and change the settings as appropriate:
        1. security.saml.idp.adfs.name=Active Directory
          security.saml.idp.adfs.type=url
          security.saml.idp.adfs.url=https://my-adfs.acme.com/sso/saml/metadata
  6. (optional) Customize the Space login.jsp. 
Configuring LDAP Support
How to set up Request CE to authenticate set up users against an LDAP system instead of the local password store.
Configuring X509 Certificate Support
Instructions for setting up X509/CAC support for the Kinetic Request CE application.
Kinetic Core Security Configuration