X

Best Practices from Oracle Development's A‑Team

  • June 30, 2021

Enabling SSO in ODA from MS-Teams for Oracle Fusion Applications

Executive Summary

Oracle Digital Assistant (ODA) is a powerful platform that can be used as a convenient, conversational chat client by Oracle Fusion Applications (FA) customers. Different pillars within FA, such as, Human Capital Management (HCM), Enterprise Resource Planning (ERP), and Customer Experience (CX) have skills available that provide support for common business functions via the ODA conversational interface. On the other hand, many FA customers use MS-Teams (Teams) for internal communication and are interested in leveraging this channel to communicate with ODA. ODA supports many communications channels for conversations including Teams and it is thus possible to have conversations with FA from a Teams session.

However, the FA customers using Teams may also have Single Sign-On (SSO) enabled between Azure Active Directory (AD) and FA. In that case, the expectation is to have a seamless conversation with FA from a Teams session. But the security access token generated from Teams cannot be directly used to communicate with FA at present. Until this discrepancy is addressed via an enhancement in product functionality, this blog provides the high-level guidelines for an interim, custom solution that can be used to implement an optimum, conversational experience from Teams with FA.

The methodology presented here should only be treated as a proof-of-concept without any support. It is not recommended for any production deployment, until proper security considerations are addressed by the implementation team.

Solution Architecture

The solution is implemented by creating a custom skill with a custom component that is developed to generate an access token at runtime which is compliant with requirements of FA. The authentication flow within an MS-Teams session can be broken up into a sequence of steps, as listed below

  1. Call the Authentication service in Azure and get a JWT token in the custom skill 
  2. Extract the MS-teams session username from Step 1 and use the custom component to generate a second JWT token that can call the REST APIs within FA

The overall solution architecture is shown in Fig. 1.

Fig. 1 Architecture of ODA for SSO with MS-Teams and FA

Setup 

There are a few prerequisites which should be completed within Azure portal, ODA console and FA dashboard. The following sections outline the details of configuration in different product areas.

SSO between Azure and ODA

The configuration of SSO between Azure and SSO is well documented in the product documentation[1]. Please refer to the section that describes the configuration steps. Besides, there is a detailed technical white paper[2] with screenshots for every step, which is also mentioned in the TechExchange blog[3]. Following the steps documented in these references, an additional authentication provider can be configured for Azure Identity Provider within ODA console, as shown in Fig. 2.

Fig. 2 MS-Azure configured as Identity Authentication Provider in ODA Console

Import of Public Certificate in Fusion Applications

In order to enable external clients call REST APIs within Fusion Applications, the public certificate from the external trusted issuer must be imported to support inbound authentication[4]. This can usually be done in self service mode as documented or via a Service Request with Oracle Support. The imported certificate with trusted issuer should show up in the API Authentication Provider screen within the Security Console of Fusion Applications as shown in Fig. 3.

Fig. 3 Public Certificate for Authentication Provider and Trusted Issuer imported in FA

Custom Skill Development

The custom skill developed here has primarily 2 main areas of development. First is the conversational flow, where the user is first authenticated by Azure and second is the custom component where the JWT token for Fusion Applications is generated for subsequent use in REST APIs. Following sections highlight parts of the conversational flow and the custom component which were used to build the custom skill

Conversational Flow

As a result of our setup of SSO mentioned earlier, we have an identity provider already configured within our ODA console, as shown in Fig. 2. A few custom configuration parameters are defined for the skill within the ODA console to pass the values for identity provider and other variables (Fig. 4).

Fig. 4 Custom Configuration Parameters for the ODA skill

Call System Component OAuth2AccountLInk to get JWT Token from MS-Azure

As a first step for authentication in the conversation, the system component OAuth2AccountLink is called to retrieve the JWT token and the authenticated username from Azure, as shown here. Information about this system component call can be found in the ODA product documentation[5].

  userAuth:
    component: "System.OAuth2AccountLink"
    properties:
      enableSingleSignOn: "${system.config.enableSSO}"
      prompt: "User Authentication"
      linkLabel: "Login to ${system.config.authProviderName}"
      authenticationService: "${system.config.MSAuthService}"
      accessTokenVariableName: "user.accessToken"
      authenticatedUserVariableName: "user.authenticatedUser"
    transitions:
      actions:
        pass: "ssotokenFA"
        fail: "userAuthFailure"

Call Custom Component to get new JWT Token for FA

