Using a JavaScript Object Notation Web Token with Oracle Fusion Analytics

April 12, 2023 | 12 minute read
Krishna Prasad Kotti
Senior Member of Technical Staff
Text Size 100%:

REDWOOD

Updated November 14, 2023, for additional guidance on waiting after uploading a public certificate.

Introduction

Oracle Fusion Analytics (Fusion Analytics) is a family of prebuilt, cloud-native analytics services that run on Oracle Cloud Infrastructure. About Fusion Analytics provides an overview.

The JavaScript Object Notation (JSON) Web Token, or JWT, is the recommended authentication method used by Oracle Fusion Cloud Applications to authenticate the Fusion Analytics extraction and health check services.

Password-based authentication is an alternative method described in an upcoming companion blog.

Oracle recommends the JWT-based method over the password-based method because it offers increased security and decreased maintenance. It increases security by authenticating Fusion Analytics services and not the Fusion Analytics service administrators who possess the service account password. It decreases password maintenance when patches and updates occur and when the passwords expire.

RECOMMENDED1

Refer to the Oracle Fusion Cloud Applications Authentication documentation for more information.

This article describes configuring Oracle Fusion Cloud Applications and Fusion Analytics to use the recommended JWT-based authentication method. It offers guidance for those transitioning from password-based authentication and those provisioning new Fusion Analytics instances. It includes architectural diagrams, component descriptions, deployment instructions, and links to reference material.

Acronyms Used
Acronym Meaning
FIPS Federal Information Processing Standards
PKCS Public Key Cryptography Standards
RSA Rivest–Shamir–Adleman Algorithm
API Application Programming Interface
   

REDWOOD

Architecture Transitioning Illustrations

Transistioning JWT Initial

Transistioning JWT Configured


Provisioning Illustrations

Provisioning JWT Initial

provisioning JWT configured


Components

The configured architecture has these additional components:

  • RSA Private Key
  • x509 Self-Signed Certificate
  • Oracle Fusion Cloud Applications API Identity Provider
RSA Private Key

An RSA private key is used to create certificates and RSA public keys for authentication and must be kept secret.

x509 Self-Signed Certificate

A self-signed certificate and RSA public key are created using the RSA private key.

Oracle Fusion Cloud Applications API Identity Provider

Authentication providers prove the identity of users and system processes.
The Oracle Fusion Cloud Applications API Identity Provider contains certificates. Each public key certificate is accessible using the corresponding private key.


REDWOOD

Deploy Deployment Prerequisites

Ensure the RSA private key complies with the PKCS #1 standard.
Oracle Fusion Cloud Applications Java Web Tokens require this standard.
A PKCS#1 private key contains "BEGIN RSA PRIVATE KEY" in the first line.

Troubleshooting Tip: A FIPS-compliant operating system may be configured to disallow PKCS #1 private keys.

The examples use OpenSSL to generate the private key and certificate.
* Check the OpenSSL Downloads documentation for the latest supported and unsupported releases.
   As of April 2023,
    The latest stable version is the 3.1 series, supported until March 14th, 2025.
    The 3.0 series, a Long Term Support version, is supported until September 7th, 2026.
    The 1.1.1 series, a previous version, is only supported until September 11th, 2023.
* Old versions (including 1.1.0, 1.0.2, 1.0.0, and 0.9.8) are now out of support and should not be used.
* After downloading and installing the latest version, ensure the PATH environment variable is correct.

* Use 4096 as the value for the last (numbits) parameter in the RSA private key command. This parameter controls the size of the private key in bits.
* Values less than 2048 are not supported.
* Values less than 512 are not allowed.

* Ensure the certificate does not contain carriage-return characters. Oracle Fusion Cloud Applications does not support the carriage-return character, only the line-feed / new-line character.

Note: The command in the example creates a private key and determines the PKCS standard.
If the standard is not PKCS #1, it must be recreated using the traditional option of OpenSSL.

The deployment topics are:

  • Preparations
  • Oracle Fusion Cloud Applications API Identity Providers
  • Transitioning to JWT-based Authentication
  • Provisioning with JWT-based Authentication
  • Validating JWT-based Authentication
Preparations
Software Required

The examples in this post use the OpenSSL toolset.

