DEV Community: Hinse ter Schuur

Learn OIDC - Part 2 - JWT

Hinse ter Schuur — Sat, 23 Mar 2024 23:00:00 +0000

Introduction

For a project I was working on, I was looking for a lightweight OIDC Identity Provider to be used as a stub for our tests. I couldn’t find a lightweight one, so I tried to build one myself.

WARNING: The code shown in this series is for educational purposes only and is not meant to be used in production.

JWT

One of the important building blocks in OAuth and OIDC is the concept of JSON Web Token or JWT (often pronounced as ‘jot’). A JWT is basically a JSON Web Signature (see: Learn OIDC - Part 1 - JWS) with a set of claims, represented as a JSON object as payload. The advantage of JSON format for the claims is that it is fairly easy to parse and human-readable too.

Format

The most common representation of JWTs is the JWS Compact Serialization. The details of the JWT specification can be found in RFC 7519.

Claims

The claims in the JWT can be basically anything, but there is a set of Registered Claim Names. All these registered claim names are shortened to just 3 characters in order to provide a compact representation. Although all these Registered Claim Names are considered optional for the JWT specification, they are heavily used in OAuth and OIDC implementations.

So for our implementation we’re going to use (most of) these registered claim names as well.

iss - the principal that issued the claims, should be a string/uri
sub - the principal that is the subject of the claims, should be a string/uri
aud - an array of audiences that the JWT is intended for (if there’s just one audience, it could be a plain string/uri instead of an array)
exp - the expiration time identifies the expiration time after which the JWT must not be accepted for processing, should be a number representing seconds since the epoch
nbf - the not before identifies the time before which the JWT MUST NOT be accepted for processing, should be a number representing seconds since the epoch
iat - the issued at identifies the time at which the JWT was issued, should be a number representing seconds since the epoch
jti - the JWT ID provides a unique identifier for the JWT, should be a string and can be used to prevent detect token replays

Note that none of these are required from the perspective of the JWT spec. Those are just some registered, commonly used claims.

In the light of OIDC some of these claims are required for proper OIDC implementation with ID tokens, as we’ll see in a later post

Implementation

A straight-forward way to implement a method to generate a JWT could be to re-use the JWS implementation from part 1 and put some manually constructed JSON string as payload.

Something like:

var payload = """
        {
        "iss": "fake-oidc-idp",
        "sub": "johndoe",
        "aud": "app-under-test",
        "exp": 1711285526,
        "nbf": 1711285226,
        "iat": 1711285226,
        "jti": "88771636-b8ec-49b1-bf07-03117f989a7a"
        }""".replace("\n", "");

return Jws.compactRS256(payload.getBytes(StandardCharsets.UTF_8), privateKey, keyId);

This will work for some hardcoded payload like this, but for implementing a lightweight OIDC stub we would need a bit more dynamic values.

Specifically the exp, nbf, and iat should be more dynamic. This could be done with some clever String.format setup, but it will get messy once we try to make the string fields dynamic. Because then we’d need all kinds of escaping to keep the JSON body properly formatted.

So the best move would be to include some battle-tested JSON library to help with this. In this series we’ll be using the well-known Jackson JSON library.

Assembling claims

The access token claims we will be creating for this example should be dynamic. For example the iat (issued at) should be set to the moment of generation. Next to that, tokens typically have some token lifetime which is expressed as the timestamp at which the token expires (exp claim). This also requires the current time plus the token lifetime.

Given that we already have fields or variables for privateKey, keyId, issuer (which is typically constant for the application) and tokenLifetimeInSeconds, the token generation method could look like:

private static final ObjectMapper MAPPER = new ObjectMapper();
static {
    MAPPER.configure(SerializationFeature.INDENT_OUTPUT, false);
    MAPPER.setSerializationInclusion(JsonInclude.Include.NON_NULL);
}

