Updated May 17, 2024, for additional guidance on waiting after uploading an X.509 certificate.
Updated November 14, 2023, for additional guidance on waiting after uploading an X.509 certificate.
Updated June 7, 2024, for additional guidance on using Windows, validation, and troubleshooting.
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 that Oracle Fusion Cloud Applications uses 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.
Refer to the Fusion Cloud Applications Authentication documentation for more information.
This article describes configuring 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 |
Topics
- Architecture
- Deploy
- Validate
- Transition
- Troubleshoot
Provisioning Illustrations
Components
The configured architecture has these additional components:
- RSA Private Key
- X.509 Certificate
- Fusion Cloud Applications API Identity Provider
An RSA private key is used to create X.509 certificates and RSA public keys for authentication and must be kept secret.
X.509 CertificateAn X.509 certificate is a digital certificate that uses the international X.509 public key infrastructure (PKI) standard and verifies the public key contains the private key used in connections.
Fusion Cloud Applications API Identity ProviderThe Fusion Cloud Applications API Identity Provider contains an X.509 certificate and validates Fusion Analytics connections.
A Fusion Analytics project team member creates an RSA private key and an X.509 certificate.
A Fusion Cloud Applications administrator configures Fusion Cloud Applications API Authentication.
Topics- Prepare
- Generate a Private Key and X.509 Certificate
- Configure Fusion Cloud Applications API Authentication
The examples in this post use the OpenSSL toolset.
Download OpenSSL from OpenSSL Downloads if necessary.
An Apple Mac, by default, may use LibreSSL. This is OK.
Run the following command in a terminal or PowerShell session to determine the software and version used.
openssl version
Platform Required
Any platform that can produce PKCS#1 RSA private keys.
Privileges Required
The administrator uploading the X.509 certificate to Fusion Cloud Applications must be assigned the IT_Security_Manager role.
Generate a Private Key and X.509 Certificate
Copy, paste, and run the commands below to create a private key and determine the PKCS standard.
* 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.
* Values less than 2048 are not supported.
* Values less than 512 are not allowed.
The PKCS #1 standard is used if the first line displayed contains “BEGIN RSA PRIVATE KEY”.
Using Linux and MAC
Use a terminal session to run the commands.
mkdir JWT_KEYS; cd JWT_KEYS; openssl genrsa -out jwt_private.key 4096; chmod 600 jwt_private.key; cat jwt_private.key;
If the format is not in PKCS#1 format, run the command below to create a private key using the -traditional option.
openssl genrsa -traditional -out jwt_private.key 4096; chmod 600 jwt_private.key; cat jwt_private.key;
Using Windows PowerShell
Use a PowerShell session to run the commands.
mkdir JWT_KEYS; cd JWT_KEYS; openssl genrsa -traditional -out jwt_private.key 4096; type jwt_private.key
If the key is still not in the PKCS#1 standard or you see an error regarding the -traditional option, stop and ensure you have the latest version of OpenSSL.
Generate an X.509 Certificate
Copy, paste, and run the command below to create an X.509 certificate using the private key.
You are prompted for optional information. The email address at the end helps to identify the certificate in Fusion Cloud Applications. Enter optional values and click return until the command ends.
* Ensure the certificate does not contain carriage-return characters. Fusion Cloud Applications does not support the carriage-return character, only the line-feed / new-line character.
openssl req -new -x509 -key jwt_private.key -out jwt_publickey.cer -days 365
Configure Fusion Cloud Applications API Authentication
The Fusion Cloud Applications administrator configures Fusion Cloud Applications API authentication.
- Sign in to Fusion Cloud Applications.
- Navigate to Tools>Security Console.
- Click API Authentication.
- View the list and determine if the FAWServiceJWTIssuer provider exists.
Create the API Provider (if necessary)
- Sign in to Fusion Cloud Applications.
- Navigate to Tools>Security Console.
- Click API Authentication.
- Click + Create Oracle API Authentication Provider.
- Click Edit.
- Enter FAWServiceJWTIssuer as the Trusted Issuer.
Note: The name FAWServiceJWTIssuer is not optional.
- Check the JWT Token Type box.
- Click Save and Close.
- Click + Create Oracle API Authentication Provider.
Upload the X.509 Certificate
- Sign in to Fusion Cloud Applications.
- Navigate to Tools>Security Console.
- Click API Authentication.
- Click the FAWServiceJWTIssuer Trusted Issuer.
- Click Edit.
- Click
- Click + Add New Certificate.
- Enter a suffix for the *Certificate Alias, e.g., DevFusionAnalytics.
- Click Browse for *Import Public Certificate and upload the X.509 certificate, i.e., jwt_publickey.cer
- Click Save
- Click Done
Important! After uploading the certificate, wait at least 15 minutes before using it in Fusion Analytics.
The designated Fusion Analytics service administrator validates the private key and X.509 certificate.
If transitioning a Fusion Analytics instance to use the JWT key pair, proceed to the Transition section below.
One validation method is to:
- Begin to create a new Fusion Analytics instance.
- Upload the private key and certificate and test the connection.
- Cancel the Fusion Analytics instance creation.
Follow the steps below:
- Sign into the OCI (Oracle Cloud Infrastructure) identity domain designated for the Fusion Analytics environment.
- Navigate to Analytics & AI>Data Intelligence.
- Click Create Instance.
- In the Fusion Applications Connection section:
- Enter the Fusion Applications URL of the environment containing the X.509 certificate.
- 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.
- Click
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“.
- Click Cancel to exit the process.
The Fusion Analytics service administrator updates the Fusion Cloud Applications connection in Fusion Analytics.
- Sign into the OCI (Oracle Cloud Infrastructure) identity domain designated for the Fusion Analytics environment.
- Navigate to Analytics & AI>Data Intelligence.
- Click the instance Display Name being transitioned.
- Click Update Fusion Connection.
- In the Authentication section:
- 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.
- Click
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“.
- Click Save Changes.
The designated Fusion Analytics service administrator and the Fusion Cloud Applications administrator troubleshoot issues.
If the validation fails using the method, verify the following first before opening an SR (Service Request) with Oracle Support:
- Ensure the private key is a PKCS #1 RSA private key.
- Ensure the Fusion Cloud Applications API Provider/Trusted Issuer is named exactly FAWServiceJWTIssuer in the Fusion Cloud Applications environment.
- Ensure the JWT box is checked for the Fusion Cloud Applications API Provider/Trusted Issuer.
- Ensure the public key certificate has been uploaded to the Fusion Cloud Applications API Provider/Trusted Issuer and enough time has been allowed for it to be available.
- Ensure the X.509 certificate and private key contain identical private key values. Run the following commands
openssl x509 -noout -modulus -in jwt_publickey.cer; openssl rsa -noout -modulus -in jwt_private.key;
You have now configured Oracle Fusion Cloud Applications and Fusion Analytics to use 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