Introduction

Oracle SaaS Cloud supports JWT token-based authentication in its REST and SOAP APIs in addition to the basic authentication mechanism. The JWT token allows a SaaS API client to embed a username or a principle in its token content and use it to authenticate with the SaaS cloud without specifying a password. This allows a customer to avoid hassles around password management. Of course, there is a cost associated with using the JWT token. This post intends to explain the steps required for using JWT token in place of the basic authentication.

There is a support document: How to Use JSON Web Token (JWT) For Authorization With Fusion Cloud Application REST APIs and SOAP Web Services ? (Doc ID 2572018.1) available for Oracle customers. Please review this document. This blog intends to provide more detailed information for customers who are new to JWT token.

Steps to Use JWT Token

1. Create a Private Key and Certificate Pair

A private key is used to sign your JWT token string. Its corresponding certificate is used by SaaS to verify the token signature and thus must be added to your SaaS instance described in the next step. The certificate can be self-signed (for development only) or signed by a CA with optional intermediate certificate authorities.

You can use different tools to create a key pair. The key algorithm must be RS256. JAVA users can use keytool to create a self-signed key pair. For example,

keytool -genkey -keyalg RSA -alias <aliasName> -keystore <keystoreFileName> -storepass <keystorePassword> -validity 3650 -keysize 2048

To export the certificate in base64 encoded .cer format:

keytool -exportcert -rfc -alias <aliasName> -file <certFile.cer> -keystore <keystoreFileName> -storepass <keystorePassword>

2. Upload Certificate to SaaS Instance via an SR

Create an SR in Oracle Support to request for certificate installation in your SaaS instance. Add a reference to the support doc (Doc ID 2572018.1) mentioned above in the SR. Upload your self-signed certificate file to the SR and indicating it is self-signed. If not self-signed, upload all CA and intermediate certificate files along with your own certificate file. 

The issuer's name must be also specified in the SR by the SR creator as part of the information used in installing the certificate. The issuer's name must be specified in your JWT token in the "iss" attribute. It must match the name used when installing your certificate.

3. Create a Program to Generate and Sign JWT Token

There is a variety of libraries in different programming languages available for creating and signing a JWT token. JAVA users can check out my other blog, Create a JWT Token in Java for Oracle IDCS, for detailed information on how to create such a program in JAVA.

4. Specify Values for JWT Token Attributes

The required attributes and format are described in the support document Doc ID 2572018.1. Among them, the "x5t" attribute needs a little more attention.

4.1 Specify Value for the "x5t" Attribute

The "x5t" attribute is a base64 encoded public certificate fingerprint. To obtain your certificate's fingerprint using JAVA keytool, 

keytool -printcert -file <certficateFile.cer>, or

keytool -list -keystore <keystoreFileName> -storepass <keystorePassword>

The SHA1 (not the SHA256) fingerprint value should look like the following:

68:54:DF:C7:23:C2:02:9F:BE:01:C4:C1:5B:3D:89:0E:3D:9A:CC:A3

Remove the : from the string and it becomes

6854DFC723C2029FBE01C4C15B3D890E3D9ACCA3

This is the hex value of your certificate's fingerprint. The next step is to encode this hex value using hex to Base64 encoding. The Base64 Guru is one place to do it.

5. Use JWT Token in API Calls

To use the JWT token you created in your REST or SOAP call to SaaS, add an HTTP header "Authorization" with the value of

Authorization: Bearer your-jwt-token-string