public String createJwt(String subject, String audience) throws GeneralSecurityException, JsonProcessingException {
    var nowSeconds = System.currentTimeMillis() / 1000;
    var claims = Map.of(
            "iss", issuer,
            "sub", subject,
            "aud", audience,
            "exp", nowSeconds + tokenLifetimeInSeconds,
            "nbf", nowSeconds,
            "iat", nowSeconds,
            "jti", UUID.randomUUID().toString()
    );
    var payload = MAPPER.writeValueAsBytes(claims);
    return Jws.compactRS256(payload, privateKey, keyId);
}

This code first determines the current time in seconds since epoch and then assembles all the claims we want. For now, we use a random UUID as JWT ID (jti), this will be sufficient for all intents and purposes of the stub OIDC server we’re going to build.

As “API” for our JWT generation function we’ll require just these 2 parameters:

a subject containing some identifier of the user who is represented by the generated token
an audience (application which is supposed to process the token)

What’s next?

Since we now have some basic building blocks we could look into building the first steps of an OIDC login flow.

Learn OIDC - Part 1 - JWS

Hinse ter Schuur — Tue, 20 Feb 2024 23:00:00 +0000

Introduction

For a project I was working on, I was working a lot with OIDC-related technology.

Somewhere in the project there was the need for an easy to use and easy to configure OIDC server mock. We used Keycloak¹, which is highly configurable, to act as an OIDC server for our end-to-end test needs. This worked quite well.

But at some point we needed something which would be easy to mock for our (integration) tests. Googling around didn’t reveal any lightweight, easy to configure mock OIDC server, so I decided to try to build one myself.

WARNING: The code shown in this series is for educational purposes only and is not meant to be used in production.

JWS

One of the building blocks of OIDC is JWS (JSON Web Signature)². JWS is the underlying structure for JWTs (JSON Web Tokens). JWT is the structure being used to transmit authorization in OAuth and user identity info in OIDC. We’ll dive into JWT in a later post.

But I thought that it would be a good idea to take a quick look at JWS first.

Structure

JSON Web Signature is basically a digitally signed payload and a header describing the type of contents and the type of signature. The most common way to represent a JWS is Compact Serialization. The specification describes this as:

BASE64URL(UTF8(JWS Protected Header)) || ‘.’ || BASE64URL(JWS Payload) || ‘.’ || BASE64URL(JWS Signature)

Where JWS Payload can be any kind of payload. This could be JSON but could also be some arbitrary byte-array.

The most common signature algorithms being used on examples on the web are HS256 and RS256 which stands HMAC using SHA-256 and RSASSA-PKCS1-v1_5 using SHA-256 respectively. Implementing a JWS generation method could be done using standard Java APIs.

HS256

The following function generates a valid JWT compact representation for any byte[] payload using the provided secret key. This secret key is supposed to be shared between sender and recipient of the JWS.

static final Base64.Encoder ENCODER = Base64.getUrlEncoder().withoutPadding();

public static String compactHS256(byte[] payload, SecretKey secretKey) throws GeneralSecurityException {
    var header = """
            {"alg": "HS256"}
            """;
    var encodedHeader = ENCODER.encodeToString(header.getBytes(StandardCharsets.UTF_8));
    var encodedPayload = ENCODER.encodeToString(payload);
    var signingInput = encodedHeader + "." + encodedPayload;

    var hmac = Mac.getInstance("HmacSHA256");
    hmac.init(secretKey);
    var signature = ENCODER.encodeToString(hmac.doFinal(signingInput.getBytes()));
    return signingInput + "." + signature;
}

RS256

Since the previous signature method (rs256) requires a shared secret to be shared between both parties, it might not be the best fit for implementing OIDC servers. A better approach would be to rely on (RSA) public/private key pairs. This could be achieved with the rs256 algorithm. This implementation looks quite similar to the hs256 one, but uses a Signature object instead of a Mac object. And of course the input parameter is an RSA privateKey instead of some shared secret.

static final Base64.Encoder ENCODER = Base64.getUrlEncoder().withoutPadding();

