Many companies use 3rd party hosted SSO identity providers – there’s a lot out there to choose from. From our client advocacy program, we learned that one of our customers uses Okta as their SSO provider. We created an Okta development account to see what would be involved in getting this to work. 

Thankfully, our development team has greatly simplified the SSO setup with a utility script. This script makes easy work of setting up the Compass side of things. All you have to do is provide a configuration file and the script does the work. We’re including a special Okta configuration file you can use as a template.   

You can find the script (with configuration files) installed with Compass 2.0.2 and later. The template is called  ssoconfig_okta_ex.txt and we are sharing some tips for setting up your Okta service and filing out the configuration parameters. 

Setting up Okta Single Sign On Service

We need to tell Okta about our Compass web server. In Okta’s admin console, you’ll do this by creating an application.

Here is our Okta Compass application definition: 

Note that the redirect URL is the server and port where Compass is hosted – the /oidcclient/okta path is something that will be created when we run our script.  Also, note the “Client ID” and the “Client secret”.  This is a unique pair of values Okta will assign when you create a new application. You will use these later when you configure Compass Web. 

Now we’ll set up an Okta Authorization server (you’ll find this under Security-> API). Click on “Add Authorization Server” if you don’t already have one, and set it up like this:

You’ll see that the “Audience” is our Compass URL.  Make a note of the issuer, as you will need it for your configuration file. The issuer is a unique URL Okta uses to identify this authorization server.  The default scopes should be good enough for us. Compass only cares about openid, email, and profile: 

Now that we have set up Okta services, let’s configure the Compass side. 

Configuring Compass Web to use Okta SSO Service 

Remember we called out the “Redirect URL”, “Client ID”, “Client secret”, “Issuer”, and “scopes”? We’ll use that to fill in our configuration file!  Let’s open the file, ssoconfig_okta_ex.txt, and step through the parameters needed for the script: 

The first half of the configuration file is mostly about WebSphere: 

############################## 

##### SSO Setup ############################## 

#REQUIRED – choose the SSO_TYPE. Supported options for this script are 

# SAML2 or OIDC 

SSO_TYPE=OIDC 

#REQUIRED – a password to be used for SSO. The CQ databases and CQ Web 

#server store encrypted versions of this password which is used to ensure 

#that only trusted CQWeb servers are being used to provide SSO access. 

#Password must be 30 characters long. 

SSO_PASSWORD=dfEcKlL1ahlr-ztBkzcK9W9jFiKyoAC4fLqFr6eb 

#OPTIONAL 

# OKTA credentials should be obtained the same way as SAML2 even though 

# we’re using the OIDC services. 

SSO_LOGIN_MODE_OVERRIDE_FOR_PROPS=SAML2 

############################## 

###### WAS runtime and profile  

############################## 

#REQUIRED – specify the profiles administrator user and password here. 

SSO_WAS_ADMIN_USER=admin 

SSO_WAS_ADMIN_PASSWORD=admin 

# If WebSphere is not in a standard location, or it cannot be found by the script 

# or the CQ Web profile was created manually rather than in Installation Manager 

# then you may need the following settings. 

#OPTIONAL – default uses default WAS install location 

SSO_WAS_PATH=C:\IBM\WebSphere\AppServer\  

#OPTIONAL – default uses cqwebprofile (IM created webprofile) 

#SSO_WAS_PROFILE=cqwebprofile 

#OPTIONAL – if not set, script tries to get node name using wsadmin command. 

#SSO_WAS_NODE=dfltNode 

#OPTIOINAL – if using IM created cqwebprofile it will default to server1, otherwise 

# you must specify the server name. It is probably “server1” 

#SSO_WAS_SERVER_NAME=server1  

SSO_TYPE=OIDC and SSO_LOGIN_MODE_OVERRIDE=SAML2 will remain as-is in the file. This tells Compass that Okta will act as an OpenID Connect provider, but the credentials should be obtained from the LTPA2 token (which is what SAML2 uses). 

SSO_PASSWORD is a string of your choosing, at least 30 character long. 

SSO_WAS_ADMIN_USER and SSO_WAS_ADMIN_PASSWORD are the administrator user/password combination for your WAS administration console. 

SSO_WAS_PATH is where you have installed the WebSphere AppServer.   

