Steps for Integrating Identity using OIDC

This chapter describes generic steps to integrate an identity provider with the Trillo Workbench using OIDC authorization code.

Trillo Workbench supports seamless integration with external IdPs like Okta, OneLogin, and Google, using the industry-standard OpenID Connect (OIDC) authorization code flow. This guide outlines the straightforward 3-step process to enable this integration, empowering you to leverage your existing identity systems for Trillo Workbench logins.

1. Enter IdP settings into Trillo Workbench using UI.

2. Map user profile returned by IdP onto Trillo Workbench user schema.

3. Start using it for login through Trillo Workbench.

Enter IdP settings into Trillo Workbench using UI

When you register with an IdP, you will receive a number of parameters that need to be used in the application (i.e. Trillo Workbench as your application platform). These parameters are listed in the table below.

When you add an IdP to the Trillo Workbench you create a record with the following information.

1. Name - some user friendly name for reference.

2. Service Name - a service name that is used in the API by the client (UI).

3. Grant type, it is set as Authorization Code.

4. IdP and Trillo Workbench related parameters listed in the following table.

Trillo Workbench Label		Example / Description
Authorization URL	Issued by IdP. It is URL where user is redirected to login with redirect url, state etc parameters.	https://accounts.google.com/o/oauth2/auth
Token URL	Issued by IdP. It is used by Trillo Workbench to obtain Access Token.	https://oauth2.googleapis.com/token
Client Id	Issued by IdP.
Client Secret	Issued by IdP.
Redirect URL	It is standard Trillo Workbench callback URL. Use your Trillo Workbench instance url.	<Trillo WB Server>//_oauth2/callback
Comma Separate List of Scopes	Issued by IdP.	openid, email, profile
User Profile Info URL	Issued by IdP. It is used to obtain user profile (email, name, phone, etc. as permitted by the scope).	https://www.googleapis.com/oauth2/v2/userinfo
User Info Transformation Function	This is discussed more in detail below. This is a simple code that maps user profile returned by IdP to Trillo Workbench user schema.	GoogleUserProfileMapper
Post Authentication URL	URL where user should land after successful login.	UI URL where user is supposed to land post successful login
Logout URL	Issued by IdP. It is used to logout the use from IdP when user logs out of the application.	https://accounts.google.com/o/oauth2/logout

Map user profile returned by IdP onto Trillo Workbench user schema

Trillo Workbench aligns user profiles received from your IdP with its own user schema, ensuring effortless data synchronization. The intuitive nature of this mapping is clearly illustrated in the following example.

public class GoogleUserProfileMapper implements Loggable, TrilloFunction {

  public Object handle(ScriptParameter scriptParameter) {

    try {
      return _handle(scriptParameter);
    } catch (Exception e) {
      log().error("Failed", e);
      return Result.getFailedResult(e.getMessage());
    }
  }

  @SuppressWarnings("unchecked")
  private Object _handle(ScriptParameter scriptParameter) {
    Map<String, Object> idpUser = (Map<String, Object>)scriptParameter.getV();
    Map<String, Object> trilloUser = mapUserProfile(idpUser);
    return trilloUser;
  }
  
  private Map<String, Object> mapUserProfile(Map<String, Object> idpUser) {
    Map<String, Object> trilloUser = new LinkedHashMap<String, Object>();
    trilloUser.put("firstName", idpUser.get("given_name"));
    trilloUser.put("lastName", idpUser.get("family_name"));
    trilloUser.put("externalId", "" + idpUser.get("id"));
    trilloUser.put("pictureUrl", idpUser.get("picture"));
    trilloUser.put("emailAddress", idpUser.get("email"));
    return trilloUser;
 }
}

In order to make this code available to the Trillo Workbench, simply add the above function to the Trillo Workbench. (For convenience, the above function is added to the Trillo Workbench and you can view it by turning on Show system function.

Start using it for login through Trillo Workbench

Once you follow the above steps are completed, you can integrate external IdP with the login button using the following steps.

1. Add a Button: Add button with a label such a Login Using Google Identity.

2. Fetch IdP Url and point the browse to it: When user clicks on the login button the following actions should take place.

   • Use /_oauth2/url endpoint to get a url with a new "state" parameter (generated and recorded by the Trillo Workbench).

   • Point browser to the URL returned by the above call. This will take the user to IdP UI, which will present a login dialog to the user.

   • Once user logs in successfully, the browser will be redirected to the Trillo Workbench UI with a code. The code will be used by the Trillo Workbench to fetch the access token using the token endpoint. This will happen behind the scene and you don't have to do anything for it.

   • Sample code for the above interaction is as follows:

   Endpoint:

   POST /_oauth2/url

   Headers:

   'Content-Type':'application/json'

   Body:

   {
     appName : "auth",  // required by Trillo, its value is always "auth"
     serviceName : <serviceName given to IdP in Trillo Workbench form>   
    }

   Response:

   {
       "status": "success",
       "message": "Success",
       "data": "https://<idp url>/oidc/2/auth?response_type=code&
           client_id=<client_id of IdP>&
           redirect_uri=<WB URL>/_oauth2/callback&
           state=<a unique string generated by Trillo Workbenc>&
           scope=openid",
       "code": 200,
       "_rtag": "_r_",
       "taskStatus": "task_status_not_set",
       "failed": false,
       "detailMessage": "Success",
       "success": true
   }
   
   "data" above is the value of IdP URL for login.

3. After obtaining access token, Trillo Workbench redirect the browser to "Post Authentication URL", which is a UI URL. This URL will have a query parameter called a_t_nonce. Using the value of this URL, the UI will invoke a API (/_oauth2/nonceLogin) of Trillo Workbench to get the access token recently acquired by the Trillo Workbench.

Endpoint:

GET /_oauth2/nonceLogin

Headers:

'Content-Type':'application/json'

Query Parameters: none

Response:

{
    "accessToken": "<value of access token recenly acquired>",
    "user" : <user profile>
}

Once the UI receives recently generated access token and the user's profile, it is logged in. It can use access token in other API calls.