Configuring SSO by using Okta for IBM® TRIRIGA login

Starting in IBM TRIRIGA Application Platform 4.5.3, you can configure Okta as the OAuth identity provider (IdP) for single sign-on (SSO) to log into TRIRIGA® with Okta login credentials. There are several steps for configuring Okta as the OAuth provider, which include creating the application in Okta and configuring the OAuth provider details in TRIRIGA.

Note: SSO does not need to be enabled to use OAuth login. However, if SSO is enabled, OAuth login can still be used and may use a different IdP than the IdP for SSO.

Contents

I. Conceptual flow

The conceptual flow to log into the TRIRIGA platform by using an OAuth provider is presented in the following table.

Step Description
(1) The login process makes an unauthenticated call to the platform endpoint: <Base TRIRIGA URL>/p/oauth/<profile>/<target>
  • <profile> is the name of the OAuth profile to use for the login.
  • <target> is the name of the target application. Use tririga for the portal and * for the target application in the OAuth profile record.
(2) The browser opens to the authorized URL listed in the profile. The application key, scope, redirect URL listed in the profile, and the profile name in the state parameter are passed. The redirect URL is expected to end with the path: /p/oauth/signon.
(3) The user completes the OAuth identity provider (IdP) login process.
(4) The IdP redirects to the redirect URL in the profile. This URL is the unauthenticated platform endpoint: <Base TRIRIGA URL>/p/oauth/signon. An OAuth single-user code and state from the previous step is passed to the platform.
(5) The platform searches and verifies the user profile.
(6) The platform calls the token endpoint listed in the profile with the secret in the profile and the code provided in the call.
(7) Depending on the OAuth identity provider (IdP), the platform verifies the token by using it to call the getUser/me endpoint or get email over SSL to get the current user. For other providers, tokens are not verified.
(8) The platform performs a JSON lookup to get the value of the User ID Claim listed in the profile. Depending on the OAuth identity provider (IdP), the value is from the user returned by getUser. For other providers, it is the email from get email. For all other providers, it is from the token.
(9) The platform searches for a My Profile record that has the value from the User ID Claim lookup in the My Profile ID Field listed in the OAuth profile.
(10) If a match is found, the platform attempts to create a user session.
(11) If successful, the platform sends a redirect to the original target application URL listed in the profile.

II. Creating OAuth application in Okta

Important: All instructions for configuring a specific provider are informational only. Providers may change their process at any time without notice. IBM provides no support for the provider configuration. You must contact the provider.
Procedure
  1. To create a new app integration, click Create App Integration.
  2. In the Create a new app integration screen, select the following options:
    • For the Sign-in method, select OIDC - OpenID Connect.
    • For the Application type, select Web Application.
    • Click Next.
  3. In the New Web App Integration screen, select or enter the following options:
    • For the Grant type, select Client acting on behalf of a user > Authorization Code.
    • For the Sign-in redirect URIs, enter <tririga base URL>/p/oauth/signon
    • If the server is a multi-homed server, then enter additional URLs as needed.
    • For the Assignments > Controlled access, select an option.
    • Click Save.
  4. In the new web app integration, review or update the following tabs:
    • In the General tab, for the Client authentication, keep the selected option of Client secret.
      Note: Make a note of the Client ID and generated Client secret. You will need these values to configure the OAuth provider in TRIRIGA.
    • In the Okta API Scopes tab, grant access to okta.users.read.self.

III. Configuring OAuth provider in TRIRIGA

Procedure
  1. Log into the TRIRIGA main portal.
  2. Navigate to Tools > System Setup > Integration > OAuth Settings.
  3. Select Add to add a new OAuth profile record.
  4. In the OAuth Setup section, specify the following OAuth settings:
    • Name: Enter the name of the OAuth profile that is going to be used for login.
    • OAuth Provider: Select the name of the OAuth provider. For example: Okta.
    • Access Type: Select User delegate. With OAuth, a three-legged flow involves the end-user (user delegate), the client, and the server, while a two-legged flow involves only the client and the server.
    • Description: Specify a description.
    • OAuth Application Key: Enter the Okta Client ID that you obtained when you created the OAuth application in Section II.
    • OAuth Application Secret: Enter the Okta Client secret that you obtained when you created the OAuth application in Section II.
    • OAuth Authorize URL: Enter the following URL value: https://<Okta Domain>/oauth2/v1/authorize
    • OAuth Token URL: Enter the following URL value: https://<Okta Domain>/oauth2/v1/token
    • OAuth Redirect URL: Enter the value for: <tririga base URL>/p/oauth/signon. For example: https://triapp.company.com/dev/p/oauth/signon
    • OAuth Scope: Enter API permissions that are granted to an OAuth application. For Okta, enter the following: okta.users.read.self.
    • User ID Claim: Okta allows the claims in the OAuth token to be configured. In the default token, the Okta user (which should be an email) is in the sub claim. If you are using the default, enter sub.
    • My Profile ID Field: The Okta User ID can be stored in any field of a user's My Profile record including custom fields. Specify the field here. Typical values are either UserName or eMail.
    • User For TRIRIGA Login: Select the check box to enable logging into TRIRIGA by using this OAuth provider.
    • Login Text and Login Image URL: These fields are optional and you can use them to configure the appearance of the button for this profile on the login screen.

IV. Adding certificate to Liberty truststore

Okta uses a certificate specific to the account that needs to be trusted by IBM WebSphere Application Server Liberty.

Procedure
  1. Log into you Okta account from your web browser.
  2. Click on the lock icon or the Net Secure error.
  3. Display and download the certificate.
  4. Use the Java Virtual Machine (JVM) keytool to add the certificate to the Liberty truststore.

V. Creating users in TRIRIGA

You must create user records in TRIRIGA so that the users can use their Okta credentials to log in. For more information on creating a user, see Creating people records.

VI. Logging into TRIRIGA

You can log into TRIRIGA with your Okta credentials by using the following URL: <tririga base url>/p/oauth/<OAuth profile name>/tririga. For example: https://triapp.company.com/dev/p/oauth/okta/tririga.
Note: Replace the OAuth profile name with the name that you have provided in the Configuring OAuth provider in TRIRIGA section.

Log into TRIRIGA by using your Okta ID and password.