Configuring SSO for TRIRIGA on traditional WebSphere with Azure and OpenID

There are several steps for configuring single sign-on (SSO) with traditional WebSphere® Application Server, Microsoft Azure, and OpenID Connect (OIDC). Effective April 2020, Office 365 is now renamed Microsoft 365.

Note: The following SSO content was written for TRIRIGA® Application Platform 3.7 and above.

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.

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 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 Application Server

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.

You set up OpenID by installing the OpenID Connect application, importing the signer certificate into the truststore, and configuring the WebSphere Application Server settings in the WebSphere Integrated Solutions Console.

a. Opening WebSphere Integrated Solutions Console

Procedure
  1. Launch the WebSphere Integrated Solutions Console from the following URL:
    • http://<internal_server_name>:<was_admin_port>/admin
    • For example, http://<tririga_server>:9066/admin
  2. For the User ID, enter: admin.
  3. For the Password, enter: admin.
  4. Click Log In.
    Note: If the console does not request a User ID and Password, then enable the administrative security in the following procedure.

b. Enabling WebSphere Administrative Security

Note: If the console already requests a User ID and Password, then you can skip the following procedure.
Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select Security > Global Security.
  3. Click Security Configuration Wizard.
  4. Make sure to clear Enable Application Security. Click Next.
  5. Select Federated Repositories. Click Next.
  6. Enter your administrative credentials. Click Next.
  7. Click Finish.
  8. Click Save.