An Apple Mac, by default, may use LibreSSL. Run openssl version to determine the software and version used.
Currently LibreSSL produces RSA private keys in the correct format.
CloudShell in Oracle Cloud Infrastructure also produces RSA private keys in the correct format.

Platform Required

Any platform that produces PKCS #1 RSA private keys.


Privileges Required

Ensure you have the following Oracle Fusion Cloud Applications role for uploading the public certificate:


Generating an RSA Private Key

Run the OpenSSL commands to create an RSA private key, e.g., jwt_private.key and the public key certificate, e.g., jwt_publickey.cer.

The command below creates a private key and determines the PKCS standard.
 "The key is using the PKCS #1 standard" is displayed if the PKCS #1 standard is used.
"The key is not using the PKCS #1 standard" is displayed if it is not.

If the key is using the PKCS #1 Standard, the command creates the public key certificate.

cat <<EOF >cr-jwt-key.sh
set echo off; openssl genrsa -out jwt_private.key 4096 >null 2>>null; chmod 600 jwt_private.key;
head -1 jwt_private.key |grep 'BEGIN RSA'; rc=\$?;
head -1 jwt_private.key |grep 'BEGIN RSA' && echo "The key is in PKCS #1 format" || echo "The key is not in PKCS #1 format";
set echo on;

[ \$rc -eq 0 ] || exit

openssl req -new -x509 -key jwt_private.key -out jwt_publickey.cer -days 365 <<EOC
US
CA
.
FAW
.
.
.
EOC

echo "The private key and public certificate are created."
ls -ltr jwt*

EOF

$SHELL cr-jwt-key.sh

If both the private key and public certificate are created, proceed to the Oracle Fusion Cloud Applications API Identity Providers section.

If the key is not in PKCS #1 format, it must be recreated using the OpenSSL traditional option.

The command below determines if the traditional option is available.
"The traditional option is available" is displayed if it is, the private key is recreated, and the public certificate created.
"The traditional option is not available" is displayed if it is not.

cat <<EOF >check-traditional.sh
set echo off
openssl genrsa -traditional >null 2>>null; rc=\$?;
openssl genrsa -traditional >null 2>>null && echo "The traditional option is available." || echo "The traditional option is not available. Install OpenSSH."
[ \$rc -eq 0 ] || exit


set echo off; openssl genrsa -traditional -out jwt_private.key 4096 >null 2>>null; chmod 600 jwt_private.key; 
head -1 jwt_private.key |grep 'BEGIN RSA'; rc=\$?; 
head -1 jwt_private.key |grep 'BEGIN RSA' && echo "The key is in PKCS #1 format" || echo "The key is not in PKCS #1 format"; 
set echo on; 
[ \$rc -eq 0 ] || exit 

set echo off
openssl req -new -x509 -key jwt_private.key -out jwt_publickey.cer -days 365 <<EOC
US
CA 
.
FAW
.
.
.
EOC
echo "The private key and public certificate are created."
set echo on 
ls -ltr jwt* 

EOF



$SHELL check-traditional.sh

If both the private key and public certificate are created, proceed to the Oracle Fusion Cloud Applications API Identity Providers section.

If the traditional option is unavailable, expand the selection below and install the latest version of OpenSSL.

Refer to OpenSSL on Github for guidance with operating systems other than MAC-OS.

Different methods exist for installing OpenSSL on an Apple Mac.

One method downloads and installs the software from Github. Another uses Homebrew.

This section uses a method from the Mac App Store that scripts the Homebrew method.

Open the link for the latest instructions. If necessary, use these steps validated in August of 2023.

1. Open the prebuilt Apple Terminal application and run the following preparation commands. Sudo root access may require and prompt for the Mac password. Wait patiently for the command to finish, as it can take a while.

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
(echo; echo 'eval "$(/opt/homebrew/bin/brew shellenv)"') >> /Users/dcarley/.profile
eval "$(/opt/homebrew/bin/brew shellenv)"

 2. If all went well above, run the following to install opensll

brew install openssl
which openssl
openssl version


Rerun the OpenSSL command with the traditional option
cat <<EOF >cr-traditional-jwt-key.sh 
set echo off
openssl genrsa -traditional -out jwt_private.key 4096 >null 2>>null
head -1 jwt_private.key |grep 'BEGIN RSA' && echo "The key is in PKCS #1 format" || echo "The key is not in PKCS #1 format" 
set echo on
EOF

