Single Sign-On Setup

Single Sign-On Setup

About this document

The purpose of this document is to describe how set up an instance of Comflow for Single Sign-On (SSO) via Microsoft Active Directory, so that the end users are able to skip the Comflow login screen since they are already signed on to the domain.

The document primarily addresses Comflow System Managers, and secondly IT administrators and Comflow developers. It is assumed that the reader has already fundamental knowledge of Comflow.

Pre-Requisites

Comflow installation has been completed, with ActiveDirectoryAuthentication as the authentication method in your sitedef.xml file:

<Authentication name="AD" class="net.comactivity.core.authentication.ActiveDirectoryAuthentication">

End users log on to their client computers with domain login, so that when they navigate into Comflow, they are already logged on to the domain.

Someone with domain administrator privileges is ready to support you in this activity

Configuration Overview

The steps of configuring Comflow for SSO are:

keytab file creation and creation of dedicated SSO user accounts

creation/modification of customer installation feature project

modification of site definition file (sitedef.xml)

Keytab File Generation and Creation of SSO Users

For each server where you want to use SSO with Comflow, you need to generate and store a keytab file. The keytab file makes it possible for Comflow to authenticate users in the background. This also requires the AD to contain one dedicated AD user account ("SSO user") for each server.

Possibly, your domain administrator will allow you to create these files yourself, but most likely you will need to ask him/her to generate files using the ktpass command as described below.

The creation of new AD users, too, probably requires you to ask your domain admin.

If you have multiple instances of Comflow on the same server, they can use the same keytab file and SSO user.

Keytab files are generated using the ktpass command from a command line. You must use an "elevated command prompt", that is: run as Administrator.

In the below examples, we generate two keytab files for two servers called "SRV12" and "SRV18" (with the full computer names "SRV12.thedomain.com" and "SRV18.thedomain.com"), both in the realm called "THEDOMAIN.COM", and the dedicated users and passwords are THEDOMAIN\user12 with password12 and THEDOMAIN\user18 with password18, respectively.

ktpass -princ HTTP/SRV12.thedomain.com@THEDOMAIN.COM -mapuser THEDOMAIN\user12 -pass password12 -crypto RC4-HMAC-NT -out SRV12.keytab -ptype KRB5_NT_PRINCIPAL -kvno 1

ktpass -princ HTTP/SRV18.thedomain.com@THEDOMAIN.COM -mapuser THEDOMAIN\user18 -pass password18 -crypto RC4-HMAC-NT -out SRV18.keytab -ptype KRB5_NT_PRINCIPAL -kvno 1

Explanation of command arguments:

-princ: the principal for which we enable single sign-on. Case-sensitive!

-mapuser: the user id of the dedicated SSO user of the principal

-pass: the password for the user passed as -mapuser

-crypto: the encryption algorithm, use value "RC4-HMAC-NT"

-out: the filename of the .keytab file that the command generates

-ptype: use value "KRB5_NT_PRINCIPAL"

-kvno: the version number of the .keytab file. If this argument is omitted, the ktpass command will increment the version number each time (the Active Directory will keep the count). But since the version number is part of the identification of the .keytab file, you cannot simply replace it by a new file if the version number has changed, so for that reason, it is more convenient to always force the version number to 1 using the -kvno argument

A more detailed documentation of the ktpass command can be found here:

https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/ktpass

Put the generated keytab file under the root folder for your Comflow installations (which is usually D:/Corzia).

Creation/Modification of a Feature Project

We will now create a "feature project" that in the end will be part of the deployed web application.

It is possible that there already exists a feature project (because you use some "features" at the customer, for example the Supply Chain Control application). In that case, you will modify the existing feature project.

Open Comflow Development Studio for the Comflow instance in which you're enabling SSO.

Create a ".config" project in the workspace by checking out and existing project of this type (for example "bjb.scana.BJB-S074.config") from repository.corzia.com ("dev" volume), disconnect it from CVS sharing and then rename it. The project name should be on the form "domain.computername.config", for example: "com.thedomain.SRV12.config".

In this project, open the file OSGI-INF/blueprint/caportal-jaas-module.xml for editing. N.B.!: rather than using the OSGI-INF/blueprint/caportal-jaas-module.xml file as it was in the project you copied, you should replace the contents with the below lines, updating it with your own values for principal (case-sensitive, exactly as generated into the keytab file) and keyTab as marked in blue below (the keyTab property is the location on the file system of the keytab file).

<?xml version="1.0" encoding="UTF-8"?>

 <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"

             xmlns:jaas="http://karaf.apache.org/xmlns/jaas/v1.0.0"

             xmlns:ext="http://aries.apache.org/blueprint/xmlns/blueprint-ext/v1.0.0">

      <!-- Bean to allow the $[karaf.base] property to be correctly resolved -->

      <!-- ext:property-placeholder placeholder-prefix="$[" placeholder-suffix="]"/ -->

      <jaas:config name="com.sun.security.jgss.accept">

          <jaas:module className="com.sun.security.auth.module.Krb5LoginModule" flags="required">

                          principal=HTTP/SRV12.thedomain.com@THEDOMAIN.COM

                                     useKeyTab=true

                                     keyTab=D:/Corzia/SRV12.keytab

                                     storeKey=true

                                     debug=false

                                     isInitiator=false

                         </jaas:module>

      </jaas:config>

      <jaas:config name="com.sun.security.jgss.initiate">

          <jaas:module className="com.sun.security.auth.module.Krb5LoginModule" flags="required">

                          principal=HTTP/SRV12.thedomain.com@THEDOMAIN.COM

                                     useKeyTab=true

                                     keyTab=D:/Corzia/SRV12.keytab

                                     storeKey=true

                                     debug=false

                                     isInitiator=false

          </jaas:module>

      </jaas:config>

 </blueprint>

