This is a step-by-step guide on configuring SAML authentication support in Kinetic Core version 2. For version 5, please contact [email protected]

Details

1. Enable Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files

   • Go to the download page and download the relevant files.
   • 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):

   • Copy cacerts to $TOMCAT_HOME/conf as "keystore.jks":
     cp $JAVA_HOME/lib/security/cacerts $TOMCAT_HOME/conf/keystore.jks
   • Change keystore.jks password:
     keytool -storepasswd -new <keystorepass> -storepass changeit -keystore $TOMCAT_HOME/conf/keystore.jks
   • Import your CA Certificate (optional if using a global CA, required if using an internal CA such as Active Directory):
   • Retrieve a Base64 encoded certificate for your CA, e.g. mydomain.cer
     keytool -import -alias mydomainCA -file <certificate-file.cer> -trustcacerts -keystore $TOMCAT_HOME/conf/keystore.jks -storepass <keystorepass> -noprompt
   • Generate a new SSL Certificate Request:
     • Decide on an alias, e.g. acme. Use that in place of
       keytool -genkey -keyalg RSA -keysize 2048 -sigalg SHA256withRSA -alias <server-alias> -storepass <keystorepass> -keystore $TOMCAT_HOME/conf/keystore.jks
   • Submit your certificate request to your Certificate Authority and get a Base64 encoded certificate back.
   • Import your signed certificate:
     keytool -import -alias <server-alias> -file <server-cert.cer> -keystore $TOMCAT_HOME/conf/keystore.jks -storepass <keystorepass>
   • Enable the SSL Connector:
     - Edit the $TOMCAT_HOME/conf/server.xml file.
     - Edit the existing 8443 connect or add a new one as seen below:
     <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'

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.
- Edit the $TOMCAT_HOME/conf/server.xml file:
- Edit the the Connector that your load balancer / reserve proxy forwards to and add: secure="true" scheme="https" proxyPort="443". See the example below:

<Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol" maxThreads="150" scheme="https" secure="true" proxyPort="443" />

4. Configure Kinetic Request CE System

   • Change to your Request CE Data Directory (default is $TOMCAT_HOME/webapps/kinetic/WEB-INF/config/)
   • Open the security.properties file in a text editor
   • Configure your Request CE keystore:
     • (optional) Change the keystore password:
       keytool -storepasswd -new <keystorepass> -storepass changeit -keystore ./keystore.jks
     • NB: This keystore is in your data directory - not the Tomcat config directory.
     • In security.properties:
       • Uncomment and set security.keystore.path and security.keystore.password.
       • Uncomment security.keystore.defaultKey.
     • Enable the SAML Security Strategy:
       • In security.properties uncomment the line containing the SamlSecurityStrategy.class to enable it.

5. Configure your Kinetic Request CE Space

   • Copy security.SPACESLUG.properties-example to security.<spaceslug>.properties, e.g. security.acme.properties
   • Enable SAML for the space by uncommenting security.saml.enabled
   • (optional) Uncomment and configure your SAML attribute mapping.
     • NB: You will need to know what attribute name will be mapping "email" and "displayName" in order to configure this.
   • Configure your Service Provider:
     • 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
     • 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
   • (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.

6. Configure your IDP(s)

   - Uncomment *security.saml.providers* and give your IDP a key, e.g. "adfs"
   - Determine how you will provider Kinetic Request CE your IDP metadata: HTTP or File-based.
   - Create a provider configuration, copy one of the two examples and change the settings as appropriate:
   

   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

7. (optional) Customize the Space login.jsp.