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