article by Frank Nimphius, March 2020
The new Oracle Web SDK allows you to integrate Oracle Digital Assistant in websites or web applications. The Oracle Web SDK has 4 security features that you can leverage for your chatbot conversations:
- The Oracle Web SDK uses secure web socket layer (wss) to communicate between the messenger client and the chat server
- By default, and configurable through a setting, the Oracle Web SDK enforces the hosting website to use HTTPS as a protocol
- Domain whitelisting allows you to restrict the sites that can host the web messenger for a Oracle Web SDK channel. Whitelisting is set per Oracle web channel and thus for each skill or digital assistant exposed on the web
- JSON Web Tokens (JWT) are signed tokens that authenticate the client and user. If the token signature does not match a channel generated secret key, or if the token has expired, then no access is possible to digital assistant
In a previous TechExchange article I explained how to generate JWT tokens using a remote service. Generating JWT tokens remotely and not as part of the Oracle Web SDK is the recommended and secure way of creating tokens. However, for development and testing you may look for a fast and easy option to create tokens, in which case generating JWT tokens locally becomes handy.
In this article I explain how you can create JWT tokens locally.
Note: This option of generating JWT tokens locally is not an option for digital assistant bots in production.
—-
Security Note: In terms of security, I recommend that you always use a separate Oracle Digital Assistant instance in its own OCI compartment for development and testing. This recommendation is not based on potentially locally generated JWT tokens, but on the human factor. During development and testing, you may need to relax security settings, which you don't want to apply to your production bots. Read this article about creating Oracle Digital Assistant instances in their own OCI compartment.
—-
Note: This SDK works with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure), which means Oracle Digital Assistant version 20.x and later. If you are on an earlier cloud version, there exists a JavaScript SDK for this as well, though with a reduced set of features compared to the Oracle Web SDK.
Downloading Oracle Web SDK
Make sure you download the latest version of the Oracle Web SDK. You find the SDK in the Oracle Native Client SDKs (for OCI Native environments) section of the following Webpage: https://www.oracle.com/downloads/cloud/amce-downloads.html
Creating a Oracle Web Channel
You create a new Oracle Web Channel by pressing the + Channel button in the channels page (you access the channels page from the hamburger icon on top of the Oracle Digital Assistant instance main page).
Select Oracle Web as the Channel Type, provide a unique name and set Allowed Domains to your domain or use an * (asterisk) character to indicate access for all domains. When specifying a domain, ensure you add a leading https:// . You can use the * character as a wildcard in the domain name.
Note: For this article, please set the Allowed Domains to *. The reason is that, at the end, you will run the sample web page locally on your computer (so no domain involved)
Client Authentication is enabled by default and enforces the requirement for JWT tokens to be used to authorize client access. Click Create to create a new channel configuration,
Next, edit the new channel configuration by assigning a digital assistant or skill to it and switching the Channel Enabled toggle to on.
The channel configuration has also generated a Channel ID and a Secret Key. Take a note of the two, as ell as the host URI of your Oracle Digital Assistant instance (the URI should not include the https:// protocol and no training slash ("/").)
Note: Client Authentication enforces the use of JSON Web Tokens (JWT). In production you should use a backend server to generate these tokens using the Secret Key generated from the Oracle Web channel. The Web Messenger sends the token to the chat server after establishing connection. The Oracle chat server then uses the channel secret key to verify the signature. Only when the signature is valid, the chat server then reads the channel Id from the token to connect to the Web channel.
Editing the Oracle Web SDK Sample for a Quick Start
Extract the downloaded ZIP file to your local file system. Notice that the extracted content contains a samples folder with a web folder in it. The web folder contains an index.html file, as well as a scripts folder. You can use the index.html file to test your digital assistant or skill on the Web channel. So even before configuring the web SDK to your own web application or web site, you are ready to go.
To configure the index.html sample page, navigate to the scripts folder and open the settings.js file.
Edit line 21 with the URI of your Oracle Digital Assistant instance. The URI should look similar to: oda-db<your instance id>.data.digitalassistant<…>.com.
Enabling Client Authentication and Generate JWT Tokens Locally
Scroll down to the bottom of the settings.js page. Edit lines 56 and 59 with the channel Secret Key and the Channel ID. Now you should also understand why local JWT token generation is not suitable for production environments. The settings.js file content can be debugged in a browser once the index.html page loads, which means that the secret key no longer is kept secret.
Next, navigate to line 62 and notice a comment in line 61. The comment tells you that local JWT generation is not implemented (which actually is the justification for this article). Change the generateToken function name to generateJWTToken (if in a future version of the sample the function name changes, then still change it to generateJWTToken).
Next, add the following code block to the bottom of the settings.js file.
var generateJWTToken = function(header,data,secret){
// Header
var oHeader = header;
// Payload
var oPayload = data;
var sHeader = JSON.stringify(oHeader);
var sPayload = JSON.stringify(oPayload);
var sJWT = KJUR.jws.JWS.sign("HS256", sHeader, sPayload, secret);
return sJWT;
}
Your settings.js file should look as shown in the image below:
Save the file.
—
Note: As you can see in line 57 in the image above, the user Id is set to "abc". This actually makes it a single use environment. To make this a multi user environment, generate the user ID (e.g. from the current Date-Time, or authenticate users and pass the ID to the function. The same is required when you generate the token remotely. If you forget to generate the user Id, then a problem you get reported from users will be that they all see the same conversation. The user Id is used as a session ID, which explains this behavior. So please make sure, when testing in a multi – user environment, that you generate unique user Ids.
—
Next, open the index.html file in a text editor. As you may have noticed, the generate JWTToken function in the settings.js uses a JavaScript library to create the message signature for the token.
Note: For this article I am using jsrsasign (https://github.com/kjur/jsrsasign/wiki/Tutorial-for-JWT-generation). You can use any library you want for as long as it can be used within a browser. If you choose your own library, ensure you change the code in the generateJWTToken function.
Edit the index.html file and add the following script tag to the document's header:
<script src="https:__kjur.github.io_jsrsasign_jsrsasign-latest-all-min.js\"></script>
Next, edit line 21 of the index.html file and set it to clientAuthEnabled = true; . This ensures the index.html file to call the functions in the settings.js file to generate the JWT token.
Save the HTML file.
Testing the Secured Web Channel
Double click the index.html file to test the conversation. You should see a bot icon as shown below.
Note: If you don't see a bot icon, check your JavaScript and HTML file edits for missing information or syntax errors.
Next, click onto the the bot icon to open the messenger. Type a message into the Message field to start the conversation. If you don't see the conversation getting through to the bot, check the channel ID and secret key settings, as well as the Oracle Digital Assistant URI. Below is the bot response for the pasta skill I used.
Debugging
By experience, what can go wrong will go wrong once in a while. If you experience a problem setting up local JWT generation, use the browser console option. The screen shot below shows how to open the JavaScript console for Google Chrome.
Learning About Web SDK Features and Settings
Beside of the Oracle Web SDK documentation and Oracle TechExchange article, the Oracle Web SDK comes with a user guide you can read to learn about settings and properties.
Related Content
TechExchange: Getting Started With Oracle Digital Assistant on Oracle Cloud Infrastructure (OCI)
TechExchange: Integrate Oracle Digital Assistant Web SDK in Visual Builder Cloud projects
TechExchange: All 2-Minutes Oracle Digital Assistant Tech Tip Videos on YouTube
