Configuring SSO for TRIRIGA on WebSphere Liberty with Azure and OpenID

There are several steps for configuring single sign-on (SSO) with WebSphere Application Server Liberty, Microsoft Azure, and OpenID Connect (OIDC).

Note: The following SSO content was written for TRIRIGA Application Platform 3.7 and above. Effective April 2020, Office 365 was renamed to Microsoft 365. Effective July-October 2023, Microsoft Azure AD was renamed to Microsoft Entra ID.

Contents

I. Registering OpenID with Azure

To use OpenID Connect (OIDC) with TRIRIGA, you must register an OpenID application with Microsoft Azure, and create an OpenID client secret that will be used later to configure WebSphere Application Server Liberty.

a. Creating Microsoft Azure Account

Procedure
  1. If you do not already have a Microsoft Azure account, then create one of the following:
  2. After you create an account, open the Microsoft Azure portal.
  3. Sign in with your admin credentials.

b. Registering OpenID Application with Microsoft Azure

Procedure
  1. Launch the Microsoft Azure app registration screen from the following URL:
  2. Select New Registration to begin the app registration process.
    • Name: Enter a descriptive name to display to users. This value is generally used to identify the registration in the Microsoft Azure portal.
    • Account Type: This value may vary depending on your organization's overall use of Microsoft Azure and Microsoft 365. However, for normal TRIRIGA integrations, Single Tenant is sufficient.
    • Redirect URL: Enter the value for: <tririga_base_url>/oidcclient/redirect/Azure
  3. Select Register to display the next registration screen. From this Overview screen, several links either require additional configuration or provide information necessary for WebSphere Application Server Liberty server.xml configuration later.
    • Application (Client) ID: Copy this value and save it for now. Later, in the server.xml file, enter this value in the clientId attribute of the openidConnectClient element. This step will be discussed later.
    • Endpoints. See below.
    • Certificates & Secrets. See below.
  4. Endpoints: This screen provides the endpoints for OpenID interaction.
    1. Copy the OpenID Connect metadata document value.
    2. Open the OpenID Connect metadata document URL in a new browser tab.
    3. In the .json document, locate the values for: issuer, token_endpoint, jwks_uri, and authorization_endpoint.
    4. Copy these values and save them for now. Later, in the server.xml file, enter these values in the respective issuerIdentifier, tokenEndpointUrl, jwkEndpointUrl, and authorizationEndpointUrl attributes of the openidConnectClient element. This step will be discussed later.
  5. Certificates & Secrets: This screen provides the client secret for OpenID interaction. To add a client secret:
    1. Select New Client Secret.
    2. Add a description for your client secret.
    3. Select a duration.
    4. Select Add.
    5. After you save the configuration changes, the right-most Value column will contain the client secret value.
    6. Copy this value and save it for now. Later, in the server.xml file, enter this value in the clientSecret attribute of the openidConnectClient element. This step will be discussed later.

II. Configuring SSO with TRIRIGA

After you register an OpenID application with Microsoft Azure, the next step is to set up SSO with TRIRIGA.

a. Assigning Microsoft Users to TRIRIGA

Before you configure the SSO, you must create one or more TRIRIGA users and set each TRIRIGA username to the username of each Microsoft user. Because after SSO is enabled, the only way for users to log into TRIRIGA will be from the Microsoft sign-in screen.

Procedure
  1. Log in to the TRIRIGA main portal.
  2. Create one or more TRIRIGA users. Set each TRIRIGA username to the username (email) of each Microsoft user.
    Important: You must take this step before you configure the SSO, because after SSO is enabled, the only way for users to log into TRIRIGA will be from the Microsoft sign-in screen.

b. Editing TRIRIGAWEB.properties File

Procedure
  1. On the application server, set the following attributes in the TRIRIGAWEB.properties file. This file should be located in the Tririga/config folder.
    SSO=Y
SSO_REMOTE_USER=N
SSO_USER_PRINCIPAL=Y

III. Configuring OpenID with WebSphere Liberty

After you register an OpenID application with Microsoft Azure, and set up SSO with TRIRIGA, the next step is to set up OpenID Connect (OIDC) with WebSphere Application Server Liberty.

You set up OpenID by installing the OpenID Connect client feature, importing the signer certificate into the keystore, and editing the WebSphere Application Server Liberty server.xml file.

a. Installing OpenID Connect Client Feature

Procedure
  1. Connect to the environment where WebSphere Application Server Liberty is installed.
  2. Run the following commands from the <path_to_liberty>/wlp/bin folder.
    installUtility install openidConnectClient-1.0
installUtility install transportSecurity-1.0
    Note: If you encounter an error that the feature is already installed, ignore the error and proceed to the next step.

b. Importing Signer Certificate into Keystore

Procedure
  1. Download the Baltimore CyberTrust Root certificate that is used by Microsoft, from the following URL:
    Note: Depending on your system, the certificate file might be named bc2025.crt or bc2025.cer.
  2. After you download the certificate file, copy it to WebSphere Liberty at: <path_to_liberty>/wlp/usr/servers/<server_name>/resources/security where <server_name> is the name of your WebSphere Liberty server.
  3. In the server.xml file, make the following changes.
    1. If the <keyStore> element is not defined yet, then add a default keystore.
      <keyStore id="defaultKeyStore" password="password"/>
      • To load the keystore file, the password value can be stored in clear text or encoded form.
      • To encode a different password, use the WebSphere Liberty securityUtility command.
    2. If the transportSecurity-1.0 feature is not enabled yet, then add the following element declaration inside the <featureManager> element.
      <featureManager ... >
   <feature>transportSecurity-1.0</feature>
</featureManager>
    3. Save your changes to the server.xml file.
    4. Start or restart WebSphere Application Server Liberty.
  4. Connect to the environment where WebSphere Application Server Liberty is installed.
  5. Run the following command from the <path_to_liberty>/wlp/usr/servers/<server_name>/resources/security folder.
    keytool -importcert -keystore <server_keystore_name> -storepass <server_keystore_password> 
   -alias loginMicrosoft -file <certificate_filename> -noprompt

    For example:

    keytool -importcert -keystore key.p12 -storepass password 
   -alias loginMicrosoft -file bc2025.cer -noprompt

c. Editing WebSphere Liberty server.xml File

Procedure
  1. On WebSphere Application Server Liberty, in the server.xml file, add the following element declaration inside the <featureManager> element.
    <featureManager ... >
   <feature>openidConnectClient-1.0</feature>
</featureManager>
  2. Add the following element declaration with the values that you saved earlier from the Microsoft Azure app registration.
    <openidConnectClient
   clientId="<application id from your registered app>"
   clientSecret="<client secret that you created for your app>"
   id="Azure"
   issuerIdentifier="<issuer from OpenID Connect metadata document>"
   tokenEndpointUrl="<token_endpoint from OpenID Connect metadata document>"
   jwkEndpointUrl="<jwks_uri from OpenID Connect metadata document>"
   authorizationEndpointUrl="<authorization_endpoint from OpenID Connect metadata document>"
   signatureAlgorithm="RS256"
   userIdentityToCreateSubject="preferred_username"
   redirectToRPHostAndPort="https://<public host name>:<ssl port>"
   >
</openidConnectClient>
  3. Map the TRIRIGA role to ALL_AUTHENTICATED_USERS.
    • If the <application-bnd> element is already defined, then replace it with the following element declaration.
    • If the <application-bnd> element is not defined yet, then add the following element declaration inside the <webApplication> element.
    <webApplication ... >
   <application-bnd>
      <security-role name="TRIRIGA_PLATFORM">
         <special-subject type="ALL_AUTHENTICATED_USERS"></special-subject>
      </security-role>
   </application-bnd>
</webApplication>
  4. Set the invalidateOnUnauthorizedSessionRequestException attribute to true.
    • If the <httpSession> tag is already defined, then verify if it has an attribute named invalidateOnUnauthorizedSessionRequestException.
      • If the attribute is already defined, then verify or change its value to true.
      • If the attribute is not defined yet, then add the attribute and set its value to true.
    • If the <httpSession> tag is not defined yet, then add the following element declaration.
    <httpSession invalidateOnUnauthorizedSessionRequestException="true"/>
  5. Add the following element declaration to change the authentication cache timeout.
    <authCache timeout="2h"/>
  6. Save your changes to the server.xml file.
  7. Start or restart WebSphere Application Server Liberty.
  8. Log in to TRIRIGA. Now, you should see the Microsoft sign-in page.
    Important: Remember that each TRIRIGA username was set to the username (email) of each Microsoft user.