Note: From late 2.16 and onwards, the property xmlns:jaas should be "karaf" as above. In earlier versions, it should be "felix". If you need the Felix variant, please get in touch with Corzia.

When you have saved your changes to the caportal-jaas-module.xml file, delete the .jar file (the one called for example com.thedomain.SRV12.config.jar in the generated folder). The development tools will immediately create a new .jar file with the same name, which contains your JAAS settings. Your .config project now looks something like this:

Now create a feature project - if you don't have one already! Its name should be on the form com.thedomain.SRV12.feature (same as the .config project but with ".feature" instead of ".config" as the last part of the project name) OR - if you run multiple Comflow instances on this server, it might be better to include the instance name in the feature project name, so that you keep the possibility open to have different features on the different instances. You create the project in the same way as you created the config project (copy from CVS, disconnect and rename).

Your feature project looks like this:

You will now establish the TurbineResources.properties file under "Configuration". Start with replacing the existing file with the one currently deployed in $approot/WEB-INF/conf. Then scroll down to "Run data services" and change the default run data service as below:

# -------------------------------------------------------------------

#

# R U N D A T A S E R V I C E

#

# -------------------------------------------------------------------

# Default implementations of base interfaces for request processing.

# Additional configurations can be defined by using other keys

# in the place of the

# -------------------------------------------------------------------

services.RunDataService.default.run.data=net.comactivity.jetspeed.services.SSORunData

Under "Docs", paste your .keytab file and commit it to CVS (just to be on the safe side).

You probably have a .bat file called SRV12_test_keytab.bat under "Docs". Open it (with Text Editor) and edit the script to fit your local server. If you have trouble setting up SSO and get in touch with Corzia support they might ask you to provide the output from running the .bat script.

The part of the .bat file that you have to change to local circumstances is just in the beginning of the file:

set JAVA_HOME=D:\Corzia\Java\jdk1.8.0_111

set JAVA_BIN=%JAVA_HOME%\bin

set ECLIPSE_HOME=D:\Corzia\eclipse\eclipse9090

set ECLIPSE_PROJECT=%ECLIPSE_HOME%\workspace\bjb.scana.BJB-S074.feature

set KRB5=%ECLIPSE_HOME%\workspace\BJBScanaPortal\Configuration\krb5.conf

set SPN=HTTP/BJB-S074.scana.bjb

set KEYTAB=%ECLIPSE_PROJECT%\Docs\BJB-S074.keytab

set TICKET_CACHE=%ECLIPSE_PROJECT%\Docs\BJB-S074_ticket_cache

set _JAVA_OPTIONS=-Djava.security.krb5.debug=false -Djava.security.krb5.conf=%KRB5%

Then run the script. To run it, use the right-click option "Open with System Editor". This will, if successful, place a new "_ticket_cache" file under Docs (don't forget to Refresh the Docs folder in order to see it).

Now copy the .config.jar file into your feature project, into /PrivateRoot/osgi_features/bundles . Then edit the .features file under /PrivateRoot/osgi_features so that it points at the .config.jar file.

Then commit the feature project to CVS and change your deploy script so that it includes the feature project, because it must be deployed. (The .config project however does not need to be deployed and you could close it (or even remove it from your workspace) after you have committed it to CVS.

If you use the same deploy script for several instances on different servers, you can include the feature projects of all servers in the deploy script. The feature projects that don't apply to a given server should not be present in the workspace and thus will not be deployed, but even if they were, it does not matter, because the sitedef.xml is in control of what feature applies run-time.

Add Properties to sitedef.xml

Under <Site><ServerInfo><Authentication> for the ActiveDirectoryAuthentication,  add the property

<parameter name="sso.enabled" value="true"/>

<parameter name="sso.check.group.enabled" value="false"/>

 <parameter name="sso.group" value=""/>

Under <Site><ServerInfo><Properties> add the property

<Property name="osgi.features.install" value="bjb.scana.BJB-S074:1.0.0" />

 where the value will be matched to the feature name and version as stated in the .features file:

<?xml version="1.0" encoding="UTF-8"?>

 <features name="BJB-S074">

      <feature name="bjb.scana.BJB-S074" version="1.0.0">

          <bundle>cabundle:bjb.scana.BJB-S074.config.jar</bundle>

      </feature>

 </features>

If there is already a value for the property osgi.features.install, don't replace the existing value, instead add it to the current value separated by one space.

If you have multiple Comflow instances on the same server you need to change each instance's sitedef.xml but both can point to the same keytab file.