HCL Compass and single sign-on

You can configure HCL Compass for single sign-on with Lightweight Third-Party Authentication (LTPA), OpenID Connect, and Security Assertion Markup Language 2.0 (SAML2).

Single sign-on (SSO) prevents the need to sign on to multiple applications separately. Rather than having to sign on for each application, the user signs in once at an identity provider (IP) and this provides tokens to provide to other web applications and services. A token is like an ID card. You show it wherever you go and it is trusted in many places. If the ID card is trusted, you can do things such as rent a car, buy a magazine, fly on a plane, and so forth. The same goes for SSO tokens. For any application that is set up to trust the token, it will allow you to log in to that application as the authenticated user. SSO makes using many different applications easier and more secure because you need only to log in once and you only do so on the trusted login site.

Authentication and authorization are separate in SSO. The first time a user connects to one of the applications, the user must authenticate by logging in. When the token is valid (usually in 24 to 48 hours), the user does not need to authenticate again. Instead the previously obtained token is used to authorize access to the application.

Choosing an IP

OIDC and SAML2 have a user experience that is more consistent and configurable. These two provides automatic redirects to the IP login site. This login site is usually customizable to provide a consistent login page that provides information about your enterprise and what applications might be available to the user.

LTPA2, on the other hand, uses the browser’s basic authentication capability, which is a pop-up window that asks for a username and password. It might be confusing trying to figure out to what you are logging in.

If you have OIDC or SAML2 capability, we supply a script that can automate most of the OIDC and SAML2 setup for you. The script includes template configuration files you can use to as a starting point. The templates will work with a Liberty-based OpenID Connect provider such as Jazz). Included is also a template file you can use for configuring Compass with Okta Single Sign On. You can download the scripts directly from HCL Compass product.

Configuration

Setting up SSO can be a complicated and time-consuming process. It involves a combination of setup on the WebSphere Application Server (WAS), Compass, and the IP. We have written a script to automate most of the process. The script only works for OIDC and SAML2 (this might change in the future), and there are still some manual steps you will need to do. We recommend using one of these two SSO technologies and the supplied script for setting up SSO.

If you must use LTPA2, documentation for setting it up is attached to this page. Also attached are detailed instructions for setting up SSO with OIDC and SAML2 if you want to do so manually.

Using the Setup Script

About the script that automates most of the SSO setup for OIDC and SAML2, it needs a configuration file (examples are provided). Running the script does most of the setup steps for you. It does 100% of the setup for Compass Web and WebSphere, but you still must do some steps on the IP side.

For OIDC, you need to register the Compass Web application as a client of the SSO service. How you do this depends on which IP provider you use. For JAS, a command line tool is provided in the cli directory called ldclient. For a basic Liberty OIDC IP, you can add the registration directly into the server.xml. The OIDC standard provides for a REST interface that lets you register the client using a POST command. Instructions for how to register Compass Web are provided once the script finishes running. In addition, the script produces two files that you could use for the registration process: a JSON file that you can use for JAS/cli or REST POST, and an XML file with a snippet of XML that you could use for a server.xml based client registry.

For SAML2, clients and IPs exchange information using metadata files. As part of the script configuration, you will have provided the script a metadata file for the IP. When the script finishes running, it will produce a metadata file that you can import at the IP. This metadata file contains information about the SSO client (Compass Web) and what certificates it uses and should be trusted.

For information about how to create an SSO configuration file, see the example configuration files that come with the script.

Plugin Configuration

As part of the SSO for OIDC and SAML2, you will have added a new web service to your WAS profile. This service helps with the SSO parts. The service that was added depends on which SSO technology you use.

CWOAU0062E: The OAuth service provider could not redirect the request because the redirect URI was not valid. Contact your system administrator to resolve the problem.

The configuration is mostly performed in the WAS console and assumes that you are familiar with a workaround that was needed to enable https redirect.

As a result, the SSO with https:// <hostname>/cqweb will work.

End User Experience

When SSO is configured for Compass, the user experience is a little bit different. If the user has not already authenticated, then the user is asked to authenticated. How this looks depends on which SSO IP you use and how you customize it. OIDC and SAML2 typically provide the most user-friendly experience.

If only a single repository and database exist (not including test databases), then once the user is authenticated, CQ Web logs them in to that database automatically. If more than one repository or user exists, then you are presented with the Connect to Compass dialog. The username is pre-populated with the SSO user and the password is blank. Both are disabled because you are using SSO to connect.

You can log in to Compass as a different user than the one you authenticated with using SSO. If you have already connected to a Compass database, then log out first. When you see the login dialog, you can clear the Use SSO Identity checkbox. This re-enables the User ID and Password fields so that you can log in as a different user. CQ Web will remember this the next time you need to log in, whether it is after you log out, or the next time you load the browser. Similarly, you can select Use SSO Identity again to use the SSO identity. This too is remembered for the next time.

Limitations