Configuring Single Sign On to the Percussion CMS

As of Version 4.3, Percussion supports SAML authentication in support of single sign-on. By establishing an Apache/Shibboleth proxy in front of CM1, users attempting to access the Content Management system can first be authenticated using an Identify Provider application.  

Benefits of using single sign-on include:

  • Reducing password fatigue from different user name and password combinations
  • Reducing time spent re-entering passwords for the same identity
  • Reducing IT costs due to lower number of IT help desk calls about passwords

Note: This document contains the following assumptions:

  • Customer has an Identity Provider in place (IdP).
  • Customer has a good understanding of how they configure other service providers (SP) using SSO and unsolicited SSO.
  • Customer knows how to configure their firewalls to allow access to specific ports such as Apache’s default port 80.
  • CM1 is NOT co-located with DTS (we lockdown CM1 due to the Apache config)

Pre-Install Setup:

  1. Install CM1 (Note that DTS cannot be co-located with CM1 due to security issues)
  2. Run CM1 and verify that you can log in.
    Note: You may want to create a user with the same credentials as one stored in your IdP so that you may add users via CM1 with that user later.
  3. Shutdown CM1

Install Apache:

  1. Install the Apache package on the same server CM1 is installed: yum install httpd
    You can check the package version with the following command: yum -v list httpd
  2. Start Apache: service httpd start
  3. Confirm access through apache on port 80 by opening a web browser and going to http://<Your_HOST_NAME>:80 where you should be able to view the Apache landing page.
    1. Note: You may need to modify your local systems hosts file before reaching the server.
    2. Note: You may also need to open port 80 in your firewall before being able to access Apache.
  4. Once you have confirmed that you can reach Apache, shut it down with the following command: service httpd stop

Configure Apache Proxy:

  1. In CM1 change the server.xml (/<INSTALL_DIRECTORY>/Appserver/server/rx/deploy/jboss-web.deployer/server.xml) to contain the redirect port in the AJP <connector> element to have 9992 instead of 8443. maxThreads set to 250x number of processors.

    Example:<Connector address="${jboss.bind.address}" emptySessionPath="true" enableLookups="false" port="9998" protocol="AJP/1.3" redirectPort="9992" maxThreads=”500”/>

  2. Allow persistent outbound connections if you are on RHEL: /usr/sbin/setsebool -P httpd_can_network_connect 1
  3. Change permissions on the Apache error log: chmod 755 /etc/httpd/logs/error_log
  4. Configure the httpd.conf (/etc/httpd/conf/httpd.conf) Apache configuration file:
    1. Change permissions for the httpd.conf file if needed in order to edit 
    2. Uncomment the line NameVirtualHost *:80
    3. Uncomment the line LoadModule filter_module modules/mod_filter.so
    4. Add a virtual host (or replace the template one) to look like such, where <VHOST_NAME> (example: samltest.com) is a name of your choice:
<VirtualHost *:80>
ServerName <VHOST_NAME>
DocumentRoot "/var/www/html/CM1"
ErrorLog "/etc/httpd/logs/error_log"
TransferLog "/etc/httpd/logs/access_log"
ProxyRequests Off
RewriteEngine On
ProxyPreserveHost On
UseCanonicalName On
#RHYTHMYX
ProxyPass /Rhythmyx ajp://127.0.0.1:9998/Rhythmyx
#Apache Defaults to port 80
ProxyPassReverse /Rhythmyx http://%{SERVER_NAME}/Rhythmyx
#CM
ProxyPass /cm ajp://127.0.0.1:9998/cm
ProxyPassReverse /cm http://%{SERVER_NAME}/cm
#Assets
ProxyPass /Assets ajp://127.0.0.1:9998/Assets
ProxyPassReverse /Assets http://%{SERVER_NAME}/Assets
#Web Resources
ProxyPass /web_resources ajp://127.0.0.1:9998/web_resources
ProxyPassReverse /web_resources http://%{SERVER_NAME}/web_resources
#Rhythmyx Web Resources
ProxyPass /Rhythmyx/web_resources ajp://127.0.0.1:9998/Rhythmyx/web_resources
ProxyPassReverse /Rhythmyx/web_resources http://%{SERVER_NAME}/Rhythmyx/web_resources
#sites
ProxyPass /sites ajp://127.0.0.1:9998/sites
ProxyPassReverse /sites http://%{SERVER_NAME}/sites
#Sites
ProxyPass /Sites ajp://127.0.0.1:9998/Sites
ProxyPassReverse /Sites http://%{SERVER_NAME}/Sites

#Redirect Root to /cm/
#Redirect / /cm/
#Rewrite all content links to the correct port
FilterDeclare DN_REPLACE_URLS
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $text/
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/html
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/xml
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/json
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/javascript
FilterChain DN_REPLACE_URLS
#Substitution for links coverage example: "http(s)://xstring:9992"
Substitute "s|(https?://)([a-z0-9.]+):9992|$1$2|i"
</VirtualHost>

  1. Restart Apache: service httpd restart