public static String compactRS256(byte[] payload, RSAPrivateKey privateKey) throws GeneralSecurityException {
    var header = """
            {"alg": "RS256"}
            """;
    var encodedHeader = ENCODER.encodeToString(header.getBytes(StandardCharsets.UTF_8));
    var encodedPayload = ENCODER.encodeToString(payload);
    var signingInput = encodedHeader + "." + encodedPayload;

    var signer = Signature.getInstance("SHA256withRSA");
    signer.initSign(privateKey);
    signer.update(signingInput.getBytes());
    var signature = ENCODER.encodeToString(signer.sign());
    return signingInput + "." + signature;
}

Example usage

The method above is quite easy to use. It requires a payload, let’s use the string Hello World! for this example. The most complex part would be to load the private key to use for the signing. For now let’s assume that the file is present in the file signing.der³.

// Load private key
var keyFactory = KeyFactory.getInstance("RSA");
var keyFileName = "signing.der";
byte[] privateKeyBytes = Files.readAllBytes(new File(keyFileName).toPath());
var privateKey = (RSAPrivateKey) keyFactory.generatePrivate(new PKCS8EncodedKeySpec(privateKeyBytes));

// Example payload
byte[] payload = "Hello World!".getBytes(StandardCharsets.UTF_8);

var compactJws = Jws.compactRS256(payload, privateKey);
System.out.println(compactJws);

This would print something like:

eyJhbGciOiAiUlMyNTYifQo.SGVsbG8gV29ybGQh.<signature-bytes>

This compactJws could be sent to a receiving party which could verify the integrity of the message by checking the signature using the public key of the sender.

Multiple keys

In a lot of systems keys tend to be rotated every now and then. This is also the case for signing keys for JWS.

To give recipients an indication of which key was used to sign the message, a special kid (Key ID) claim in the JWS header could be utilized. The kid is an identifier of the key that was used to sign the specific message.

NOTE: The specification doesn’t say anything about how key ids map to a specific key. This has to be agreed upon by the sending and receiving side (typically chosen by the sender side).

One elegant way to communicate the mapping of kid to the public key is the use of JWK Set⁴. This JWK Set can list multiple ‘kid’ to public key mappings.

Add kid claim

Adding support for the kid claim to our JWS implementation is quite straightforward. The only thing that we need to change is the header variable:

public static String compactRS256(byte[] payload, RSAPrivateKey privateKey, String kid) throws GeneralSecurityException {
    var header = """
            {"alg": "RS256","kid": "%s"}
            """.formatted(kid);
    var encodedHeader = ENCODER.encodeToString(header.getBytes(StandardCharsets.UTF_8));
    var encodedPayload = ENCODER.encodeToString(payload);
    var signingInput = encodedHeader + "." + encodedPayload;

    var signer = Signature.getInstance("SHA256withRSA");
    signer.initSign(privateKey);
    signer.update(signingInput.getBytes());
    var signature = ENCODER.encodeToString(signer.sign());
    return signingInput + "." + signature;
}

Summary

We implemented a very bare-bones method to create valid JWS objects which basically contains a digitally signed payload. We looked at two separate mechanisms to sign the JWS: shared secret (hs256) en public/private key (rs256).

This should serve as a good starting point for implementing JWT on top of it. … Which will be a topic of an upcoming blog post.

Keycloak is an Open Source Identity and Access Management, see https://keycloak.org ↩
JWS Specification: RFC 7515 ↩
The file signing.der could be generated using the openssl command: openssl genrsa -outform der -out signing.der 2048 && openssl rsa -in signing.pem -outform DER -out signing.der ↩
JSON Web Key Set: RFC 7517 - Section 5 ↩

Reduce unnecessary “ceremony” with the map method

Hinse ter Schuur — Sun, 23 Jul 2023 22:00:00 +0000

Recently I was pair-programming with a co-worker who was struggling with understanding the map function of java.util.stream.Stream. The brought back memories of how I learned the meaning and practical application of the map function.

Lists

Let’s have a look at good-old Lists first

In the very old days (pre Java 5)

In the Java 1.2+ days we had lists without generics, no streams API and no for-each loops.

