Visual Builder Component for Oracle Analytics — Part 6 — Token Auth

5 min readSep 14, 2021

Introduction

Using OAuth Tokens to authenticate embedded analytics content can provide flexibility to your application architecture. I have written blogs on this topic, with part 1 describing how to obtain the token and part 2 describing how to use this mechanism programmatically using the Oracle OCI Functions and API Gateway services.

Those blogs provide an approach for making analytics content available in a public manner, by using the token API you create in part 2 to automatically authenticate the embedded analytics canvas but this method could also be used to configure specific security / logon for your own custom application.

If you’ve found this blog via an internet search and wondering about parts 1–5, then please refer to this blog for an introduction to building custom analytics applications using Oracle Analytics and Visual Builder.

Using a Token API in Visual Builder

This blog assumes that you’ve already followed part 1 and part 2 of the token API blogs referenced above and you have an API endpoint that will return a token that can be used to authenticate embedded analytics content. It also assumes that you’ve followed the previous blogs in this series and understand the basics of embedding Oracle Analytics canvases into a Visual Builder application.

Creating a Service in Visual Builder

The first step in using tokens with embedded analytics content is to create a mechanism in VB to obtain the token. This can be achieved by defining a service connection based on an endpoint.

On selecting ‘Define by Endpoint’ you can enter the URL for your API that returns a token as seen below (blurred for publication):

As you navigate through the create service UI, you get to an option to test the API endpoint:

Testing API Endpoint for VB Service Connection

On selecting ‘Send Request’ you’ll see the response from the API endpoint (i.e. the JSON for the OAuth Token) appear. This can then be saved as an example response.

Response from Token API — Save as Example Response

On selecting ‘Create’, the result will be a Service Connection that will allow you to obtain a token and pass it to a variable for use in the Oracle Analytics embedding component.

Creating a Type

The next step is to create a Type from the token service endpoint created in the previous step.

Select all the fields and then ‘Finish’ to define the endpoint type:

Create a Variable Based on the Type

Create a variable based on a Service Data Provider Type:

Populating the Variable

Ideally, we need to populate the variable that will pass the token to the embedded analytics content as soon as the page loads. We can do that by creating an action chain.

Action Chain to Call REST Endpoint and Populate Variable

Here is the mapping between the result of calling the REST endpoint and the variable to hold the token:

Create Event Listener

Create an Event Listener, of type ‘Lifecycle Events’, specifically ‘vbEnter’.

The Event Listener needs to call the Action Chain created earlier, ‘getTokenOnPageLoad’:

A way to test that the API call action chain and variable population is working is to add a text area to your app page with source data of the token variable. If it’s working then you’ll see the OAuth token appear as in the example below:

Don’t forget to remove this text box when you make your application available.

You add your analytics canvas to the application page in the same way as described in the earlier blogs in this series but in order to use token authentication, you check the box ‘Use token auth’ and pass the reference to the variable that holds the token in the configuration field ‘OAC token reference’.

Using Visual Builder Anonymous Access

As I mentioned at the start of this blog, one of the use cases for token authentication of embedded analytics is to make content available publicly, without any users needing to specifically authenticate themselves since this happens automatically by obtaining a token and passing it to the embedded analytics.

Visual Builder provides an option to ‘Allow Anonymous Access’ to an application and this can offer the same type of public access to an analytic application that also uses tokens for authentication.

There is one other setting that is required if you don’t want users of your application to login to either VB or Oracle Analytics Cloud that is using tokens to authenticate embedded content. In the screenshot below, you’ll see that the option ‘Allow only secure applications to be created’ is off. The VB product doc on this setting is here.

In summary, the product doc states “When an administrator enables the Allow only secure applications to be created option, all published and staged applications in the instance will require user authentication. When the option is enabled, users must be assigned a role by the identity domain administrator and log in to access an application. When the option is not enabled, applications can be created that allow access to anonymous users.”

Summary

This blog has described how to enable token based authentication for embedded analytics content within a Visual Builder application. It’s mostly a case of setting up the mechanism to obtain the token by calling an API. Luckily VB provides a straightforward, low code way to do this. Once you have that mechanism created, then you check the token option in the analytics component and reference that token variable.