TechExchange: How to use the System.OauthAccountLink component to perform authorized access to protected REST endpoints (Facebook Example)

article by Frank Nimphius, October 2019

OAuth 2.0 (Open Authorization) is the standard protocol for token-based authorization. It allows clients (such as chatbots) to access protected resources on behalf of a resource owner without passing the resource owner's credentials with the request.

Chatbots created with Oracle Digital Assistant integrate with remote back-end systems through custom components that invoke REST services. For custom components to access protected REST endpoints, some sort of authorization must be passed in the request header.

Oracle Digital Assistant supports OAuth2 authorization through the built-in System.OAuthAccountLink component. You use the System.OAuthAccountLink component to get an authorization token, which you then exchange for an access token in a custom component call to the OAuth2 token endpoint, so that subsequent custom component calls can access protected REST resources.

This article explains how to authorize custom component requests for OAuth2 protected resources using Facebook as an example. Facebook supports OAuth2 and allows a bot to access user profile information if authorized by the user.

About the System.OAuthAccountLink Component

The two most commonly used authorization options in OAuth2

Client Credential Flow – Using the client credential flow, clients like Oracle Digital Assistant obtain authorization to protected resource through a shared client Id and client secret. This authorization flow type can be handled using a custom component only (subject of a future Oracle TechExchange article).
Authorization Code Flow – The authorization code flow requires a bot user to authorize a resource access. In a first request, the client requests an authorization token for which it needs the user to login to the remote identity provider and to grant the requested access (defined as "scope"). With the authorization token, using a custom component, Oracle Digital Assistant then requests a second endpoint to exchange the authorization token for an access token then then needs to be sent with each access request to the protected resource.

Using the authorization code flow in Oracle Digital Assistant, the System.OAuthAccountLink component helps you to obtain the authorization code by sending a redirect request to the remote authorization endpoint. If the user is not authenticated to the remote server, the user will be prompted for her username and password. Then, if it is the first time she runs the Oracle Digital Assistant skill requesting for access, she will have to approve the requested resource access.

The System.OAuthAccountLink component is accessible through the + Components template in the dialog flow builder environment (see image below). You need to configure it with a variable reference of type string to receive the authorization token, as well as with an "authorizeURL", which is the GET request expected by the remote authorization provider. The URL usually includes the call back URL into Oracle Digital Assistant, a client Id, the scope (the resource grants requested) and more information required by the authorization endpoint.

The System.OAuthAccountLink component is documented in the product documentation. In the documentation you find an example to using LinkedIn as the authorization provider.

Note: Authorization servers behave similar but are different in the information they need. To understand the request requirements, please refer to the 3rd party authorization documentation (e.g. for Facebook links are provided at the end of this articles)

Sample at Runtime

The sample provided with this article demonstrates an authorization code flow using Facebook as the authorization provider and resource holder. Not all Facebook user profile API require authorization code flow (access to basic profile information works with the credential flow). If however you need access to e.g. the user mail address, then authorization code flow is required (a link to the Facebook API permissions is provided at the end of this article).

When the user – bot conversation reaches a dialog flow state that is associated with the System.OAuthAccountLink component, users are prompted for clicking a login button or a cancel button.

Pressing the login button redirects the request to the Facebook authorization endpoint, which redirects the user to the Facebook login page if the user hasn't authenticated before. If the user is authenticated, but it is the first time she runs Oracle Digital Assistant requesting access to a resource, she will be prompted to allow the access.

After a successful authentication and authorization, the Facebook authorization server redirects the request to the Oracle Digital Assistant callback URL that you had passed with the authorization request. In response, a message is displayed in the browser tab or webview window indicating that it can be closed now.

Next, the sample skill provided with this article prints the authorization code. This printed statement is for demonstration purpose only and should not be used in your production bot.

The authorization code is then passed to a custom component that calls the facebook token API for an access token. The call is not performed from the browser but server side, which means that it is secure in that it cannot be intercepted through browser network sniffing tools.

After obtaining the access token, a second custom component is called in the sample that accesses the protected resource (the Facebook user profile API) for the information to display. The call to the protected source then uses the access token to proof authorization. The result of the sample is shown below (just with your connected user data).

Configuring OAuth2 Access in Facebook

Unlike other samples I share on Oracle TechExchange, this does not run out-of-the box but requires some setup.

You need a developer account on Facebook, wich you get free of cost by authenticating with your Facebook account to https://developers.facebook.com
Second, you need to create a Facebook application, which you do from the Facebook developer page, choosing the "MyApps" –> Create App menu option (see image below).

Note: "CenterStage" is the Facebook application I created for demonstration purposes and this article. You don't have access to it.

What is the Facebook application for?

Applications in Facebook are "client applications" that provide you with a client ID, a client secret and settings for the redirect URL. It is common in OAuth2 authorization servers that the client's redirect URL needs to be registered with the provider in advance to prevent unauthorized modifications.

Note: When deploying your Oracle Digital Assistant bot to the Facebook messenger channel, you also need to create a Facebook app and associate it with a Facebook page you create. While you could use the same app for authorization, I recommend to build a separate app. For security reasons it is not advisable to use the same app.

