Configuring SSO by using a cloud OAuth provider for IBM® TRIRIGA login

Starting in IBM TRIRIGA Application Platform 4.5.3, you can configure one of several third-party cloud providers (such as Autodesk, Google, Microsoft, and Okta) as the OAuth identity provider (IdP) for single sign-on (SSO) to log into TRIRIGA® with third-party login credentials. There are several steps for configuring the OAuth provider, which include creating the OAuth application 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
(1a) The login process makes an unauthenticated call to the platform endpoint: <Base TRIRIGA URL>/p/oauth/profile. The platform displays a list of OAuth profiles that are enabled for TRIRIGA login.
Note: The platform SSO can also be used for foundation-portal and Perceptive-app logins with the following restrictions: <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 foundation portal, or add ?webApp=true for the Perceptive app, or use * for the target application in the OAuth profile record.
(1b) If a list of OAuth profiles are displayed, the user selects a profile and starts the OAuth identity provider (IdP) login process.
(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.
(3a) The user completes the OAuth identity provider (IdP) login process.
(3b) If the login process for IBM TRIRIGA Connector for BIM or IBM TRIRIGA CAD Integrator/Publisher detects that the IdP returned an OAuth code and state, the browser is closed.
(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.
(11a) If successful, the platform returns a JSESSIONID cookie, and issues a redirect to the original target application URL listed in the profile.
(11b) The login process ignores the redirect URL, and saves the JSESSIONID cookie for further communication with the platform.

II. Creating OAuth application

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.
Important: The following instructions provide the general steps for an OAuth identity provider (IdP) such as Autodesk, Google, Microsoft, and Okta.
Procedure
  1. Create and configure a new OAuth application with the proper application type, scopes, users, and redirect URIs.
    Note: Configure the OAuth application for three-legged flow. 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.
  2. Locate the Client ID and Client Secret values.
    Note: Make a note of the Client ID and Client Secret values. You will need these values to configure the OAuth provider in TRIRIGA.

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: Autodesk, Google, Microsoft, or Okta. For Custom, be aware that other providers will receive generic processing and is not guaranteed to work.
    • 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 Client ID that you obtained when you created the OAuth application in Section II.
    • OAuth Application Secret: Enter the Client Secret that you obtained when you created the OAuth application in Section II.
    • OAuth Authorize URL: Enter the URL value from the OAuth provider.
    • OAuth Token URL: Enter the URL value from the OAuth provider.
    • 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 the API permissions that are granted to an OAuth application. The only access that TRIRIGA requires is to read the current user. For example:
      • For Autodesk, enter user:read
      • For Google, enter openid+https://www.googleapis.com/auth/userinfo.email
      • For Microsoft, enter openid
      • For Okta, enter okta.users.read.self
    • User ID Claim: Enter the claim in the OAuth token that is used for the user identity. This field is ignored for Autodesk and Google. For example:
      • For Autodesk, this is ignored.
      • For Google, this is ignored.
      • For Okta, the claims in the OAuth token can 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: Enter the field of a user's My Profile record that is matched to the OAuth user identity. This field can be any field, including custom fields. 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.
    • Microsoft Graph Callback URL: This field is not used for IBM TRIRIGA Connector for BIM or IBM TRIRIGA CAD Integrator/Publisher. But it can be used to enable an IBM TRIRIGA Application Platform Perceptive app or Administrator Console for login. This URL is the URL of the platform or target app.

IV. Creating users in TRIRIGA

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

V. Logging into TRIRIGA

You can log into TRIRIGA with your third-party credentials by using the following URL: <tririga base url>/p/oauth/<OAuth profile name>/tririga. For example:
  • For Autodesk, use https://triapp.company.com/dev/p/oauth/forge/tririga
  • For Google, use https://triapp.company.com/dev/p/oauth/google/tririga
  • For Microsoft, use https://triapp.company.com/dev/p/oauth/azure/tririga
  • For Okta, use 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 third-party ID and password.