Suppose we have a List of String containing words (words) and we want to convert it to a list containing the lengths of the words. In these early versions of Java the following had to be done:

public static List getWordLengths(List words) {
    List result = new ArrayList();
    for (int i = 0; i < words.size(); i++) {
        String word = (String) words.get(i);
        result.add(word.length());
    }
    return result;
}

or… if you wanted to abstract away from using an integer index and checking the size, you could use an iterator.

public static List getWordLengths(List words) {
    List result = new ArrayList();
    Iterator iterator = words.iterator();
    while (iterator.hasNext()) {
        String word = (String) iterator.next();
        result.add(word.length());
    }
    return result;
}

The nice thing about the second version is that it required a bit less knowledge about the list. You didn’t need consider the size of the list.

At that moment in time, every Java programmer would almost immediately recognize what the code was supposed to do: “transform every item of the list of words into the length of the word”

There was just a large portion of ceremony around the actual transformation.

In the less-old days (pre Java 8)

With Java 5, the required ceremony for doing these kind of transformations was greatly reduced.

Instead of using Iterator or index variables we could use the for-each loop construct. And in addition we got generics, which made the casts obsolete (when the words list was defined as List<String>)

So in order to do the same as before, we would now only need this code (since the words was now of typed with generics )

public static List<Integer> getWordLengths(List<String> words) {
    List<Integer> result = new ArrayList<Integer>();
    for (String word : words) {
        result.add(word.length());
    }
    return result;
}

The great benefit was that we nearly didn’t have to think about “how to iterate” over all the items. We could just focus on the transformation and adding the results to a list.

And again… somewhat experienced Java programmers would immediately see what was going on. Every item of the list was being transformed and put into the result list. We just didn’t have a proper name for “transform every item and put into result list”.

Recent days

With Java 8 we got the Streams API and lambdas. This Streams API introduced the concept of “transform every item” by adding the map method.

public static List<Integer> getWordLengths(List<String> words) {
    return words.stream()
            .map(word -> word.length())
            .collect(Collectors.toList());
}

This map basically says: transform every item and collect the results in a new list. The only “unnecessary” ceremony is the .stream() and the .collect(Collectors.toList()).

Current day

With the helper methods introduced in Java 16, it’s even more convenient since the .collect(...) could be replaced with toList in order to reduce some of the “unnecessary” ceremony.

public static List<Integer> getWordLengths(List<String> words) {
    return words.stream()
            .map(word -> word.length())
            .toList();
}

So with this version we don’t need to think about iterating and creating new collections anymore. We could just focus on the transformation. We just map every item that is contained in the list.

Optional

In addition to collections/streams, there is another part of the standard Java APIs where we can use map to prevent unnecessary ceremony… Optional

Suppose we have a variable that might or might not contain a word:

Optional<String> maybeWord = ...

With boilerplate

Suppose we want to get the length of the word, if there is a word in it. A “naive” approach could be to check whether the optional contains a word, and if so… transform the item. E.g. something like this:

if (maybeWord.isPresent()) {
    return Optional.of(maybeWord.get().length());
} else {
    return Optional.empty();
}

What we basically want to do, is transform every item (0 or 1 item) to it’s length. We use some ceremony to determine the content of the Optional and to create a new Optional containing the result.

Without boilerplate

This sounds quite similar to the .map function we saw earlier. We don’t want to mess around we destructuring and assembling some results ourselves, we’d like the map function to take care of that.

Luckily the creators of Java created an equivalent map function on the Optional class, making it a breeze to transform data contained in an Optional.

return maybeWord.map(word -> word.length());

Keep in mind

It is important to keep in mind that the function/lambda, which does the mapping, shouldn’t modify the original object nor the original list that the stream is created for. Ideally the function should be side-effect free.

Other appearances

The map function is something which could be found in all kinds of APIs and other programming languages too.

For example when doing reactive programming with Spring WebFlux you could use the map function to transform a Mono. Or when using Quarkus you could call map on a Uni to get a transformed Uni.