JSON Web Tokens (JWT) have gained popularity for authentication and authorization in web applications and APIs. It’s a standardized (RFC 7519) and secure way to identify users and prevent unauthorized access. Many SaaS provider such as Salesforce, Snowflake, Atlassian, Twilio, Shopify etc. support JWT based authentications flows. The security aspect is provided by cryptographic methods that allow signing and optional encryption of the token. This article will focus on signing a JWT. For details about JWT encryption find more in this article.

The signing can be done with:

• HMAC (Hash-based Message Authentication Code)

• RSA or ECDSA (Asymmetric cryptographic algorithms)

HMAC is a symmetric approach in which both client and server share the same secret key while RSA is an asymmetric method with a public and private key where the private key is used to sign the token and the public key to verify it.

A JWT is typically composed of three parts divided by dots “.” :

HEADER . PAYLOAD . SIGNATURE

The header contains just meta data about the used cryptographic method:

{
  "alg": "HS256",
  "typ": "JWT"
}

The payload contains the claims like user id, issuer, expiration time etc. The payload should never contain sensitive information like passwords as in case of an unencrypted JWT the payload is not protected. More details can be found in the Wiki.

{
    "sub": "user-id",
    "iss": "https://salesforce.com",
    "iat": 1615370644,
    "exp": 1615374184
}

Header and payload are then Base64 encoded.

So the header becomes “eyJhbGciOiAiSFMyNTYiLCJ0eXAiOiAiSldUIn0” and the playload “eyJzdWIiOiJ1c2VyLWlkIiwiaXNzIjoiaHR0cHM6Ly9zYWxlc2ZvcmNlLmNvbSIsImlhdCI6MTYxNTM3MDY0NCwiZXhwIjoxNjE1Mzc0MTg0fQ“.

The signature is created with header and payload Base64 encoded. All three parts form the JWT which can be used to authenticate against an API.

The problem

Oracle APEX provides a PL/SQL package which deals with JSON Web Tokens. It’s called APEX_JWT. If you open the documentation a note is hard to miss:

APEX_JWT APIs only support HS256 symmetric encryption algorithm for claim signatures. Asymmetric encryption algorithms such as RS256 are not supported.

If your API supports HS256 cryptographic algorithm for signing the JWT you can use the apex_jwt.encode() function. The result is a signed JWT (Note: in the documentation for this function it is written “… function encodes and optionally encrypts payload.” however the JWT is signed but not encrypted, so the payload is still pure Base64 encoded!)

Many API providers (e.g. Snowflake SQL REST API) require a (stronger) RS256 cryptographic algorithm for which the Oracle APEX PL/SQL API does not support us. There is a feature request for APEX with status “currently on the roadmap for a future release” however even with currently newest APEX version 24.2 it is still not supported. Connor McDonald stated on Ask Tom recently:

But ultimately, APEX_JWT is an API layer built on top of the DBMS_CRYPTO package, which in 19c does not full public key support, and hence RS256 is not available.

DBMS_CRYPTO does get that support in 21 and 23ai, but 99% of customers are still on 19c.

Of course, there has been 28 RUs of 19c and hence DBMS_CRYPTO has continued to evolve in 19c as well, so hopefully it will come in due course to APEX.

A solution

As java is a highly integrated programming language in Oracle Database my idea was to create a java class to create a JWT using RS256 cryptographic algorithm.

Here my implementation (JwtGenerator.java):

package orajwt;

import java.util.Base64;
import java.security.*;
import java.security.spec.*;

public class JwtGenerator {

    /**
     * Create a JSON Web Token (JWT) and sign it with an RSA256 private key
     * @param iss Issuer of the token
     * @param sub Subject of the token
     * @param iat Issue time for the JWT in UTC (equals current time value as seconds)
     * @param exp Expiration time for the JWT in UTC (seconds)
     * @param privateKey RSA256 private key used to sign the token
     * @return The generated JWT as String
     * @throws Exception
     */
    public static String rs256Encode(String iss, String sub, Long iat, Long exp, String privateKey) 
            throws Exception {

        String header = "{\"alg\":\"RS256\",\"typ\":\"JWT\"}";
        String headerEncoded = Base64.getUrlEncoder()
                                     .withoutPadding()
                                     .encodeToString(header.getBytes("UTF-8"));

        String payload = "{\"iss\":\"" + iss + "\",\"sub\":\"" + sub + "\",\"exp\":" + exp + ",\"iat\":" + iat + "}";
        String payloadEncoded = Base64.getUrlEncoder()
                                     .withoutPadding()
                                     .encodeToString(payload.getBytes("UTF-8"));

        // private key needs to get rid of begin/end blocks and any whitespace
        privateKey = privateKey.replace("-----BEGIN PRIVATE KEY-----", "")
                               .replace("-----END PRIVATE KEY-----", "")
                              .replaceAll("\\s+","");

        String jwt = headerEncoded + "." + payloadEncoded;

        // generate the signature for the JWT
        byte[] decodedKey = Base64.getDecoder().decode(privateKey);

        PKCS8EncodedKeySpec keySpec = new PKCS8EncodedKeySpec(decodedKey);
        KeyFactory kf = KeyFactory.getInstance("RSA"); 
        PrivateKey rsaPrivateKey = kf.generatePrivate(keySpec);

        Signature privateSignature = Signature.getInstance("SHA256withRSA");
        privateSignature.initSign(rsaPrivateKey);

        privateSignature.update(jwt.getBytes("UTF-8"));
        String signatureEncoded = Base64.getUrlEncoder()
                                 .withoutPadding()
                                 .encodeToString(privateSignature.sign());

        return jwt + "." + signatureEncoded;
    }
}

The rs256Encode() method supports standard JWT claims “iss”, “sub”, “iat” and “exp”.

To upload the class file to Oracle Database a utility named loadjava exists. I took my favorite IDE Eclipse compiled the java file and exported the class file to a jar file. Make sure to compile the java file for the destination JVM running in the database. In my case it was Java8 running on 19c. Then I could run load java:

loadjava -u user@database -v -r orajwt-1.0.jar

To verify the loaded java class in the database run this SQL command:

SELECT object_name, object_type, status FROM all_objects WHERE object_type like '%JAVA%' and lower(object_name) like '%orajwt%';

The status should be “VALID”.

Next create a PL/SQL wrapper function to access the java method from PL/SQL:

   /** 
    * Create JSON Web Token (JWT). 
    * This is a PL/SQL wrapper function for java method "JwtGenerator.rs256Encode" from orajwt package
    * @param p_iss The issuer of the token
    * @param p_sub The subject of the token
    * @param p_iat Issue time for the JWT in UTC (equals current time value as seconds) 
    * @param p_exp Expiration time for the JWT in UTC (seconds)
    * @param p_private_key RSA256 private key for signing the JWT
    * @return The JWT as String
    */
    function create_JWT(
       p_iss         in varchar2,
       p_sub         in varchar2,
       p_iat         in number,
       p_exp         in number,
       p_private_key in varchar2
    ) return varchar2 as language java name 'orajwt.JwtGenerator.rs256Encode(java.lang.String, java.lang.String, java.lang.Long, java.lang.Long, java.lang.String) return java.lang.String';

To create a RSA256 signed JSON Web Token run create_JWT() from PL/SQL, provide the claims and the private key.

This blog post was focusing on signing a JWT using RSA256 encryption algorithm and a private key. Next is to add a function to verify a signed JWT using the public key. For this also a PL/SQL implementation exists from Ilmar Kerm.