[ -f /bin/sh ] &&sh cr-traditional-jwt-key.sh ||zsh cr-traditional-jwt-key.sh


Generating an x509 Self-Signed Certificate

This example generates a self-signed certificate that expires in 365 days. Adjust the lifetime to meet your requirements.

Note: This command also generates a certificate to replace an expired one.

Run an OpenSSL command using the private key above to create an x509 self-signed certificate, e.g., jwt_publickey.cer.

openssl req -new -x509 -key jwt_private.key -out jwt_publickey.cer -days 365 <<EOF
US
CA
.
FAW
.
.
.
EOF


Oracle Fusion Cloud Applications API Identity Providers

View the Oracle Fusion Cloud Applications API Identity Providers

View and determine if the FAWServiceJWTIssuer exists.

  • Sign in to the Oracle Fusion Cloud Applications environment.
  • Navigate to Tools > Security Console.
  • Click API Authentication.

View the list and determine if the FAWServiceJWTIssuer provider exists.


Creating an Oracle Fusion Cloud Applications API Identity Provider

If the FAWServiceJWTIssuer provider does not exist, create it.

Click + Create Oracle API Authentication Provider.


Updating an Oracle Fusion Cloud Applications API Identity Provider

If the FAWServiceJWTIssuer provider exists, update it.

Note: Uploading a replacement certificate requires updating the provider.


Adding a Public Key Certificate to an Oracle API Authentication Provider

Whether creating a new provider or updating an existing one, upload the public key certificate.

Click
ADDCERTICATE

  • Click + Add New Certificate.
    • Enter a suffix for the *Certificate Alias, e.g., DevFusionAnalytics.
    • Click Browse for *Import Public Certificate and upload the x509 self-signed certificate, i.e., jwt_publickey.cer
      Browse
    • Click Save
    • Click Done

Important! After uploading the certificate, wait at least 30 minutes before using it in Fusion Analytics.


Transitioning to JWT-based Authentication

Oracle recommends transitioning to JWT-based Authentication if you currently use Password-based Authentication.

  • Sign in to the Oracle Cloud Infrastructure console.
  • Choose your region and compartment.
  • Navigate to Analytics & AI > Fusion Analytics Warehouse.
  • Click the Fusion Analytics Display Name.
  • Click Update Fusion Connection.
  • Next, follow the steps in Enabling JWT-based Authentication and Validating JWT-based Authentication.
  • Then, Click Save Changes

Provisioning with JWT-based Authentication

Oracle recommends provisioning with the JWT-based authentication method.

  • The Authentication panel is displayed in the Fusion Application Connection section of the provisioning graphical user interface.
  • Next, follow the steps in Enabling JWT-based Authentication.
  • Then, complete the remainder of the Provisioning dialog.

Enabling JWT-based Authentication

Complete the Authentication dialog, whether transitioning an existing instance or provisioning a new one.

  • Click JWT Based Authentication.
  • Browse and select the Private Key, i.e., jwt_private.key.
  • Browse and select the Public Certificate, i.e., jwt_publickey.cer.
  • Check the box for Keys have been uploaded to Fusion Source.

ENABLEJWT1


Validating JWT-based Authentication

Whether transitioning an existing instance or provisioning a new one, validate the method by clicking Validating1 after completing the Authentication dialog.

Note: As of Update 23.R1, a message may not appear informing you that a connection test failed.
* Ensure you see the message "Fusion application credentials are valid".

JWT Token Test Connection Credentials are Valid


REDWOOD

Explore More

You have now configured Oracle Fusion Cloud Applications and Fusion Analytics to use a JWT for authentication.

Explore more about the components and usage of this feature using these links:

Switch to use JWT authentication
Resetting a Service Account Password
Get Started with Oracle Fusion Analytics
Featured and Recent Fusion Analytics Blogs

REDWOOD

Dayne Carley

Ravi Guddanti

Krishna Prasad Kotti

Senior Member of Technical Staff


Previous Post

Best Practices for Case Statements in Oracle Analytics

Paul Benedict | 4 min read

Next Post


Oracle named a Visionary in the 2023 Gartner® Magic Quadrant™ for Analytics and Business Intelligence Platforms

James Richardson | 2 min read