Test Apache Proxy Configuration

Test the Apache configuration before moving to installing Shibboleth.

  1. Login to CM1 via the <VHOST_NAME>:80 you specified above. (Make sure your host file on the machine you're testing on points to the <VHOST_NAME>.
  2. Content should show up as it did when you installed CM1.
  3. To secure this environment you will want to close the port 9992 on the server and open port 80

Configure CM1 For Shibboleth

  1. In /home/CM1/Percussion/rxconfig/Server/ backup the config.xml: cp config.xml config.bak
  2. Edit the config.xml that you just backed up by removing the following lines:
<PSXSecurityProviderInstance id="0" type="BackEndTable">
<name>rxmaster</name>
<Properties>
<datasourceName/>
<uidColumn>USERID</uidColumn>
<tableName>USERLOGIN</tableName>
<passwordFilter>Java/global/percussion/filter/sys_DefaultPasswordFilter</passwordFilter>
<passwordColumn>PASSWORD</passwordColumn>
</Properties>
</PSXSecurityProviderInstance>

  1. Edit the config.xml again to contain a new security provider in the place of the one previously deleted between the <securityProviders> and </securityProviders> tags. Please note that the <AuthenticatedUserHeader> value will vary based upon what attribute provided from the IdP you would like to authenticate your user against. In this example the IdP passes the eppn field which results in a string (username@idpdomain.org)
<PSXSecurityProviderInstance id="0" type="WebServer">
<name>Web Server</name>
<Properties>
<RoleListDelimiter>;</RoleListDelimiter>
<AuthenticatedUserHeader>eppn</AuthenticatedUserHeader>
<UserRoleListHeader>RxUserRoles</UserRoleListHeader>
</Properties>
</PSXSecurityProviderInstance>

  1. Edit server.xml in /home/CM1/Percussion/AppServer/server/rx/deploy/jboss-web.deployer/ to contain the following in the <Connector> element:

    tomcatAuthentication=”false”

    Example: <Connector address="${jboss.bind.address}" emptySessionPath="true" enableLookups="false" port="9998" tomcatAuthentication="false" protocol="AJP/1.3" redirectPort="9992"/> 

Configure Apache for Shibboleth:

  1. If you have a virtual host (<VirtualHost *:80> and </VirtualHost>) set up at the bottom of the httpd.conf file found in /etc/httpd/conf/httpd.conf delete it or comment it out along with the following lines if they exist:
    • # ServerName rhel65saml.percussion.local
    • # DocumentRoot "/var/www/html/CM1"
    • # ErrorLog "/etc/httpd/logs/error_log"
    • # TransferLog "/etc/httpd/logs/access_log"
  2. Edit the httpd.conf file by uncommenting the line ServerName www.example.com:80 to contain the name you would like the server to be. This is the address you will access CM1 on. 
  3. In httpd.conf uncomment the line below the ServerName and make sure it is set to on: UseCanonicalName On.
  4. Edit the file to contain the following at the bottom of the conf file where you previously made changes for the Apache proxy configuration. Note some of these lines may be similar to the proxy configuration however it is recommended to overwrite all of those lines with the following:
ProxyRequests Off
RewriteEngine On
ProxyPreserveHost On
#UseCanonicalName On
RequestHeader set AUTH-TYPE "shibboleth"
<Location /Rhythmyx>
#Authorize through Shibboleth
AuthType shibboleth
ShibCompatWith24 On
ShibUseHeaders On
ShibRequestSetting requireSession 1
require valid-user
RequestHeader set Shib-Spoof-Check "SPK349919353920"
</Location>

<Location /cm>
#Authorize through Shibboleth
AuthType shibboleth
ShibCompatWith24 On
ShibUseHeaders On
ShibRequestSetting requireSession 1
require valid-user
RequestHeader set Shib-Spoof-Check "SPK349919353920"
</Location>
<Location /Assets>
#Authorize through Shibboleth
AuthType shibboleth
ShibCompatWith24 On
ShibUseHeaders On
ShibRequestSetting requireSession 1
require valid-user
RequestHeader set Shib-Spoof-Check "SPK349919353920"
</Location>
<Location /web_resources>
#Authorize through Shibboleth
AuthType shibboleth
ShibCompatWith24 On
ShibUseHeaders On
ShibRequestSetting requireSession 1
require valid-user
RequestHeader set Shib-Spoof-Check "SPK349919353920"
</Location>
<Location /Rhythmyx/web_resources>
#Authorize through Shibboleth
AuthType shibboleth
ShibCompatWith24 On
ShibUseHeaders On
ShibRequestSetting requireSession 1
require valid-user
RequestHeader set Shib-Spoof-Check "SPK349919353920"
</Location>
<Location /sites>
#Authorize through Shibboleth
AuthType shibboleth
ShibCompatWith24 On
ShibUseHeaders On
ShibRequestSetting requireSession 1
require valid-user
RequestHeader set Shib-Spoof-Check "SPK349919353920"
</Location>
#RHYTHMYX
ProxyPass /Rhythmyx ajp://127.0.0.1:9998/Rhythmyx
#Apache Defaults to port 80
ProxyPassReverse /Rhythmyx https://%{SERVER_NAME}/Rhythmyx

#CM
ProxyPass /cm ajp://127.0.0.1:9998/cm
#Apache Defaults to port 80
ProxyPassReverse /cm https://%{SERVER_NAME}/cm
#Assets
ProxyPass /Assets ajp://127.0.0.1:9998/Assets
ProxyPassReverse /Assets https://%{SERVER_NAME}/Assets

#Web Resources
ProxyPass /web_resources ajp://127.0.0.1:9998/web_resources
ProxyPassReverse /web_resources https://%{SERVER_NAME}/web_resources
#Rhythmyx Web Resources
ProxyPass /Rhythmyx/web_resources ajp://127.0.0.1:9998/Rhythmyx/web_resources
ProxyPassReverse /Rhythmyx/web_resources https://%{SERVER_NAME}/Rhythmyx/web_resources
#Sites
ProxyPass /Sites ajp://127.0.0.1:9998/Sites
ProxyPassReverse /Sites https://%{SERVER_NAME}/Sites
#Redirect Root to /cm/
RedirectMatch ^/$ /cm/
#Rewrite all content links to the correct port
FilterDeclare DN_REPLACE_URLS
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $text/
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/html
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/xml
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/json
FilterProvider DN_REPLACE_URLS SUBSTITUTE resp=Content-Type $/javascript
FilterChain DN_REPLACE_URLS
#Substitution for links coverage example: "http(s)://xstring:9992"
Substitute "s|(https?://)([a-z0-9.]+):9992|$1$2|i"


Please note that the spoofing key provided in can be changed to a key you desire.

Install and Configure Shibboleth:

  1. Shibboleth does not support SELinux please disable before installing by editing the /etc/selinux/config and change the line SELINUX=enforcing to SELINUX=disabled
  2. Install shibboleth from yum: yum install shibboleth.x86_64
    1. If you receive an error such as: no package shibboleth available you must add the shibboleth repo to your server: 
    2. cd /etc/yum.repos.d
    3. Create the repo file: touch shibboleth.repo
    4. Add the following lines to the repo file:
      [security_shibboleth]
      name=Shibboleth (RHEL_6)
      type=rpm-md
      baseurl=http://download.opensuse.org/repositories/security:/shibboleth/RHEL_6/
      gpgcheck=1
      gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/RHEL_6/repodata/repomd.xml.key
      enabled=1
    5. Attempt to install shibboleth.x86_64 again.
  3. Install mod_ssl so that Apache may support ssl connections: yum install mod_ssl
  4. In /etc/shibboleth/ edit the shibboleth2.xml in the <ApplicationDefaults> element change the entityID to be the hostname of your box.
    entityID="https://RHEL65SAML.percussion.local/shibboleth"
  5. In the shibboleth2.xml in the <SSO> element change the entityID field to be the IdP URL:
    https://<IdP_URL>/idp/shibboleth
    Example: https://idp.testshib.org/idp/shibboleth
  6. In the same shibboleth2.xml file edit the <Sessions> element and change the field handlerSSL field to look like this:
    handlerSSL=”true”
  7. In the shibboleth2.xml you will need to configure the <MetadataProvider element to point to your IdP. Note we are not implementing Metadata Filters:
    For example:
    <MetadataProvider type="XML" uri="http://www.testshib.org/metadata/testshib-providers.xml"
    backingFilePath="testshib-two-idp-metadata.xml" reloadInterval="180000" />
  8. Start shibboleth:
    service httpd restart
    service shibd start
  9. You must now upload your metadata to your IdP (this may change based on how your IdP is configured). You can access your metadata by going to:
    https://<SERVER_NAME>/Shibboleth.sso/Metadata
    Where <SERVER_NAME> is the name you chose in the Apache config for ServerName.

You should now be ready to utilize SSO

SSO Troubleshooting

Connection to IdP

If you find that you are having trouble connecting to the IdP check that the generated metadata HTTP-POST urls are exactly the same ServerName used in the httpd.conf. This document is case sensitive!

Cannot connect to ServerName given in httpd.conf

If you cannot connect to anything through a browser to the ServerName you gave in httpd.conf, you may want to check your local hosts file to direct your browser to the correct Server Name.

Cannot authorize against CM1

If you attempt to go through shibboleth and log in via the IdP and cannot connect to CM1, you may want to check your config.xml. This may happen upon upgrade of CM1 which may overwrite configuration changes in config.xml. Compare config.xml (/<CM!_DIRECTORY>/rxconfig/Server/config.xml) with the changes to the file in the SAML directions.

Leave a comment

*
*