Oracle Analytics Cloud (OAC) Embedding— Public User Access — Part 1

6 min readAug 5, 2020

Introduction

Oracle Analytics is an easy to use, highly visual way to understand what your data is telling you. In some scenarios, it is desirable to make this insight available to a larger audience, without the need for the viewer to log in.

This multi-part blog series will describe how to achieve this using a combination of Oracle Cloud services combined with the OAC embedding framework. The first in this series of blogs will describe how the overall solution is architected, how to configure an IDCS confidential application to obtain a token and test the token works.

Here’s a video that also describes this process:

Video Describing How to Generate and use Tokens with OAC Embedding

Overview of Solution

The following diagram illustrates how public user access works for OAC content embedded in a web page.

Public User Access for Embedded Oracle Analytics Content

(1) A client accesses a web page that contains embedded OAC content (canvases) using the <oracle-dv> tag. See this blog post for details of how to do that embedding.

Before the user can see the content, OAC needs to be authenticated, in this case using an authentication token obtained from Oracle Identity Cloud Service (IDCS).

(2) The web page calls an API (deployed using the Oracle API Gateway service) that runs a script running on the Oracle Functions service to obtain an authentication token from IDCS.

(3) This function calls the IDCS token API using one of the methods supported by IDCS.

(4) The token is returned via the Oracle API Gateway to the client.

(5) OAC content is shown in the users browser

Create a Confidential App in Oracle IDCS

This step assumes that you already have an Oracle Analytics Cloud instance created. The next step is to create a confidential application within Oracle IDCS to act as a proxy between the webpage with embedded OAC content and OAC itself.

You perform this task on the Oracle Identity Provider Service console. The following is an overview of the key steps but please refer to the IDCS documentation for a detailed explanation.

Adding a Confidential Application in IDCS Admin Console

Set the option for ‘Resource Owner’ in Allowed Grant Types:

Scroll down on that page to ‘Add Scope’ in the Token Issuance Policy. You will be presented with a list of applications defined in IDCS, you need to choose the application that corresponds to the OAC instance you’re embedding content from. Look for a resource starting ‘ANALYTICSINST_’ and ending with the name of your OAC instance:

Add the reference corresponding to OAC used for embedding

Skip the last section on that page:

Don’t select anything on tab 4 and click ‘Finish’:

At this stage, you will be presented with a pop-up window containing the Client ID and Client Secret. Make a note of these (securely) as you’ll need them later. If you miss this pop-up then you can access this information later in the IDCS application you’ve created (see the details section of the app configuration).

At this stage, the IDCS confidential application isn’t active but you can activate it from the IDCS application UI.

Testing out Token Generation

The quickest way to test you’re able to generate authentication tokens is using a CURL command to call the IDCS API for tokens, in this case, we’re using the command for the IDCS ‘resource owner password credentials workflow’:

curl — request POST \
 — url https://<IDCS-domain>.identity.oraclecloud.com/oauth2/v1/token \
 — header ‘authorization: Basic <base64 encoded clientID:ClientSecret>’ \
 — header ‘content-type: application/x-www-form-urlencoded;charset=UTF-8’ \
-d ‘grant_type=password&username=<username>&password=<password>&scope=<scope copied from resource section in IDCS confidential application>’

Here is an example command using the client ID and secret to get the base64 encoded string required by the IDCS API call described above:

echo -n “<Client ID>:<Client Secret>” | base64

We recommend you use a minimally privileged user in this use case, who only has access to data that is intended to be published publicly. Ideally, a separate OAC instance could be devoted to this scenario as well.

Once you’ve substituted all the <values> in that CURL command, running it from a command line should return an access token, for example (note that this example has been shortened to illustrate the point):

{“access_token”:”eyJ4NXQjUzI1NiI7IjB3c0tlVXZLUmVveVdnQjdJQ2tRXzcwS0dLZVY4YlZ4VGdxNzV0aWdTNh8iLCJ4NXQiOiIyTVEyWmtoWmMyV2h4RlV4QldBZEZ..<token shortened>…QhhiusAlI1qKPhHumRWf9u2VezW-2jw9bnOo9oeHGzCHfW7wPB86KPAxRBOTanECHyATGXFmFj5oRl2yziaJQiAS21PZu4Q”,”token_type”:”Bearer”,”expires_in”:100}

You’ll see that the token expires in 100 seconds and I describe how to increase that in a separate blog. For now, you can test this token will authenticate your OAC embedded content by copying the actual token into the following example HTML and deploying on your test web server or localhost (don’t forget to add suitable entries into the OAC safe domains page in the OAC console):

<!DOCTYPE HTML PUBLIC “-//IETF//DTD HTML//EN”>
<html>
  <head>
   <meta http-equiv=”Content-Type” content=”text/html; charset=utf-8">
   <title>Standalone DV Embed Demo Using Token</title>
   <script src=”https://<reference to embedding.js from OAC developer menu>” type=”application/javascript”>
   </script>
  </head>
 <body>
   <B>Standalone embedded project test</B>
   <div style=”width: calc(100% — 40px); height: (100% — 40px); border: 1px solid black; padding: 10px;” >
    <oracle-dv
    project-path=”<path to canvas being embedded>”
    active-page=”canvas”
    active-tab-id=”1">
    </oracle-dv>
   </div>
 <script>
  var token = “<copy token here>”;
  requirejs(['jquery', 'knockout', 'obitech-application/application', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'],
  function($, ko, application) {
  application.setSecurityConfig(“token”, {tokenAuthFunction:
  function(){
  return token;
  }
  });
  ko.applyBindings();
  }
  );
  </script>
 </body>
</html>

If everything works as expected, you’ll see your embedded OAC canvas appear, with no login prompt, for example :

If you see an error such as

“AJAX request failed during bootstrap. Request ‘https://<OAC-instance>-<tenancy>-ia.analytics.ocp.oraclecloud.com:443/ui/dv/ui/api/v1/sessioninfo/ext' response:”

then it’s likely your token has expired. In this case, obtain a new token to re-test.

Summary

Allowing public access to visual analytics from OAC is a popular use case. This blog series will explain how to achieve that using token based authentication that happens automatically when a user visits a web page hosting an embedded OAC canvas. In this first blog, I’ve explained how the overall solution is architected along with the initial steps to create and configure an IDCS confidential application that references your OAC instance as a resource. Once that configuration has been completed, I’ve shown how to test that the token is generated and how it can be used to make sure you’re able to see the OAC canvas without having to log in.

In the next blog in this series I’ll describe how to use the Oracle Functions and API Gateway Cloud services to seamlessly automate this authentication for public user access to your analytics insights.