The username obtained from the previous system component call is now passed to a custom component along with the private key configured as a secure configuration parameter (refer to Fig. 4).

    ssotokenFA:
    component: "com.ateam.FAJWT"
    properties:
      teamsUser: "${user.authenticatedUser}"
      keyFA: "${system.config.privateKeyforFA}"
      responseVariableName: "user.resultPayload"
    transitions:
      next: "displayResults"     

Custom Component

The custom component accepts the username from the MS-Teams session and uses it to generate a new JWT token signed by the private key corresponding to the public certificate imported earlier in FA.

The key areas of building the custom component are discussed here with relevant code snippets.

  • The custom component has a dependency on jsonwebtoken module, which is listed below.
     "use strict";
     const jwt = require('jsonwebtoken');
  • Input and output parameters between the custom component and the conversation flow are listed here.
    const { teamsUser }             = conversation.properties();
    const { keyFA }                 = conversation.properties();
    const { responseVariableName }  = conversation.properties();
  • Setup the JWT token claim tags that are relevant for calling REST APIs in Fusion Applications
    var v_iss  = 'ATeam'; // Issuer has to match the name as shown in  Fig. 3
    var v_aud  = 'https://<FA instance hostname>';

    var payload = {
      "prn": teamsUser,
      "iss": v_iss,
      "aud": v_aud,
      "sub": teamsUser,
     };
  • Generate the new JWT token with a validity interval of 12 hours and signed by the private key. The header field, x5t should be populated from the fingerprint of the public certificate imported earlier. Details for generating the x5t value correctly are described in the blog[6] published by my teammate, Siming Mu.
    var token = jwt.sign(payload, keyFA, {   
       algorithm: 'RS256',
       expiresIn:  12 * 60 * 60,
       header: {"x5t": "<fingerprint from imported public certificate>",
      }
    });
  • Return a JSON object with the new JWT token back to the conversational flow.
    var resultsObj  = {JWT: token}; // JSON object with new token
    conversation
      .variable(responseVariableName, resultsObj)
      .keepTurn(true)
      .transition('success');
    done();

Upon return from the custom component, the conversational flow can then use standard techniques available to process the JSON object and extract the new JWT token. The new token can then be passed to a second custom component invoking a REST API from Fusion Apps. Since invoking a REST API is a standard, well-documented technique in NodeJS, the details are not discussed here. Please refer to the product documentation, as needed[2].

Testing

After packaging the custom skill for testing, we run it in a MS-Teams chat session. We observe that the bot response does not show the Sign-In pop-up button for Fusion Apps, as is seen for sessions without SSO (Fig. 5).

Fig. 5 Sample ODA conversation in MS-Teams without SSO

Instead, we see a seamless conversation in MS-Teams that returns information from Fusion Applications using REST API calls. Portions of a sample chat session output is shown in Fig. 6 below.

Fig. 6. Sample ODA conversation session in MS-Teams with SSO

This concludes the testing of our custom skill in Digital Assistant built to enable SSO from MS-Teams for Oracle Fusion Apps.

Summary

The approach outlined here is primarily documented to provide the initial guidance to build a basic framework that can enable SSO for ODA in a Teams session. It is not recommended for production usage by any means and is beyond the scope of this blog. It is left to the readers discretion to take this approach as the starting point and then build on it for further enhancements and optimizations to address the unique security requirements different situations may demand. 

Acknowledgements

I would like to acknowledge Rohit Dhamija of Oracle Digital Assistant team and Chandrasekhar Kottaluru of Fusion Applications team, who provided valuable guidance for  the SSO setup with Azure and Oracle Digital Assistant.

I would also like to thank my teammates, Siming Mu and Greg Mally, who helped me at different times with build or compilation of this custom ODA skill.

References

  1. SSO Configuration for Microsoft Teams Channels - Product Documentation for Oracle Digital Assistant
  2. Using MS Teams SSO authentication to access Microsoft Graph APIs from chatbot conversations in Oracle Digital Assistant - Technical White Paper, Rohit Dhamija
  3. Using MS Teams SSO authentication to access Microsoft Graph APIs from chatbot conversations in Oracle Digital Assistant  - TechExchange Blog, Frank Nimphius, Master Principal Product Manager, Oracle Digital Assistant
  4. Inbound Authentication in Fusion Applications - Product Documentation for Fusion Applications
  5. Backend Authentication - Product Documentation for Oracle Digital Assistant
  6. A Quick Note on Using JWT Token Authentication with Oracle SaaS API  - A-Team Blog, Siming Mu

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha