Getting ClearQuest Single Sign On Working with Okta

You may have heard that ClearQuest now supports single-sign-on (SSO)! 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 and was interested in using it with ClearQuest Web (CQWeb).  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 ClearQuest 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) here:

http://www-01.ibm.com/support/docview.wss?uid=swg27049409
The template is called ssoconfig_okta_ex.txt and we are sharing some tips for setting up your Okta service and filling out the configuration parameters.

Setting up Okta Single Sign On Service
We need to tell Okta about our CQWeb server.  In Okta’s admin console, you’ll do this by creating an application. 

​
Here is our Okta ClearQuest application definition:
​

​
Note that the “redirect URL” is the server and port where CQWeb 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 CQWeb.

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 CQWeb 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. CQWeb only cares about openid, email, and profile:
​

Lastly,  create a new access policy for CQWeb. Go to “Access Policies” and click “Add New Access Policy”. Set it up as you see in the picture below:
​

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

Configuring CQWeb 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 CQWeb 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.  If you are using the default install location (e.g. Program Files x86), you can remove this setting.

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 CQWeb 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 email address 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 CQ application.

SSO_CQWEB_HOST, and SSO_CQWEB_PORT are your CQWeb 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=9.0.0,admin,admin

______________________________________________________________

SSO_CQ_DATABASE_INFO is the dbset, CQ admin user, and CQ 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.

The configuration file is ready!

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 CQWeb in a browser.  If you haven’t already authenticated against Okta, you’ll need to do that:

Success!
​

​
Does your organization use a hosted SSO provider?  What do you use? Do you want to use it with CQWeb? Have you already set up ClearQuest to use SSO?  We’d love to hear about it.  Please tell us about your experience in the comments!
​

Leah Nassar
ClearQuest Software Support Engineer
leah.nassar@hcl.com