Once the app is created, you can access the App ID and the Application Secret from the Settings -> Basic panel (see image below). This information is needed in the System.OauthAccountLink component (App Id) and in the custom component that requests for the access token (App Id and Application Secret).

Facebook, like many other authorization providers, require you to register the OAuth2 callback URL to prevent fraud. For this you need to navigate to the Products -> Facebook Login -> Settings menu. The callback URL you need for Oracle Digital Assistant is a webhook call in the form of : https://<cloud host>.oraclecloud.com:443/connectors/v1/callback. I'll cover later how you get to know the call back host part.

Building the OAuth2 Dialog Flow State

To perform authorization code flow in Oracle Digital Assistant, the client (Oracle Digital Assistant) requests an authorization endpoint to obtain an authorization token. This request is configured on and performed by the System.OAuthAccountLink component. You use the System.OAuthAccountLink component for all non-Oracle authorization providers (providers which are not Identity Cloud Service or Oracle Access Manager).

If the user is not yet authenticated, the authorization endpoint redirects the request to a login form. If the user is authenticated but did not grant the client access to the requested resource, a web view is displayed for user approval.

If authentication and authorization happened, the the client (Oracle Digital Assistant) receives an authorization token by Facebook calling the redirectURL. Up to this point. this is a 2-legged authorization process.

To complete the authorization code flow, the authorization token returned from Facebook needs to be passed to a custom component, which then securely requests an access token. The access token issued by the Facebook token endpoint and has a limited life-time.

Once the access token is received by Oracle Digital Assistant, all subsequent custom component queries to the Facebook Graph APIs need to pass the access token to be able to fetch data. A list of Facebook resources that you can access through authorize custom component calls is documented here:

https://developers.facebook.com/docs/facebook-login/permissions/

You can even try the APIs using the Facebook Graph API explorer

https://developers.facebook.com/tools/explorer/?classic=1

The BotML code below shows the dialog flow state with the System.OAuthAccountLink component that renders the login menu and that sends the request to the Facebook authorization endpoint


 oauthAccountLink:
    component: "System.OAuthAccountLink"
    properties:
      prompt: |-
              Please press the login button for me to re-direct you to Facebook. 

      variable: "authToken"      
      authorizeURL: "https://www.facebook.com/v4.0/dialog/oauth?response_type=code&client_id=<your app_id>&
                     redirect_uri=https://<your cloud instance>.oraclecloud.com:443/connectors/v1/callback
                     &response_type=code&scope=email"
      cancelLabel: "Cancel"
      linkLabel: "Login with Facebook"
      showCancelOption: true
    transitions:
      next: "oauthAccountLink"
      actions:
        pass: "printToken"
        fail: "printFail"
        textReceived: "printCancel"


Note: The authorization URL contains a query parameter "scope" with the value of "email". Not all Facebook profile permissions require authorization by the user. However, the email information does. Every permission that is not accessible without explicit user authorization needs to be added to the scope parameter in the request.

Learning About the Callback URL

The callback URL that needs to be registered in Facebook and that needs to be sent with the System.OAuthAccountLink authorization request (and that needs to be sent when exchanging the authorization token for an access token in a custom component call) can be obtained from the channel configuration in Oracle Digital Assistant. As shown in the image below, navigate to the channel configuration and create a new Facebook configuration (you can dismiss it later). Copy the Webhook URL including the "connectors" part. to create the callback URL, just append "/v1/callback" as shown below

<webhook value including the connectors string>/v1/callback.

BotML

The following images show the dialog flow of the sample skill you can download for this article. I did obfuscate sensitive information related to my own Oracle Cloud instance I used to build the sample and produce the screenshots.

To obtain an access token, a custom component (also provided) is used to sent the authorization token to the Facebook /token endpoint. The information you need to provide for this includes the authorization token ("token" property), the clientId (app_id in Facebook) and the appSecret code. In addition, as mentioned, you need to pass the redirectURL. The redirect URL will be compared against the registered redirect URL(s) in Facebook to prevent fraud.

The "variable" property references a dialog flow variable of type string that will receive the access token in case of a successful /token endpoint request.

Once the access token is returned from the first custom component, it is saved (in the sample) in the "accessToken" variable (you can decide to change the name the way you want). The access token is valid for a couple fo hors and thus does not need to be re-requested for each call to the Facebook Graph APIs. The custom component used in the dialog flow below (also provided for download) queries the Facebook API for the authenticated user profile information. The result is saved as an array in the dialog flow variable referenced by the variable component property.

Finally the user information saved in the dialog flow variable can be displayed using a System.CommonResponse component.

About the Custom Component

This article uses two custom components for obtaining the access token and to query the Facebook user profile API.

Both custom components can be downloaded from here. The most important information you find in the custom component code is the token and the user Graph API reference.

You can use the custom components as a starting point for your own Facebook integration and maybe as a template for building additional custom components that read other areas of the Facebook Graph APIs.

Note: The image below shows a code snippet of the TokenExchange component.

Important: The sample is provided as is. Oracle world wide customer support does not support samples released on Oracle TechExchange. If you have questions, please post them to the Oracle Digital Assistant forum on OTN:

https://cloudcustomerconnect.oracle.com/resources/3be43c6ff3/summary