c. Installing OpenID Connect Application

Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select Servers > Server Types > WebSphere Application Servers.
  3. The Application Servers screen provides a list of server names and related node names.
    1. Copy the Name and Node values and save them for now. For example, the Name might be server2, and the Node might be ip-10-165-194-11Node03.
    2. Later, when you run the Python script installOIDCRP.py, include these values in the <serverName> and <nodeName> of the command. This step will be discussed later.
  4. Connect to the environment where WebSphere Application Server is installed by using PuTTY (https://putty.org/).
  5. Determine the values for <app_server_root_folder> and <profile_name>. To find these values:
    1. Open the TRIRIGA Administrator Console.
    2. Select Java Info.
    3. In the Java System Properties page, locate the Classpath field.
    4. Copy the <app_server_root_folder> value and save it for now. The <app_server_root_folder> is the parent folder of the profiles folder. For example, this folder might be /home/tririga/IBM/WebSphere/AppServer.
    5. Copy the <profile_name> value and save it for now. The <profile_name> is the child folder of the profiles. For example, this folder might be AppSrv02.
  6. Navigate to the <app_server_root_folder>/bin folder.
    cd <app_server_root_folder>/bin

    For example:

    cd /home/tririga/IBM/WebSphere/AppServer/bin
  7. Install the OpenID Connect application by running the Python script installOIDCRP.py with the values that you saved earlier.
    ./wsadmin.sh -p <profile_name> -f installOIDCRP.py install <nodeName> <serverName>

    For example:

    ./wsadmin.sh -p AppSvr02 -f installOIDCRP.py install ip-10-165-194-11-Node03 server2

d. Configuring Security Domain & Authentication Cache Timeout

Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select Security > Security Domains.
  3. Click New.
  4. For the Name, enter: OIDCAzure. Click OK.
  5. Open the OIDCAzure security domain.
  6. In the Assigned Scopes section:
    1. Expand Cell > Nodes > <Node Name> > Servers.
    2. Select the TRIRIGA server.
  7. In the Security Attributes section:
    1. Expand Application Security.
    2. Select Customize for this Domain.
    3. Select Enable Application Security.
    4. To change the authentication cache timeout, expand Authentication Mechanism Attributes.
    5. Select Customize for this Domain.
    6. Click Authentication Cache Settings to go to the General Properties section.
  8. In the General Properties section:
    1. Change the Cache Timeout to 120 minutes.
    2. Click OK.
  9. Scroll to the bottom of the page. Click OK.

e. Configuring OpenID Connect Relying Party

Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select Security > Security Domains.
  3. Open the OIDCAzure security domain.
  4. In the Security Attributes section:
    1. Expand Trust Association.
    2. Select Customize for this Domain.
    3. Select Enable Trust Association.
    4. Click Interceptors to go to the Interceptors screen.
  5. In the Interceptors screen, click New.
  6. In the General Properties section:
    1. For Interceptor Class Name, enter com.ibm.ws.security.oidc.client.RelyingParty
    2. Under Custom Properties, click New to add the following properties with the values that you saved earlier from the Microsoft Azure app registration.
    3. Add provider_1.clientId with the Value of <application id from your registered app>.
    4. Add provider_1.clientSecret with the Value of <client secret that you created for your app>.
    5. Add provider_1.identifier with the Value of Azure.
    6. Add provider_1.issuerIdentifier with the Value of <issuer from OpenID Connect metadata document>.
    7. Add provider_1.tokenEndpointUrl with the Value of <token_endpoint from OpenID Connect metadata document>.
    8. Add provider_1.jwkEndpointUrl with the Value of <jwks_uri from OpenID Connect metadata document>.
    9. Add provider_1.authorizeEndpointUrl with the Value of <authorization_endpoint from OpenID Connect metadata document>.
    10. Add provider_1.signatureAlgorithm with the Value of RS256.
    11. Add provider_1.userIdentifier with the Value of preferred_username.
    12. Add provider_1.redirectToRPHostAndPort with the Value of https://<public host name>:<ssl port>.
    13. Click OK.
  7. Return to the OIDCAzure security domain.
  8. In the Security Attributes section:
    1. Scroll to the bottom of the page.
    2. Click Custom Properties to go to the Custom Properties screen.
  9. In the Custom Properties screen, click New.
    1. Add com.ibm.websphere.security.InvokeTAIbeforeSSO with the Value of com.ibm.ws.security.oidc.client.RelyingParty.
    2. Click OK.

f. Configuring Microsoft Azure Realm as Trusted Realm

Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select Security > Security Domains.
  3. Open the OIDCAzure security domain.
  4. In the Security Attributes section, expand User Realm.
  5. Click Configure to go to the next screen.
  6. Select Trusted Authentication Realms - Inbound to go to the next screen.
  7. In the Trust section, select Trust Realms as Indicated Below.
  8. Under Realms, click Add External Realm.
    1. Add the Name of <issuer from OpenID Connect metadata document>.
    2. Click OK.

g. Configuring WebSphere Session Property

Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select Servers > Server Types > WebSphere Application Servers.
  3. Select the application server. For example, the Name might be server2.
  4. In the Container Settings section, select Session Management.
  5. In the Additional Properties section, click Custom Properties to go to the Custom Properties screen.
  6. In the Custom Properties screen, click New.
    1. Add invalidateOnUnauthorizedSessionRequestException with the Value of true.
    2. Click OK.

h. Importing Signer Certificate into Truststore

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 the environment where TRIRIGA is installed.
  3. Launch the WebSphere Integrated Solutions Console.
  4. Select Security > SSL Certificate and Key Management.
  5. In the Related Items section, select Key Stores and Certificates.
  6. In the Key Stores and Certificates screen, click NodeDefaultTrustStore.
  7. In the Additional Properties section, select Signer Certificates.
  8. In the Signer Certificates screen, click Add.
    1. Add the Alias of baltimore with the File Name of <complete path to the bc2025 file on the environment where TRIRIGA is installed>.
    2. Click OK.

i. Mapping TRIRIGA Role to All Authenticated Users

Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select Applications > Application Types > WebSphere Enterprise Applications.
  3. Select the application name that begins with IBM-TRIRIGA. For example, the Name might be IBM-TRIRIGA_Build-296099.
  4. In the Detail Properties section, select Security Role to User/Group Mapping.
  5. In the Security Role to User/Group Mapping screen:
    1. Select the Role of TRIRIGA_PLATFORM.
    2. Select Map Special Subjects > All Authenticated in Trusted Realms.
    3. Click OK.

j. Saving All Changes to Master Repository

Procedure
  1. Launch the WebSphere Integrated Solutions Console.
  2. Select System Administration > Save Changes to Master Repository.
  3. Click Save.