/
Configuring DDF with WSS using standalone authentication servers.

Configuring DDF with WSS using standalone authentication servers.

Owned by Alexander Lamar (Unlicensed)
Last updated: Aug 16, 2013Version comment

DDF uses CAS as its single sign-on service, and LDAP and STS to keep track of users and user attributes. CAS, LDAP, and STS are integral, interconnected components of the DDF security scheme, and all can be installed on a local DDF instance with only a few feature installs (with the exception of the CAS installation, which requires Apache Tomcat to run). Setting up these authentication components to run externally, however, is a little more nuanced, so this page will provide step-by-step instructions detailing the configuration process.

This document assumes that you have a keystore for each of the services / servers. If you are using different keystore names, substitute the name in this document with the desired name for your setup. For this document, the following is used:

ServerKeystore FileComments
CASkeystore.jksUsed on the CAS Tomcat server.
STSstsKeystore.jksUsed to sign SAML and also as incoming connections
DDF

serverKeystore.jks

clientKeystore.jks

Server used for incoming connections

Client used for outgoing connections

Figure 1: Login Authentication Scheme

Distributed WSS.pptx

Configuring CAS, LDAP, and STS

It is implied that the three authentication components below will be installed onto three separate servers, and as such it is important to keep track of the DNS hostnames used in each for certificate authentication purposes.

LDAP

LDAP is used to maintain a list of trusted DDF users and the attributes associated with them. It interacts with both CAS and the STS: the former uses LDAP to create session information, and the later queries LDAP for user attributes and converts them to SAML Claims.

  1. Obtain and unzip the DDF Kernel (ddf-distribution-kernel-<VERSION>.zip). 
  2. Start the distribution.
  3. Deploy the Embedded LDAP App by copying the ldap-embedded-app-<VERSION>.kar into the <DISTRIBUTION_HOME>/deploy directory. You can verify that the ldap server is installed by checking the DDF log or by performing an la command and verifying that the OpenDJ bundle is in the Active state. Additionally, it should be responding to LDAP requests on the default ports, 1389 and 1636.
  4. Copy your environment's Java Keystore File into the ${DISTRIBUTION}/etc/keystores folder, making sure it overwrites the folder's existing serverKeystore.jks file.

 

It is very important that the keystore file used in the process is set up to trust the hostnames used by CAS and STS, or else the user will run into certificate authentication issues.

 

CAS

CAS is used for SSO authentication purposes. Unlike LDAP and STS, CAS can not be run as a DDF bundle and instead must be run through Apache Tomcat.

  1. Follow the instructions on the CAS installation page in order to get Tomcat/CAS installed and configured (like with LDAP above, the keystore.jks file used must trust the hostnames used by the STS server, LDAP server, and the DDF user connecting to CAS).
  2. Open the ${TOMCAT}/webapps/cas/WEB-INF/cas.properties file and modify the cas.ldap.host, cas.ldap.port, cas.ldap.user.dn, and cas.ldap.password fields with your environment's LDAP information.

 

STS

The Security Token Service, unlike the LDAP, cannot currently be installed on a kernel distribution of DDF. To run a STS-only DDF installation, you can uninstall the catalog components that are not being used in order to increase performance. A list of unneeded components can be found on the STS page.

  1. In the unzipped DDF distribution folder, open /etc/org.ops4j.pax.web.cfg and find the line

    org.ops4j.pax.web.ssl.keystore=etc/keystores/serverKeystore.jks

    and change it to: 

    org.ops4j.pax.web.ssl.keystore=etc/keystores/stsKeystore.jks

    Update the password fields to the ones your keystore uses, as well.

  2. Verify that the stsKeystores.jks file in /etc/keystores trusts the hostnames used in your environment (the hostnames of LDAP, CAS, and any DDF users that make use of this STS server). 
  3. Start the distribution.

  4. Enter the following commands to install the features used by the STS server.

    features:install security-sts-server
features:install security-cas-tokenvalidator
  5. Open up the DDF web console as an administrator (default is admin/admin) and navigate to the Configuration tab.
  6. Open up the Security STS LDAP Login configuration, and make sure the LDAP URL, LDAP Bind User DN, and LDAP Bind User Password fields match your LDAP server's information (the default DDF LDAP username/password is cn=user / secret . In a production environment, the username and password should be changed in the LDAP data file). Hit save.
  7. Open up the Security STS LDAP and Roles Claims Handler configuration and populate the same url, user, and password fields with your LDAP server information. Hit save.
  8. Open up the Security STS CAS Token Validator configuration. Under CAS Server URL, put the URL to your CAS server. Hit save.
  9. Open up Platform Global Configuration. Change the protocol to https. Populate the host/port information with the STS server's host/port (for STS, the default port is 8993). Update the Trust Store and Key Store location/password fields with your environment's .jks files. Hit save.

 

All of the authentication components should be running and configured at this point. Now all that remains is configuring a DDF instance so it will go through this authentication scheme.

Configuring DDF instances to use the authentication scheme

Once everything is up and running, hooking up an existing DDF instance to the authentication scheme is just a matter of setting a few configuration properties.

  1. Make sure the ${DISTRIBUTION}/etc/keystores folder is updated with the correct keystores for your operating environment.
  2. Start the distribution.

  3. Enter the following commands to install the CAS features

    features:install security-cas-client
features:install security-cas-cxfservletfilter
  4. Open up the Security CAS Client configuration. Under Server Name, put the URL to the STS server. Under CAS Server URL, put the URL to your CAS server. Hit save.
  5. Open up Platform Global Configration. Change the protocol to https and populate the host/port information with the DDF instance's host/port.
  6. Update the Trust Store and Key Store location/password fields with your environment's .jks files. Hit save.
  7. Open up the Security STS Client configuration. Make sure the host/port information in the STS Address field points to your STS server.
  8. Change Signature Username to "client".
  9. Change Encryption Username to "tokenissuer".
  10. Change STS Token Username to "client". Hit save.

The DDF should now hit the CAS/STS/LDAP servers whenever it attempts to authenticate a user on login.