You’ll see SSO_WAS_PROFILE, SSO_DEFAULT_NODE, and SSO_SERVER_NAME here are commented out – if you are not using the default values, uncomment them (remove the # at the beginning of the line) and fill in the values specific to your Compass environment. Next section to edit is where we start to use our Okta information. In the example below, our Okta SSO service is at https://dev-173886.oktapreview.com/ and our authorization server ID is “ausaunat0izNnR5Vx0h7”. Substitute the actual SSO URL and authorization server ID for your Okta SSO services.  

 

############################## 

##### OIDC and other WAS security Settings 

############################## 

#REQUIRED 

# These come from the OID IDP (e.g. Okta) 

# Base URL of the Okta OIDC IDP 

SSO_OIDC_IDP_URL=https://dev-173886.oktapreview.com/ 

# The identity of the IDP. This comes from your OIDC IDP, e.g. the JAS server or Liberty. 

# We can just use “okta” here. 

SSO_OIDC_IDP_ID=okta 

# You need to add the IDP’s realm to the trusted list of realms. 

# Okta’s realm is the same as the Okta Issuer URL. 

SSO_OIDC_IDP_REALM=https://dev-173886.oktapreview.com/oauth2/ausaunat0izNnR5Vx0h7 

# REQUIRED for OKTA, the endpoint paths are slightly different than for  

# Liberty’s OIDC service.  

SSO_OIDC_IDP_ENDPOINT_PATH=oauth2/ausaunat0izNnR5Vx0h7/v1 

# REQUIRED for OKTA, we tell OKTA to return the profile and email scopes 

# so we can get the email address for login 

SSO_OIDC_IDP_SCOPE=openid profile email 

# REQUIRED for OKTA, Okta requires RS256 signatures 

SSO_OIDC_IDP_SIGNATURE_ALG=RS256 

# REQUIRED for OKTA, because we’re using RS256 we need to also add the jwkEndpointUrl 

# to the custom properties 

SSO_OIDC_IDP_JWK_ENDPOINT=keys 

# REQUIRED for OKTA, WAS doesn’t calculate the issuer identifier correctly from 

# the authorize endpoing URL so we have explicitly set this 

# Set this to same value as SSO_OIDC_IDP_URL 

SSO_OIDC_IDP_ISSUER_IDENTIFIER=https://dev-173886.oktapreview.com/oauth2/ausaunat0izNnR5Vx0h7 

# REQUIRED for OKTA, tell WAS which key to use for finding the principals name (username) 

SSO_OIDC_IDP_USER_IDENTIFIER=preferred_username 

#REQUIRED 

# This is used to identify the OIDC configuration on the relying party (RP) or client  

# side (CQ Web). It is a good idea to use the same value as SSO_OIDC_IDP_ID here. 

SSO_OIDC_RP_ID=okta 

#REQUIRED 

# This is a client name to use when registering the RP on the IP. This is also used 

# to check that the RP is trusted by the IP. Okta will pick this for you when you set 

# up the application in Okta admin console. 

SSO_OIDC_RP_CLIENTNAME=xxxxxxxxxxxxxxxxx 

#REQUIRED 

# A secret string shared by the RP and IP to establish trust.  

# Okta will pick this for you when you set up the application in Okta admin console. 

SSO_OIDC_RP_SECRET=XXXXXXXXXXXXXXXX 

#REQUIRED 

# CQWeb Host and Port. These are required to create the custom properties for the OIDC TAI. 

# These values are also used for creating the client registration files that you can use 

# to help you register the RP as a client of the IP. 

# Use the SSL port. SSO is only supported through SSL. 

SSO_CQWEB_HOST=www.myhost.com 

SSO_CQWEB_PORT=12443 

SSO_OIDC_IDP_URL is the base URL for my Okta account. 

Remember that Redirect URL?  We set SSO_OIDC_IDP_ID=okta so the script can set up the redirect in WebSphere. 

From our Okta Authorization server: 

Our SSO_OIDC_IDP_REALM and our SSO_OIDC_IDP_ISSUER_IDENTIFIER are both going to match up with the “Issuer”.  

OpenID Connect servers have URL Endpoints which are used by WebSphere to perform SSO.  SSO_OIDC_IDP_ENDPOINT_PATH tells the script how to create the endpoint URLs from the SSO_OIDC_IDP_URL.  It should be formatted as “oauth2/<authorizationserverid>/v1”. 

SSO_OIDC_IDP_SCOPE should be set to “openid profile email” to make sure that Okta lets us use the right information for SSO login.   

SSO_OIDC_IDP_SIGNATURE_ALG and SSO_OIDC_IDP_JWK_ENDPOINT will remain as-is in the file. Okta requires RS256 for signatures and WebSphere requires the JWK Endpoint when using RS256. 

SSO_OIDC_IDP_USER_IDENTIFIER will tell WebSphere to use the preferred_username supplied by Okta, which is the email address/login the user logs in with at Okta’s login page. 

For SSO_OIDC_RP_CLIENTNAME and SSO_OIDC_RP_SECRET, use the client name and secret generated by Okta when you created the Compass application there. 

SSO_CQWEB_HOST, and SSO_CQWEB_PORT are your Compass host name and WAS port. 

There are some optional parameters (not shown) after that which we can skip. 

############################## 

#CQ Database setup. 

############################## 

# CQ Databases need to be configured to support SSO. You need to tell the setup tool 

# which CQ dbsets to configure and provide an admin usernamd and password. 

#REQUIRED 

# CQ Databases 

# List of triples (dbset, admin_user, admin_password) for all dbsets that need the SSO 

# password set on. The script needs to log on to the CQ dbset and enable SSO on it. 

# If you don’t list your dbset/login info here, then it won’t be accessible to a CQ Web 

# server that is configured to use SSO. 

SSO_CQ_DATABASE_INFO=2.0.2,admin,admin 

 

SSO_CQ_DATABASE_INFO is the dbset, Compass admin user, and Compass admin user password, separated by commas. Only dbsets listed here will be enabled for SSO. To define multiple dbsets, separate the triplets by a comma. 

Make It So! 

Now we let the script do the rest of the work! Run the cqssosetup script and get some coffee.  

cqperl cqssosetup.pl enable -config ssoconfig_okta_ex.txt 

When it finishes, bring up Compass web in a browser.  If you haven’t already authenticated against Okta, you’ll be redirected to do that: 

Success!

Does your organization use a hosted SSO provider?   

What do you use?  

Do you want to use it with Compass?  

Have you already set up Compass to use SSO?   

We’d love to hear about it.  Please tell us about your experience in the comments! 

Comment wrap
Further Reading
article-img
HCL Software, Secure DevOps | April 13, 2021
Compass Import Assistant
The Compass Import Assistant is a straightforward Perl application that will parse a whole CSV document that imports into Compass.
article-img
Secure DevOps | March 26, 2021
How to Enable Search in HCL Compass
As an end user, searching for information in a web application can be complicated. In Compass product, it would be great if we could search all attributes of records at once. This can be made possible through search configurations. 1. Why Compass Search? Searching various record types using ID is difficult. Search functionality allows the user to search for various Record types based on “Search Scope” for example Customer, Product, Iteration. Project etc. Suppose if user is interested to fetch all defects matching a project name, it will be possible to obtain all records matching the project name. User can also apply filters by combining multiple criteria like different Record Types and different attributes. 2. Advantages of Search functionality Text search is divided into two tasks: indexing and searching. The indexing stage will scan the text of all the records and build a list of search terms often called an index. In the search stage, only the index is referenced, rather than the text of the original records. Full-text search also supports advanced search options with operators using “AND” “OR” “NOT”. It also supports wild cards such as?*. 3. How to configure Full-text search in Compass web in old UI? Configuring and enabling the full-text search feature for HCL Compass Web consists of the following tasks: Configuration Steps: 1. Run the cpsearch.pl command, with the initSearch and -solrHome options, in a command prompt window: cqperl cpsearch.pl initSearch -username admin -password "" -dbset TextSearch -userdb SAMPL -searchHome C:\CPSearch\CPSearch.Home -solrHome C:\CPSearch\CPSearch.Solr -solrPort 8984 When this command completes, configuration data corresponding to your schema is placed in the following directory: C:\CPSearch\CPSearch.Home\TextSearch_SAMPL\ Below is the output user should get if there are no errors: 2. Edit the entity file associated with the deployment: C:\CQ.Search\TextSearch_SAMPL\Entity-TextSearch-SAMPL.txt. For each record type, select a display field to appear...
article-img
Secure DevOps | February 5, 2021
Protecting HCL Compass from Brute-force attacks
HCL Compass allows the administrator to protect Compass database repositories from brute-force attacks, here is the official documentation.  It limits the number of invalid login attempts of an attacker, who pretends as a user, before the lock out and also limits the login attempts from a certain host connecting to HCL Compass.  If an attacker is trying to hack and determine the password of a particular user, they might try many login attempts with different username and password combinations until they find one that works. As a defence against such attacks, HCL Compass can lock out the account or host used by the attacker when a certain number of failed attempts have occurred. When an account or a host is locked out, the login error message is the same as if the attacker entered an incorrect username and password. This prevents the attacker from knowing that the account has been locked out, causing them to waste resources on a continued fruitless attack. This severely limits the attacker to succeed in guessing the password.  Steps to protect the credential  HCL Compass enables the credential protection in just two simple steps.  First step to enable security is by creating a “.config” file with the below data. In this example we will create the config file with the name “SecureCredential.config”. This file can be created in any location; hence we have created the file in the HCL Compass default installation location, which is, “C:\Program Files\HCL\CCM\Compass”  # Comments are preceded by '#' and are ignored. # This enables lockouts lockout_enable 1 # Host lockout configuration # This sets the HOST lockout threshold to 10 tries lockout_threshold HOST 10  # This sets the HOST reset period to 60 seconds. lockout_reset HOST 60 # User lockout configuration # This sets the USER lockout threshold to 10 tries lockout_threshold USER 10  # This sets the USER reset period to 60 seconds. lockout_reset USER 60 # Whitelist / blacklists lockout_whitelist HOST whitelisthost lockout_whitelist USER whitelistuser1, whitelistuser lockout_blacklist HOST blacklisthost3 lockout_blacklist USER bl_user1 lockout_blacklist USER bl_user2,bl_user3 # Login attempt table cleanup # This says to cleanup any failed login attempts older # than one day (60s/m * 60m/hr * 24hr/day), and only # in...
Close