Overview of the Recipe

You can authenticate REST API calls with JSON Web Tokens, which eliminate password expiration and enable you to have better control of password management.

REST API calls are commonly used when performing day-to-day activities like loading and fetching data. A password is required each time a REST API is called and comes with an expiration time that must be managed in the system. Authentication with JSON Web Tokens (JWT) eliminates password expiration and enables you to have better control of password management.

For inbound REST API integrations, the client generates a signed JWT and exchanges it for an Oracle access token to call secured REST resources.

Key features:

Generates a unique token for every REST API call.
Lets you use the same token for multiple REST API calls.
Lets you control how long you can access the token – from a few seconds to a few days.
Is very easy to use.

JWTs consist of three parts, separated by dots (.):

Header
Payload
Signature

Therefore, a JWT typically looks like this:

xxxxx.yyyyy.zzzzz

Part	Description
Header	The header consists of three parts: The signing algorithm being used, such as HMAC SHA256 or RSA. The token type, which is JWT. The x5t, which is the base64 encoded fingerprint of the trusted issuer certificate. (Sourced from your newly created X509 key pair.)
Payload	The payload, which contains the claims. Claims are statements about an entity (typically, who the user is) and any additional data. There are three types of claims: registered, public, and private.
Signature	To create the signature part, you must sign the encoded header and encoded payload using the secret and the algorithm declared in the header. This is used as the Message Authentication Code (MAC).

The payload is constructed based on the rules shown in the table.

Abbreviation	Meaning	Description
iss	Issuer	Issuer name
prn	Principal	The user name of user who has the required privileges to integrate with Oracle Fusion Cloud Fusion Applications using REST APIs.
aud	Audience	A string or array of strings identifying the recipients that the JWT is intended for. For example, `https://users.dummy.com`.
iat	Issued at	Unix epoch time format of when the token was generated. For example, 1596271154 for 08/01/2020 @ 8:39am (UTC).
exp	Expiration	Unix epoch time format of when the token will expire. For example, 1918081154 for 10/13/2030 @ 12:19am (UTC).

Integration Objective

The objective of this recipe is to enable secure and scalable inbound integration with Oracle Fusion Cloud SCM using REST APIs authenticated with JWTs, replacing basic authentication mechanisms for long-running or automated integrations.

Use Case

This use case serves as an example of how you might implement a recipe for specific requirements.

Daily Operational REST API Calls

Traditional user-name and password-based authentication when making REST API calls requires managing expiring passwords, which might lead to service disruptions if not updated. In this use case, you're authenticating REST API calls using JWTs, which don't expire, thereby enabling uninterrupted integration.

Process Overview

Details of the steps you take when designing and implementing the use cases are described in these topics:

Best Practices and Constraints

Here are some recommended best practices and constraints to consider.

Best Practices

Use short-lived JWTs and refresh them often.
Automate token generation and refresh as part of the integration flow.
Grant the user specified in the prn claim only the minimum privileges required.
Use a key vault or secrets manager to store the private key securely.
Use audit logs or integration middleware to monitor token usage and failures.

Constraints

Requires manual setup in the Oracle Fusion Cloud Applications Security Console.
You must manage JWT expiration carefully when running long-running or batch jobs.
Roles must be properly assigned. JWTs don't override Oracle Fusion Applications' role-based access control (RBAC).
JWTs must be signed using a private key and must match the public certificate that was uploaded.

Before You Begin

Ensure that you have:

Enabled an Oracle Fusion Cloud SCM environment with all required REST APIs.
Been assigned a role that lets you access the Oracle Fusion Cloud Applications Security Console (where you'll create an API Authentication provider).
Access to tools you can use to generate a private/public key pair (for example, OpenSSL) and to make REST API calls (for example, Postman).
Are familiar with JWT structure, encoding, and generation.