I presented a sponsor session on the Shared Signals Framework (SSF) at the OAuth Security Workshop 2026 (OSW2026), held in Leipzig, Germany, from May 27 through May 29, 2026. This article summarizes the key points of that presentation.

Three Shared Signals Final Specifications

In September 2025, the OpenID Foundation (OIDF) announced that the final versions of three specifications related to Shared Signals had been approved.

The three specifications are listed below:

• SSF — OpenID Shared Signals Framework Specification 1.0
• CAEP — OpenID Continuous Access Evaluation Profile 1.0
• RISC — OpenID RISC Profile Specification 1.0

In addition to these, there are several related specifications under the stewardship of the Internet Engineering Task Force (IETF), including the following:

• RFC 8417 — Security Event Token (SET)
• RFC 8935 — Push-Based Security Event Token (SET) Delivery Using HTTP
• RFC 8936 — Poll-Based Security Event Token (SET) Delivery Using HTTP
• RFC 9493 — Subject Identifiers for Security Event Tokens
• RFC 9967 — System for Cross-Domain Identity Management (SCIM) Profile for Security Event Tokens (SETs)

Transmitter’s Behavior

The Shared Signals Framework (SSF) specification defines the behavior of a Transmitter.

Broadly speaking, a transmitter has two responsibilities:

1. Generate a Security Event Token (SET).
2. Deliver the Security Event Token to a Receiver.

A Security Event Token (SET) is a token that represents a security-related event. Its format is based on JWT. The detailed definition can be found in RFC 8417, and the SSF specification introduces additional requirements on top of RFC 8417, including some that conflict with it (for example, SSF prohibits the inclusion of the sub claim).

Two notable claims in a Security Event Token payload are sub_id and events.

sub_id

The sub_id claim identifies the subject of the event. Unlike the sub claim in an ID Token, which is a single string value, the value of the sub_id claim is a JSON object whose structure is more complex than one might expect.

RFC 9493 defines the possible JSON object formats that a sub_id claim may take, and the SSF specification introduces additional definitions and requirements of its own.

From RFC 9493, 3.2.3. Issuer and Subject Identifier Format:

{
  "format": "iss_sub",
  "iss": "https://issuer.example.com/",
  "sub": "145234573"
}

From SSF, 3.5.3. IP Addresses Subject Identifier Format:

{
  "format": "ip-addresses",
  "ip-addresses": [
    "10.29.37.75",
    "2001:0db8:0000:0000:0000:8a2e:0370:7334"
  ]
}

events

The events claim describes the event type and any associated event data. Its value is a JSON object containing exactly one key-value pair. The key is a URI that identifies the event type. The value is another JSON object that may contain event-specific information. If no additional information is associated with the event, the value is simply an empty JSON object.

The CAEP profile, the RISC profile, and RFC 9967 define a number of event type identifiers and the formats of the associated event data that they may carry. The SSF specification itself also defines several event type identifiers.

From CAEP, 3.1. Session Revoked:

"events": {
  "https://schemas.openid.net/secevent/caep/event-type/session-revoked": {
    "event_timestamp": 1615304991
  }
}

From RISC, 2.3. Account Disabled:

"events": {
  "https://schemas.openid.net/secevent/risc/event-type/account-disabled": {
    "reason": "hijacking"
  }
}

From RFC 9967, 2.4.5. urn:ietf:params:scim:event:prov:activate:

"events":{
  "urn:ietf:params:scim:event:prov:activate": {}
}

From SSF, 8.1.4.2. Triggering a Verification Event:

"events": {
  "https://schemas.openid.net/secevent/ssf/event-type/verification": {
    "state": "VGhpcyBpcyBhbiBleGFtcGxlIHN0YXRlIHZhbHVlLgo="
  }
}

Transmitter Breakdown

The SSF specification defines a set of endpoints for transmitters.

• Metadata Endpoint — Publishes the transmitter’s metadata (configuration information). The endpoint path is /.well-known/ssf-configuration (see the specification for the exact definition).
• Configuration Endpoint — Manages streams, including stream creation, deletion, configuration retrieval, and configuration updates. (Events are delivered through streams.)
• Status Endpoint — Queries and Updates the status of a stream.
• Add Subject Endpoint — Addes subjects to a stream’s set of monitored subjects.
• Remove Subject Endpoint — Removes subjects from a stream’s set of monitored subjects.
• Verification Endpoint — Tests stream connectivity.
• Polling Endpoint — Delivers events via polling. (Details are defined in RFC 8936)

In addition, a transmitter needs to publish the public keys required to verify the signatures of Security Event Tokens. As a result, it typically provides an endpoint that exposes a JWK Set document (RFC 7517). In fact, transmitter metadata includes the jwks_uri parameter, which indicates the location of the JWK Set document.

The SSF specification expects these endpoints to be protected by some form of access control. OAuth access tokens, for example, are one possible protection mechanism.

Endpoints may also be protected by mechanisms other than access tokens. In fact, one open-source implementation protects its endpoints using OAuth client authentication.

In any case, to satisfy the requirements of the specification, the endpoints must be able to identify the OAuth client making the request. Although this requirement is not stated explicitly, it is an inevitable consequence of the specification’s design.

Furthermore, although the SSF specification does not define such functionality, a generic transmitter implementation would typically provide a mechanism for enqueueing arbitrary events into its event queue.

SSF is Not Trivial to Implement

Although the motivation behind the SSF family of specifications is the notification of security-related events, a closer look at the specifications reveals that SSF is actually a highly generic framework. It can be used not only for security events, but for arbitrary events as well.

As a result, not only the identity providers envisioned by the specifications, but virtually any source of events can act as a transmitter.

This naturally leads to the idea of adding transmitter functionality to various event sources. Unfortunately, implementing an SSF transmitter is not a particularly simple task. At a minimum, it requires implementing the following:

• Event queue management
• Event delivery via polling and push mechanisms
• Endpoint implementation
• Endpoint protection (OAuth, MTLS, DPoP, HTTP Message Signatures, etc.)
• Key management (for Security Event Token signing, HTTP Message Signatures, and more)

Reimplementing all of this functionality for every transmitter is a tedious and repetitive undertaking.

A Lazy Programmer’s Solution

How would a lazy programmer — that is, a programmer who dislikes repeating the same work and therefore builds reusable mechanisms to save effort in the long run — implement SSF?

Rather than implementing the transmitter endpoints directly in each server, such a programmer would probably build a single backend system responsible for the transmitter functionality and have multiple transmitters rely on it.

With this approach, the frontend transmitter implementations become much thinner.

Younger readers may not be aware of this, but laziness has long been regarded as one of the three great virtues of a programmer.

Larry Wall wrote in Programming Perl:

And although we don’t intend to teach you how to program, the perceptive reader will pick up some of the art, and a little of the science, of programming. We will encourage you to develop the three great virtues of a programmer: laziness, impatience, and hubris.

For example, a backend system of this kind might expose the following APIs corresponding to the transmitter’s Configuration Endpoint, as shown in the figure below.

• /stream/delete
• /stream/read
• /stream/update
• /stream/create
• /stream/replace

Authlete Arena

A real-world example of such an SSF backend is Authlete Arena, a new product from Authlete.

A receiver sends a request to a transmitter.

If the transmitter is implemented using Authlete Arena, it delegates the processing of the incoming request to Authlete Arena. Authlete Arena processes the request and instructs the transmitter on what response should be returned. This delegation model follows Authlete’s Semi-Hosted Service pattern (see New Architecture of OAuth 2.0 and OpenID Connect Implementation for more details).

In most cases, Authlete Arena remains hidden behind the transmitter; it never communicates directly with receivers. However, when events are delivered using the push model, Authlete Arena delivers Security Event Tokens directly to the receiver’s endpoint.

Authlete Arena’s APIs are protected by OAuth access tokens.

This implies that an authorization server is required to issue access tokens to transmitters for accessing the Authlete Arena APIs.

Authlete Arena communicates with the authorization server to obtain access token information or to retrieve the public keys required to validate access token signatures.

Like the Authlete Arena APIs, the transmitter’s endpoints are also protected by OAuth access tokens.

This implies that an authorization server is required to issue access tokens to receivers for accessing the transmitter’s endpoints.

Normally, a transmitter would communicate with the authorization server to obtain access token information or to retrieve the public keys required to validate access token signatures. When using Authlete Arena, however, access token validation can be delegated to Authlete Arena.

Instead, Authlete Arena communicates with the authorization server on behalf of the transmitter, either to obtain access token information or to retrieve the public keys required to validate access token signatures.

The benefit of delegating access token validation to Authlete Arena is that it allows transmitters to leverage Authlete’s expertise in API protection. This expertise covers technologies such as OAuth, MTLS, DPoP, and HTTP Message Signatures. In addition, advanced access-control mechanisms such as “Cedar Policy in RAR Object” are also supported.

All functionality provided by Authlete Arena can be controlled through Web APIs. As a result, it can be operated entirely from the command line. That said, a web-based administration console is often more convenient in practice, so Arena Dashboard is planned to provide that capability.

The architecture for implementing a transmitter using Authlete Arena is illustrated in the figure below.

A Design Decision

Most identity server implementations will probably choose to implement the SSF transmitter endpoints directly within the server itself. In fact, I recently confirmed that the SSF implementation of an open-source project follows exactly this approach, as one would expect.

After careful consideration, however, Authlete chose a different path: to build a generic SSF backend system that is independent of any particular identity server. As a result, we developed Authlete Arena as a completely separate product rather than as an extension to the existing Authlete platform.

Building a standalone product instead of simply adding new functionality to Authlete required a significant investment of time and effort. In return, however, it enabled us to address virtually any use case in which SSF may be applicable.

One recent example is the growing interest in using SSF in the context of AI agent governance and control. Because Authlete Arena is designed as a generic SSF backend, we are able to support such use cases as well.

Why the Name “Arena” ?

The name Arena was chosen to emphasize that the system is a generic event delivery mechanism capable of handling not only security-related events, but arbitrary events of any kind.

In this context, we intentionally use the word arena in its broader sense — a venue for events such as sporting competitions, concerts, and other gatherings. The name reflects the idea that Authlete Arena can serve as a platform for many different kinds of events, not just security events.

Since the company and product name Authlete already evokes the word athlete, the combination Authlete Arena felt like a natural fit.

Conclusion

When we founded Authlete ten years ago, I never imagined that our company would one day become the main sponsor of the OAuth Security Workshop — one of the most technically specialized events in the identity and security industry.

Thankfully, Authlete has continued to grow steadily as a profitable company, strengthening its presence both in Japan and around the world.

We are actively hiring, so if you’re interested in what we do, please feel free to get in touch.

This year again, Authlete is proud to serve as a Platinum Sponsor. We are also preparing the traditional OSW T-shirt giveaway. This year’s design will feature the Monument to the Battle of the Nations (Völkerschlachtdenkmal), one of Leipzig’s iconic landmarks.

This will be my first time attending OSW in person in two years. While my primary purpose is, of course, to participate in the event itself, I would be more than happy to talk during breaks about business opportunities, partnerships, and career opportunities at Authlete.

From Authlete, Ali Adnan (Business Development) and Zulfiqar Ahmed (Head of Product) will also be attending in person, so please feel free to reach out to us.

Authlete After 10 Years

Authlete has now passed its 10th anniversary.

We continue to grow profitably while serving excellent customers around the world. The uniqueness of our product architecture has created a strong technical competitive advantage in the market.

Recently, it feels as though the company is transitioning from the “1 → 10” phase into the “10 → 100” phase. In particular, the increasing number of high-quality customers outside Japan gives us strong confidence in our future growth.

I believe this is a particularly exciting time to partner with Authlete or to join the company.

AI Infrastructure Needs Trust Infrastructure

Although Authlete does not position itself as an “AI company,” we have steadily been building technology components related to AI. Because of this, I believe Authlete is becoming a strong partner for the emerging AI ecosystem.

As AI agents begin operating across organizational and trust boundaries, identity, federation, authorization, and event delivery become increasingly important infrastructure layers.

At Authlete, we have been investing in these areas through open standards technologies.

For example, I have already introduced our implementations of Client ID Metadata Document and OAuth SPIFFE Client Authentication on LinkedIn. We also natively support OpenID Federation, which is one possible approach for bridging AI agents across different trust domains.

In addition, we are currently developing support for the Shared Signals Framework (SSF) as a new product initiative.

We view SSF not merely as a framework for security-related notifications, but as a general-purpose event delivery system that can also support coordination among distributed systems and AI agents. This perspective significantly expands the possible applications of SSF beyond traditional security event use cases.

I hope we will be able to share more details soon.

Building a Career in Digital Identity

Because of the nature of our business, Authlete works with cutting-edge standards technologies on a daily basis.

I believe this makes Authlete one of the best places for people who want to build a career in the digital identity industry.

We also value diversity and actively welcome team members from different countries, languages, and time zones.

English is our common language, but additional language skills create even more opportunities, especially for people involved in international business development.

For example, team members who speak Portuguese, Spanish, or Italian actively contribute to communication with existing and prospective customers in their respective regions.

See You in Leipzig

If you are attending OSW 2026 and are interested in:

• digital identity
• OAuth and OpenID technologies
• AI infrastructure
• federation and trust frameworks
• partnerships with Authlete
• career opportunities at Authlete

please feel free to reach out.

Looking forward to seeing you in Leipzig.

When sender-constrained access tokens are implemented using DPoP (RFC 9449), the client includes a DPoP proof JWT (Section 4) in requests sent to the server.

The payload of the DPoP proof JWT must include the following claims:

• jti — A unique identifier for the DPoP proof JWT
• htm — The HTTP method of the request
• htu — The target URI of the request
• iat — The time at which the DPoP proof JWT was generated

In addition to these, when a DPoP proof JWT is used together with an access token — that is, when the client accesses a protected resource — the payload must also include the following claim:

• ath — The base64url-encoded representation of the SHA-256 hash of the access token

In addition, if the server requires a nonce, the nonce claim must also be included.

• nonce — The latest nonce provided by the server

Below is an example of a DPoP proof JWT payload containing a nonce:

{
  "jti": "XdPQLwZIH9pmlMhD",
  "htm": "GET",
  "htu": "https://rs.example.com/resource/1",
  "iat": 1755096729,
  "ath": "-7JjHPHFqtqwNHk7dPoU4nL7SgIgLn8vdCiDq-LfovY",
  "nonce": "ZgmFr7UWLrJX0fHB"
}

This article takes a closer look at this nonce.

Role of the nonce

Section 2. Objectives of the DPoP specification mentions an attack in which XSS code generates a DPoP proof JWT with a timestamp set in the future and later abuses it elsewhere after some time has passed. To mitigate the impact of such an attack, the server can require that the DPoP proof JWT include time-limited data provided by the server, which helps to some extent prevent unauthorized access using pre-generated DPoP proof JWTs.

Since the DPoP proof JWT is generated by the client, the values of time-related claims in its payload can be chosen freely by the client. Therefore, if the server wants to control the validity period of DPoP proof JWTs, it needs to require that server-provided, time-limited data be included in the DPoP proof JWT. The nonce claim is used for this purpose.

Provision of the nonce

A server that requires a nonce to be included in a DPoP proof JWT returns an error response containing the DPoP-Nonce HTTP header if the DPoP proof JWT does not include a nonce.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: DPoP error="use_dpop_nonce"
DPoP-Nonce: ZgmFr7UWLrJX0fHB

A resource server that complies with RFC 6750 generates a WWW-Authenticate HTTP header containing the error information, with the error code set to use_dpop_nonce.

Upon receiving this error, the client extracts the value of the DPoP-Nonce header and creates a DPoP proof JWT that includes that value as the value of the nonce claim.

The client then includes the new DPoP proof JWT in the request when resending the resource request.

Overall diagram:

Detection of nonce expiration

The client continues to use the provided nonce for subsequent resource requests. However, that nonce will eventually expire, and when it does, the server returns an error response.

Upon receiving an error response, if the client can determine that the cause of the error is “nonce expiration,” it will recreate the DPoP proof JWT using the latest nonce included in the error response and resend the request.

However, determining this is not straightforward. This is because the DPoP specification does not define a dedicated error code (such as dpop_nonce_expired) for this situation.

Therefore, the client will presume that the error was caused by nonce expiration when the following conditions are met:

• The response status code is “401 Unauthorized”
• The value of the nonce currently held by the client differs from the value of the DPoP-Nonce header included in the error response
• The error code is invalid_dpop_proof

HTTP/1.1 401 Unauthorized
WWW-Authenticate: DPoP error="invalid_dpop_proof"
DPoP-Nonce: knvXdyXM3FK3QGEK

Request retry logic

When using DPoP nonces, it is expected behavior for the server to return error responses periodically, so the client must implement request retry handling to cope with this. As a result, error handling becomes more complex.

For reference, the pseudocode for request retry is shown below.

// Obtain the nonce value currently held by the client. This nonce value is
// embedded in the DPoP proof JWT. If this client has never received a nonce
// from the server so far, the getDpopNonce() method returns null.
String dpopNonce = getDpopNonce();

// Perform the resource request. (Generation of the DPoP proof JWT is done
// inside the invoke() method.)
ResponseInfo rinfo = invoke(
    request, httpMethod, path, body, mediaType, dpopNonce);

// If the response contains a DPoP-Nonce HTTP header, update the nonce value
// held by this client with the value of that header. If the response does
// not include a DPoP-Nonce header, the updateDpopNonceIfSupplied() method
// does not update the nonce value and returns null.
String updatedDpopNonce = updateDpopNonceIfSupplied(rinfo.getResponse());

// If the response indicates a DPoP nonce error
if (isDpopNonceError(rinfo.getResponse(), dpopNonce, updatedDpopNonce))
{
    // Create a DPoP proof JWT using the latest nonce value and resend
    // the request.
    rinfo = invoke(
        request, httpMethod, path, body, mediaType, updatedDpopNonce);
}

// The response status code
int status = rinfo.getResponse().getStatus();

// If the request succeeded
if (200 <= status && status < 300)
{
    return rinfo;
}

// If the request failed
throw callError(httpMethod, path, rinfo);

DPoP nonce settings (Authlete-specific)

Authlete provides the following configuration options related to DPoP nonces:

• Service.dpopNonceDuration — The validity duration of a DPoP nonce, in seconds
• Service.dpopNonceRequired — Whether the server requires a DPoP nonce
• Client.dpopNonceRequired — Whether a DPoP nonce is required for this client

Conclusion

A DPoP nonce helps, to some extent, prevent unauthorized access using pre-generated DPoP proof JWTs. In exchange, client-side code becomes somewhat more complex.

The document “Comprehensive API Protection with Standard Specifications” on the Authlete website provides more information about security measures for API protection, including DPoP nonces.

RFC 9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP) is particularly memorable for us, as it is the first IETF RFC whose list of authors includes Authlete. Please visit our Careers page for opportunities to work together with industry experts.

The Token Status List (TSL) specification is nearing completion.

This specification is designed to handle status information (such as valid or invalid) for various token types based on JOSE and COSE, including JWT, SD-JWT VC, CWT, and ISO mdoc.

To efficiently represent the status of a large number of tokens, statuses are encoded as a bit array and compressed using DEFLATE.

The TSL specification defines a data structure called StatusList to represent this list of statuses. In this article, we take a closer look at the StatusList.

Structure of the StatusList

Regardless of whether the format is JSON or CBOR, a StatusList has the following properties:

• bits — REQUIRED. The number of bits used to represent a single status. One of 1, 2, 4, or 8.
• lst — REQUIRED. A DEFLATE-compressed representation of the status values expressed as a byte array. In CBOR, it is represented as a byte array; in JSON, it is represented as a base64url-encoded string.
• aggregation_uri — OPTIONAL. A location from which a list of URIs that publish Status List Tokens can be obtained.

Below are examples of StatusList objects in JSON format, excerpted from the specification.

{
  "bits": 1,
  "lst": "eNrbuRgAAhcBXQ"
}

{
  "bits": 2,
  "lst": "eNo76fITAAPfAgc"
}

The bits property represents the number of bits used to encode a single status, and its possible values are 1, 2, 4, or 8. When the number of bits is 1, up to 2¹ = 2 different statuses can be represented, for example, “valid” and “invalid.” When the number of bits is 2, up to 2² = 4 statuses can be represented; with 4 bits, up to 2⁴ = 16 statuses; and with 8 bits, up to 2⁸ = 256 statuses can be represented.

The lst property contains the DEFLATE-compressed byte array that enumerates the set of statuses. In the CBOR format, the result of the DEFLATE compression is stored directly as a byte array, whereas in the JSON format, it is base64url-encoded and represented as a string.

For example, suppose the number of bits used to represent a status is set to 1, and the statuses of 16 tokens are as follows:

| Index | Status  | Value |
|-------+---------+-------|
|   0   | INVALID |   1   |
|   1   |  VALID  |   0   |
|   2   |  VALID  |   0   |
|   3   | INVALID |   1   |
|   4   | INVALID |   1   |
|   5   | INVALID |   1   |
|   6   |  VALID  |   0   |
|   7   | INVALID |   1   |
|   8   | INVALID |   1   |
|   9   | INVALID |   1   |
|  10   |  VALID  |   0   |
|  11   |  VALID  |   0   |
|  12   |  VALID  |   0   |
|  13   | INVALID |   1   |
|  14   |  VALID  |   0   |
|  15   | INVALID |   1   |

If these are packed as shown in the following figure, the resulting byte array is [0xB9, 0xA3].

This byte array is then compressed using DEFLATE and set as the value of lst.

Similarly, suppose the number of bits used to represent a status is 2, and the statuses of 12 tokens are as follows:

| Index | Status |
|-------+--------|
|   0   |   01   |
|   1   |   10   |
|   2   |   00   |
|   3   |   11   |
|   4   |   00   |
|   5   |   01   |
|   6   |   00   |
|   7   |   01   |
|   8   |   01   |
|   9   |   10   |
|  10   |   11   |
|  11   |   11   |

When these statuses are packed as illustrated in the following figure, the resulting byte array is [0xC9, 0x44, 0xF9].

This byte array is then compressed using DEFLATE and set as the value of lst.

Implementation of the StatusList

The CBOR library authlete/cbor (for Java), which Authlete publishes as open source, includes a class named StatusList for representing a StatusList in the com.authlete.cbor.tsl package starting from version 1.21.

The constructor of this StatusList class takes the following arguments: int bits, byte[] lst, and String aggregationUri.

public StatusList(int bits, byte[] lst, String aggregationUri)

However, preparing the value of lst in the first place is cumbersome, so the path to calling this constructor is not so easy. To address this, a utility class named StatusListBuilder is provided for creating instances of the StatusList class.

The usage of StatusListBuilder is as follows:

1. Choose the number of bits used to represent each status from among 1, 2, 4, or 8.
2. Create a StatusListBuilder instance by passing the chosen bit size to its constructor.
3. Call the valueAt method as many times as needed to set individual status values.
4. If you want to set aggregation_uri, call the aggregationUri method.
5. If you want to reserve capacity beyond the number of statuses automatically expanded by the indices specified via valueAt, call the capacity method.
6. Finally, call the build method to create a StatusList instance.

For example, to create a StatusList that contains the following set of statuses listed in Section 4.1. Compressed Byte Array of the TSL specification,

status[ 0] = 0b1
status[ 1] = 0b0
status[ 2] = 0b0
status[ 3] = 0b1
status[ 4] = 0b1
status[ 5] = 0b1
status[ 6] = 0b0
status[ 7] = 0b1
status[ 8] = 0b1
status[ 9] = 0b1
status[10] = 0b0
status[11] = 0b0
status[12] = 0b0
status[13] = 0b1
status[14] = 0b0
status[15] = 0b1

you can write the code as follows:

// Number of bits used to represent a status
int bits = 1;

// Create a StatusListBuilder instance by passing the number
// of bits to the constructor
StatusListBuilder builder = new StatusListBuilder(bits);

// Set status values
builder.valueAt(StatusTypeValue.INVALID,  0);
builder.valueAt(StatusTypeValue.VALID,    1);
builder.valueAt(StatusTypeValue.VALID,    2);
builder.valueAt(StatusTypeValue.INVALID,  3);
builder.valueAt(StatusTypeValue.INVALID,  4);
builder.valueAt(StatusTypeValue.INVALID,  5);
builder.valueAt(StatusTypeValue.VALID,    6);
builder.valueAt(StatusTypeValue.INVALID,  7);
builder.valueAt(StatusTypeValue.INVALID,  8);
builder.valueAt(StatusTypeValue.INVALID,  9);
builder.valueAt(StatusTypeValue.VALID,   10);
builder.valueAt(StatusTypeValue.VALID,   11);
builder.valueAt(StatusTypeValue.VALID,   12);
builder.valueAt(StatusTypeValue.INVALID, 13);
builder.valueAt(StatusTypeValue.VALID,   14);
builder.valueAt(StatusTypeValue.INVALID, 15);

// Create a StatusList instance
StatusList statusList = builder.build();

StatusList is a subclass of CBORItem, so you can use the encodeToHex() method to represent it in hexadecimal,

System.out.println(statusList.encodeToHex());

a2646269747301636c73744a78dadbb918000217015d

or use the toString() or prettify() methods to represent it in CBOR Diagnostic Notation.

System.out.println(statusList.prettify());

{
  "bits": 1,
  "lst": h'78dadbb918000217015d'
}

By the way, if you convert the byte array to a base64url string using the Base64UrlAdapter introduced in “GSON: Converting Byte Arrays to and from Base64URL Strings” (or by any other method—what matters is simply converting the lst value from a byte array to a base64url string),

// Create a Gson instance with Base64UrlAdapter enabled
Gson gson = new GsonBuilder()
        .registerTypeAdapter(byte[].class, new Base64UrlAdapter())
        .setPrettyPrinting()
        .create();

// Convert the CBORItem into a general-purpose Java object using
// the parse() method
Object statusListObject = statusList.parse();

// Convert to JSON
String json = gson.toJson(statusListObject);

// Output the JSON
System.out.println(json);

you can generate JSON that complies with the requirements defined in Section 4.2. Status List in JSON Format of the TSL specification.

{
  "bits": 1,
  "lst": "eNrbuRgAAhcBXQ"
}

Conclusion

When you need to work with CBOR in Java, please give the authlete/cbor library a try. Authlete itself also uses the authlete/cbor library in its implementation of OpenID for Verifiable Credential Issuance 1.0 (OID4VCI).

We also operate a website called CBOR Zone, which allows you to convert CBOR data between the following formats. It’s quite handy, so be sure to check it out!

• Hexadecimal
• Base64
• Base64URL
• Diagnostic Notation

(This screenshot shows the conversion from the hexadecimal representation of a StatusList to Diagnostic Notation.)

With GSON’s default behavior, serializing a byte array results in an array of numbers.

// Create a Map instance representing the following data structure:
//
//   {
//     "binary": [ 18, 52, 86 ]
//   }
//
Map<String, Object> input = new LinkedHashMap<>();
input.put("binary", { (byte)0x12, (byte)0x34, (byte)0x56 };

// Prepare a Gson instance.
Gson gson = new GsonBuilder().setPrettyPrinting().create();

// Convert the data to JSON.
String json = gson.toJson(input);

// Print the JSON.
System.out.println(json);

Output produced by the code above:

{
  "binary": [
    18,
    52,
    86
  ]
}

However, in some cases, you may want to serialize a byte array as a base64url-encoded string, as shown below.

{
  "binary": "EjRW"
}

This article explains how to configure GSON to perform bidirectional conversion between byte arrays and base64url-encoded strings.

TypeAdapter

If you want to customize the conversion logic for a specific type, you create a subclass of TypeAdapter and register it with GsonBuilder.

The TypeAdapter class has two abstract methods that must be implemented. One is the write method, which is called during serialization, and the other is the read method, which is called during deserialization.

In the context of this blog post, the write method converts the given byte array into a base64url-encoded string and writes it out, while the read method reads a base64url-encoded string, converts it into a byte array, and returns it.

An implementation of this logic looks like the following:

package com.example;


import java.io.IOException;
import java.util.Base64;
import com.google.gson.TypeAdapter;
import com.google.gson.stream.JsonReader;
import com.google.gson.stream.JsonToken;
import com.google.gson.stream.JsonWriter;


public class Base64UrlAdapter extends TypeAdapter<byte[]>
{
    @Override
    public void write(JsonWriter out, byte[] value) throws IOException
    {
        if (value == null)
        {
            // Write null.
            out.nullValue();
        }
        else
        {
            // Conver the byte array into a base64url-encoded string
            // and write it.
            out.value(toBase64Url(value));
        }
    }


    @Override
    public byte[] read(JsonReader in) throws IOException
    {
        if (in.peek() == JsonToken.NULL)
        {
            // Read null and return null.
            in.nextNull();
            return null;
        }

        // Read a base64url-encoded string and convert it to a byte array.
        return fromBase64Url(in.nextString());
    }


    private static String toBase64Url(byte[] value)
    {
        // Convert the byte array into a base64url-encoded string.
        return Base64.getUrlEncoder().withoutPadding().encodeToString(value);
    }


    private static byte[] fromBase64Url(String value)
    {
        // Convert the base64url-encoded string into a byte array.
        return Base64.getUrlDecoder().decode(value);
    }
}

Once you register the Base64UrlAdapter implemented above with GsonBuilder using the registerTypeAdapter method and then create a Gson instance, the setup is complete.

Gson gson = new GsonBuilder()
        .registerTypeAdapter(byte[].class, new Base64UrlAdapter())
        .create();

Code Examples

The following are code examples for serializing a byte array to a base64url string and for deserializing a base64url string back into a byte array.

@Test
public void test_to_base64url()
{
    // Create a Gson instance with Base64UrlAdapter enabled.
    Gson gson = new GsonBuilder()
            .registerTypeAdapter(byte[].class, new Base64UrlAdapter())
            .create();

    // Create a Map instance representing the following data structure:
    //
    //   {
    //     "binary": [ 18, 52, 86 ]
    //   }
    //
    Map<String, Object> input = new LinkedHashMap<>();
    input.put("binary", new byte[]{ (byte)0x12, (byte)0x34, (byte)0x56 });

    // Convert the data to JSON.
    String json = gson.toJson(input);

    // The JSON content should be {"binary":"EjRW"}
    assertEquals(json, "{\"binary\":\"EjRW\"}");
}

@Test
public void test_from_base64url()
{
    // Create a Gson instance with Base64UrlAdapter enabled.
    Gson gson = new GsonBuilder()
            .registerTypeAdapter(byte[].class, new Base64UrlAdapter())
            .create();

    // Prepare a JSON string with the content {"binary":"EjRW"}
    String input = "{\"binary\":\"EjRW\"}";

    // Deserialize the JSON and obtain an instance of the Data class.
    Data data = gson.fromJson(input, Data.class);

    // Verify that the byte array data.binary has length 3 and that
    // its elements are (byte)0x12, (byte)0x34, and (byte)0x56 in order.
    assertNotNull(data.binary);
    assertEquals(3, data.binary.length);
    assertEquals((byte)0x12, data.binary[0]);
    assertEquals((byte)0x34, data.binary[1]);
    assertEquals((byte)0x56, data.binary[2]);
}


private static class Data
{
    byte[] binary;
}

Conclusion

In the Token Status List specification, the value of the lst property in the StatusList structure is a byte array in the CBOR format, but a base64url-encoded string in the JSON format. When dealing with such data structures, the Base64UrlAdapter created in this article may be useful.

There is an authorization policy language called Cedar Policy Language. Policies written in this language are called Cedar Policies. In this article, we look at how to associate Cedar Policies with access tokens and use them for fine-grained access control.

Advantages of Cedar Policy

One of the major advantages of Cedar Policy is that it allows authorization logic to be separated from business logic. Cedar Policies can be externalized and managed independently from application code. In fact, there are commercial services available that manage Cedar Policies (see Integrations).

Another major advantage of Cedar Policy is that it enables authorization logic to be expressed with fine-grained control. For example, it is possible to describe an authorization rule such as: “If a user is a friend of Jane, they are allowed to view and comment on photos in Jane’s travel album.” Below is an example of a Cedar Policy excerpted from the Example Scenario in the Cedar Policy Language Reference Guide that expresses this authorization logic.

permit (
    principal in Group::"janeFriends",
    action in [Action::"view", Action::"comment"],
    resource in Album::"janeTrips"
);

In Cedar Policy, you can add when and unless clauses to specify the conditions under which a policy applies. Within these conditions, you can use comparison operators, logical operators, arithmetic operators, and more, providing a high level of expressiveness.

permit (
    principal,
    action == Action::"read",
    resource
)
when {
    resource.owner == principal ||
    resource.tag == "public"
};

Cedar Policy in RAR Object

By associating scopes (RFC 6749, Section 3.3) with an access token, it is possible to express coarse-grained permissions for that access token. In a similar way, if Cedar Policies could be associated with an access token, it should be possible to express fine-grained permissions for that access token.

One promising approach to realizing this idea is to represent Cedar Policies as RAR objects (RFC 9396).

✏️ NOTE: The OAuth 2.0 Rich Authorization Requests specification (RFC 9396), commonly known as RAR, does not use the term “RAR object.” However, at an event, one of the authors of the specification referred to each element in the authorization_details array that way. I found the term convenient, so I use “RAR object” in the following discussion as well.

The idea of representing Cedar Policies as RAR objects has been discussed in the past, for example in the IETF individual draft draft-cecchetti-oauth-rar-cedar (now expired) and in forums such as the OAuth Working Group at IETF 119.

However, after reviewing the earlier discussions, I could not find a design that fully met my needs. Therefore, I decided to design one myself. In the next section, I will describe the considerations that guided this design.

Designing Cedar Policy as a RAR Object

Choosing a Notation for Cedar Policies

The original notation of Cedar Policy is distinctive. Whether this notation should be embedded into a RAR object as-is, or first converted into JSON (JSON Policy Format) and then embedded, is a point on which opinions may differ.

While the JSON format has good affinity with RAR, it is verbose — especially in the representation of when and unless conditions—and many in the Cedar community are likely to prefer the original notation. For this reason, standardizing on only one notation could cause issues later. In such cases, it is safer to design the specification so that both notations are supported.

This leads to a further design decision: whether the notation should be specified using the mandatory type property of a RAR object (RFC 9396, Section 2), or whether a new property (for example, format) should be introduced.

If the type property were used, its value would need to convey two meanings at once—namely, that the object represents a Cedar Policy and which notation is used—resulting in values such as cedar-policy-native or cedar-policy-json.

At first glance, overloading a single property with two distinct meanings seems like a poor design choice. Moreover, it raises the question of whether Cedar Policy is the only Cedar-related artifact that might need to be represented in RAR. It is conceivable that Cedar Policies and Cedar Policy Templates might need to be treated as distinct entities. There is also the possibility that Cedar Schemas could be represented as RAR objects in the future. In such cases, the type property would be better suited for distinguishing among these artifacts.

In conclusion, a format property is introduced, whose value is either cedar or json, allowing the original notation or the JSON notation to be selected. Furthermore, based on the expectation that more users will prefer the original notation, cedar is defined as the default value when the format property is omitted.

type Property

In a RAR object, the type property is mandatory (RFC 9396, Section 2). It has been decided that the value of this property will indicate that the content of the RAR object is a Cedar Policy, but the concrete value must still be defined.

The first candidate that comes to mind is the string cedar. However, as mentioned in the previous section, choosing cedar would likely cause problems if there is a future need to distinguish among Cedar Policy, Cedar Policy Template, and Cedar Schema.

Taking these considerations into account, it seems appropriate to use cedar-policy as the value of the type property to indicate that the object represents a Cedar Policy.

Cedar Policy Set

There is also a design choice between representing a single Cedar Policy in one RAR object or representing a Cedar Policy Set.

In Representing a Policy Set with JSON, the JSON representation of a Cedar Policy Set contains staticPolicies, templates, and templateLinks within a single JSON object. In principle, it would be possible to embed equivalent information into a single RAR object.

However, I could not shake the concern that, in the context of RAR, support for templates might not be necessary in the first place. When a Cedar Policy is embedded statically in a RAR object, it seems likely that any placeholders in templates would already be resolved before embedding.

That said, the decision was not straightforward, so I chose to defer it. For the time being, a Cedar Policy Set is represented using multiple RAR objects within the authorization_details array. If operational experience later reveals issues with this approach, the mapping of a Cedar Policy Set to RAR objects can be revisited and redesigned at that point.

principal, action, resource

Within a Cedar Policy, the principal, action, and resource are referenced. What values should these have?

A Cedar Policy embedded in a RAR object is evaluated when the access token to which that RAR object is attached is used to access a resource. Therefore, the values of principal, action, and resource should align with this context.

For principal, it is natural to use the subject associated with the access token (a typical example being a user ID). Following common Cedar Policy examples, using User as the entity type would be appropriate. With this approach, a condition such as “the principal is the user user001” can be expressed as follows.

principal == User::"user001"

However, access tokens issued via the Client Credentials flow (RFC 6749, Section 4.4) are not associated with a user. In such cases, the entity type should be Client.

principal == Client::"app001"

✏️ NOTE: At this point, I am not yet certain whether it is a good idea to distinguish between cases where an access token is associated with a subject and cases where it is not.

If an access token contains groups, roles, or entitlements attributes (RFC 9068, Section 2.2.3), it would be reasonable to map each of them to Group, Role, and Entitlement entities, respectively, and set them as parent entities of the principal. This would allow the use of the in operator within Cedar Policies.

principal in Group::"group1"

The value of principal is determined by the authorization server at the time the access token is issued. In contrast, action and resource belong to the resource server, and it is preferable to let the resource server define their concrete values.

For example, a server implementing the Shared Signals Framework might define the action of creating a stream as SSF::Stream::Action::"create". In that case, a Cedar Policy could include a statement such as the following.

action == SSF::Stream::Action::"create"

context

I believe that, as variables available in the context referenced from when and unless clauses in a Cedar Policy, at least the following can be provided in any environment.

• time — The current time expressed as milliseconds elapsed since the Unix epoch.
• access_token — Information about the access token. It has sub-properties such as iss, sub, and client_id.
• ip_address — The client’s IP address.

Design Summary

Properties

• type — REQUIRED. The value is fixed to cedar-policy.
• format — OPTIONAL. cedar (default) or json.
• policy_id — OPTIONAL. Policy ID.
• policy — REQUIRED. The Cedar Policy. If the value of the format property is cedar, this is a single string representing a Cedar Policy written in the native Cedar syntax. If the value of the format property is json, this is a JSON object representing a Cedar Policy written in the JSON Policy Format.

Entities

• principal — If an access token is associated with a subject (i.e., the introspection response or the payload of a JWT access token contains a sub claim), the entity of principal is User. Otherwise, it is Client. For a User entity, the value of the sub claim in the access token is treated as the unique identifier. For a Client entity, the value of the client_id in the access token is treated as the unique identifier. Each element of groups, roles, and entitlements in the access token (RFC 9068, Section 2.2.3) is mapped to a Group, Role, or Entitlement entity, respectively, and is set as a parent entity of the principal. If the token follows RFC 7643, Section 2.4, each element is expected to be a JSON object with a value property (e.g., "groups":[{"value":"group1"}]), and the value of that value property is treated as the unique identifier of the entity. If it does not follow RFC 7643, Section 2.4, the element is assumed to be a JSON string (e.g., "groups":["group1"]), and the string value itself is treated as the unique identifier of the entity.
• action — The entity of action is defined by the resource server.
• resource — The entity of resource is defined by the resource server.

Context

• time — The current time expressed as milliseconds elapsed since the Unix epoch.
• access_token — Information about the access token. It has sub-properties such as iss, sub, and client_id.
• ip_address — The client’s IP address.

Examples of Cedar Policies in RAR Objects

Based on the design described above, examples of Cedar Policies in RAR objects are as follows.

[
  {
    "type":      "cedar-policy",
    "format":    "cedar",
    "policy_id": "policy-0",
    "policy":    "permit (principal == User::\"12UA45\", action == Action::\"view\", resource);" 
  },
  {
    "type":      "cedar-policy",
    "format":    "json",
    "policy_id": "policy-1",
    "policy": {
      "effect":  "permit",
      "principal": { "op": "==", "entity": { "type": "User",   "id": "12UA45" } },
      "action":    { "op": "==", "entity": { "type": "Action", "id": "view"   } },
      "resource":  { "op": "All" }
    }
  }
]

This example contains two RAR objects. The first describes a Cedar Policy using the original Cedar syntax, and the second describes the Cedar Policy using the JSON format. However, both represent exactly the same policy semantics.

Cedar Policies for Admin-Issued Access Tokens

In standardized authorization flows, an access token is issued as a result of the client requesting it. Therefore, in those flows, the client specifies the set of RAR objects to be associated with the access token by using the authorization_details request parameter. However, in real-world commercial systems, it is quite common to issue access tokens without using standardized flows—that is, in so-called out-of-band ways.

If one assumes only scenarios in which the client specifies RARs, embedding Cedar Policies in RARs may seem unnatural. In other words, it may feel odd for a client to request complex Cedar Policies on its own. However, when considering cases where a server administrator manually creates an access token and hands it to a client application, the ability to embed Cedar Policies in RAR objects becomes useful.

For example, when a server administrator issues an access token for demonstration purposes, they might want to grant broad permissions while preventing accidental deletion of a demo stream. In such a case, the administrator could associate the following Cedar Policies with the access token.

[
  {
   "type": "cedar-policy",
    "policy": "permit(principal,action,resource);"
  },
  {
    "type": "cedar-policy",
    "policy": "forbid(principal,action==SSF::Stream::Action::\"delete\",resource==SSF::Stream::\"stj3odpcfg19u6q62t2h7k0uk3t7srkdai6e0ccd7jd4ognt\");"
  }
]

In this example, executing the SSF::Stream::Action::"delete" action on the resource SSF::Stream::"stj3odpcfg19u6q62t2h7k0uk3t7srkdai6e0ccd7jd4ognt"—a Shared Signals Framework stream prepared for demonstration purposes—is forbidden.

Demo Videos

Cedar Policy in RAR Object is not merely a theoretical idea; it has been implemented in practice and demonstrated to work.

In a LinkedIn Post

• https://www.linkedin.com/feed/update/urn:li:activity:7348451868018122752/

In an online study session (in Japanese)

Conclusion

Personally, I believe the question of whether Cedar Policy in RAR Object is useful has already been answered. Its usefulness has been demonstrated in a new product currently under development at our company, and a certain public-sector organization has also shown strong interest in it as a means of addressing challenges in a national strategic project.

It would be great if a specification for Cedar Policy in RAR Object were standardized, but I personally am too busy to devote time to the standardization discussions. Hopefully, it will be standardized in a form close to the implementation presented in this article.

I have published an open-source Java library, authlete/http-message-signatures, which implements the RFC 9421 HTTP Message Signatures specification. Last month, I received feedback pointing out that the library lacked a test demonstrating the procedure for reconstructing the signature base for signature verification (Issue 1).

Due to various circumstances, the writing of detailed documentation has been postponed, so at present, understanding how to use the library requires reading the implementation and test code. To address this, I added a test case, RFC9421Test.java, which verifies an HTTP message signature based on the examples provided in the Appendix of RFC 9421.

In this article, we walk through the procedure for verifying HTTP message signatures, following that test code step by step.

🗒️ NOTE: For an overview of RFC 9421, please refer to the section “HTTP Message Signature” in the document “Comprehensive API Protection with Standard Specifications” available on the Authlete website.

HTTP Message Signature Verification Procedure

Parse the Signature HTTP Field

A signed HTTP message includes a Signature HTTP field. RFC 9421, section B.2.4 “Signing a Response Using ecdsa-p256-sha256”, provides the following example.

Signature: sig-b24=:wNmSUAhwb5LxtOtOpNa6W5xj067m5hFrj0XQ4fvpaCLx0NK\
  ocgPquLgyahnzDnDAUy5eCdlYUEkLIj+32oiasw==:

The value of the Signature HTTP field is formatted as a Dictionary (RFC 8941, Section 3.2). Each individual key–value pair consists of an arbitrary label and a signature represented as a Byte Sequence (RFC 8941, Section 3.3.5).

Signature: label=:base64-encoded-signature:, label=:base64-encoded-signature:, ...

The http-message-signatures library provides a utility class called SignatureField that represents the Signature HTTP field, so you can use it to parse the field.

// The value of the Signature HTTP field
String signatureFieldValue =
        "sig-b24=:wNmSUAhwb5LxtOtOpNa6W5xj067m5hFrj0XQ4fvpaCLx0NK" +
        "ocgPquLgyahnzDnDAUy5eCdlYUEkLIj+32oiasw==:";

// Parse the value of the Signature HTTP field
SignatureField signatureField =
        SignatureField.parse(signatureFieldValue);

Parse the Signature-Input HTTP Field

A signed HTTP message also includes a Signature-Input HTTP field. RFC 9421, section B.2.4 “Signing a Response Using ecdsa-p256-sha256”, provides the following example.

Signature-Input: sig-b24=("@status" "content-type" \
  "content-digest" "content-length");created=1618884473\
  ;keyid="test-key-ecc-p256"

The value of the Signature-Input HTTP field is also formatted as a Dictionary (RFC 8941, Section 3.2). Each individual key–value pair consists of an arbitrary label and metadata represented as an Inner List (RFC 8941, Section 3.1.1).

Signature-Input: label=(component identifiers)optional parameters, label=(component identifiers)optional parameters, ...

The http-message-signatures library provides a utility class called SignatureInputField that represents the Signature-Input HTTP field, so you can use it to parse the field.

// The value of the Signature-Input HTTP field
String signatureInputFieldValue =
        "sig-b24=(\"@status\" \"content-type\" " +
        "\"content-digest\" \"content-length\");created=1618884473" +
        ";keyid=\"test-key-ecc-p256\"";

// Parse the value of the Signature-Input HTTP field
SignatureInputField signatureInputField =
        SignatureInputField.parse(signatureInputFieldValue);

Extract Signature-Metadata Pairs

Signatures and metadata are placed separately in the Signature HTTP field and the Signature-Input HTTP field, respectively. A signature and its corresponding metadata are associated by sharing the same label. In the example in RFC 9421, Section B.2.4, the label sig-b24 is used.

The process of examining both the Signature HTTP field and the Signature-Input HTTP field and extracting pairs of signatures and metadata is handled by the scan method of the SignatureEntry class.

Map<String, SignatureEntry> signatureEntries =
        SignatureEntry.scan(signatureField, signatureInputField);

The keys of the Map instance returned by the scan method are the labels. By specifying a label, a particular SignatureEntry instance can be retrieved.

SignatureEntry signatureEntry = signatureEntries.get("sig-b24");

The SignatureEntry class has properties that represent the label (String), the signature (byte[]), and the metadata (SignatureMetadata). They can be accessed via the getLabel(), getSignature(), and getMetadata() methods, respectively.

Prepare Component Values

In the test suite in RFC 9421, Section B.2 “Test Cases”, the following HTTP message is commonly used for tests that operate on HTTP responses.

HTTP/1.1 200 OK
Date: Tue, 20 Apr 2021 02:07:56 GMT
Content-Type: application/json
Content-Digest: sha-512=:mEWXIS7MaLRuGgxOBdODa3xqM1XdEvxoYhvlCFJ41Q\
  JgJc4GTsPp29l5oGX69wWdXymyU0rjJuahq4l5aGgfLQ==:
Content-Length: 23

{"message": "good dog"}

Before constructing the signature base, it is necessary to prepare a SignatureContext to access the set of HTTP message components contained in this HTTP message (RFC 9421, Section 2 “HTTP Message Components”).

By using the ComponentValueProvider class, an implementation of the SignatureContext interface can be prepared relatively easily.

class ResponseSignatureContext extends ComponentValueProvider
{
    ResponseSignatureContext()
    {
        setStatus(200);
        setHeaders(buildHeaders());
    }

    private static Map<String, List<String>> buildHeaders()
    {
        Map<String, List<String>> headers = new LinkedHashMap<>();

        headers.put("Date",           List.of("Tue, 20 Apr 2021 02:07:56 GMT"));
        headers.put("Content-Type",   List.of("application/json"));
        headers.put("Content-Digest", List.of("sha-512=:mEWXIS7MaLRuGgxOBdODa3xqM1XdEvxoYhvlCFJ41QJgJc4GTsPp29l5oGX69wWdXymyU0rjJuahq4l5aGgfLQ==:"));
        headers.put("Content-Length", List.of("23"));

        return headers;
    }
}

Construct the Signature Base

By providing a SignatureContext and SignatureMetadata to the utility class SignatureBaseBuilder, you can generate a SignatureBase instance that represents the signature base.

SignatureBase signatureBase =
        new SignatureBaseBuilder(new ResponseSignatureContext())
        .build(signatureEntry.getMetadata());

Prepare the Verification Key

The HTTP message signature in B.2.4 is generated using the key from B.1.3, “Example ECC P-256 Test Key.” Based on this key, we prepare the key to be used for signature verification.

// The key from RFC 9421, B.1.3. Example ECC P-256 Test Key
// (NOTE: "alg" is added)
String TEST_KEY_ECC_P256 =
        "{\n" +
        "  \"kty\": \"EC\",\n" +
        "  \"alg\": \"ES256\",\n" +
        "  \"crv\": \"P-256\",\n" +
        "  \"kid\": \"test-key-ecc-p256\",\n" +
        "  \"d\": \"UpuF81l-kOxbjf7T4mNSv0r5tN67Gim7rnf6EFpcYDs\",\n" +
        "  \"x\": \"qIVYZVLCrPZHGHjP17CTW0_-D9Lfw0EkjqF7xB4FivA\",\n" +
        "  \"y\": \"Mc4nN9LTDOBhfoUeg8Ye9WedFRhnZXZJA12Qp0zZ6F0\"\n" +
        "}";

// Prepare the verification key
// (NOTE: JWK is a class from the Nimbus JOSE + JWT library)
JWK verificationKey = JWK.parse(TEST_KEY_ECC_P256).toPublicJWK();

Prepare the Verifier

A signature verifier is represented by the HttpVerifier interface. If a JWK instance is available, you can create an instance of JoseHttpVerifier, which is an implementation of this interface.

HttpVerifier verifier = new JoseHttpVerifier(verificationKey);

Verify the Signature

The signature can be verified by passing a signature verifier (HttpVerifier) and the signature (byte[]) to the verify method of the SignatureBase class. If the signature passes verification, the return value is true.

boolean verified = signatureBase.verify(verifier, signatureEntry.getSignature());

Conclusion

HTTP message signatures can be used as one mechanism for protecting APIs. They are introduced in the online document “Comprehensive API Protection with Standard Specifications”, so please take a look.

In the November 25, 2025 version of the MCP specification, CIMD was adopted as one of the standard specifications that make up MCP (MCP 2025–11–25 Authorization).

While an explanation of CIMD itself is covered in the Authlete website document “OAuth Client ID Metadata Document (CIMD)”, this article focuses on how to adjust client metadata obtained through the CIMD mechanism.

No Way to Verify a Client’s Trustworthiness

People are riding the wave of excitement, saying, “CIMD replaces DCR!”

📝 NOTE: DCR stands for Dynamic Client Registration and, depending on the context, refers to OpenID Connect Dynamic Client Registration 1.0, RFC 7591 OAuth 2.0 Dynamic Client Registration Protocol, or both.

However, let’s calm down. The idea of using a URL as the “client ID” in OAuth 2.0 or OpenID Connect and retrieving client metadata from the location reachable via that URL had already been realized, even before CIMD, in the OpenID Federation 1.0 specification (see the explanatory article).

The functionality of “fetching client metadata from a remote server during request processing, dynamically registering the client based on it, and then continuing to process the request as if nothing happened” has a significant impact on the implementation of an authorization server. After all, it affects every place where a client ID can appear.

📝 NOTE: The client ID may appear in obvious places, such as the client_id request parameter in authorization requests or token requests. However, it can also appear in less obvious places hidden in the details of individual specifications — for example, in the iss claim of a client assertion (RFC 7523) or a request object (RFC 9101), or in the aud claim of an ID token (OIDC Core) or a JWT Authorization Response (JARM).

Moreover, dynamically retrieved client metadata has an expiration time, so the authorization server must also implement logic to re-fetch the latest metadata.

For these reasons, you may find the CIMD specification overwhelming at first.

However, for those who are familiar with OpenID Federation 1.0, the reaction is quite the opposite: CIMD looks too simple — or even too lax from a security perspective.

The CIMD specification does not define any way to verify whether a client is a trustworthy communication partner. As a result, unless an authorization server implementation imposes some form of custom restrictions, anyone can freely register a client with an authorization server that supports CIMD. This stands in contrast to OpenID Federation 1.0, which explicitly defines how to establish trust relationships between entities using trust chains.

📝 NOTE: Authlete’s CIMD implementation includes a feature for configuring an allowlist, which lets you restrict the URLs that are considered valid as client IDs. By using this feature, you can avoid the problem of “anyone being able to register a client arbitrarily.”

No Way to Adjust Client Metadata

The CIMD specification was promoted from an individual draft to an IETF working group draft just two months ago, in October 2025, so at this point there are only a limited number of real, working implementations. Against that backdrop, Visual Studio Code publishes its CIMD client metadata at
https://vscode.dev/oauth/client-metadata.json.

{
  "client_name": "Visual Studio Code",
  "grant_types": [
    "authorization_code",
    "refresh_token",
    "urn:ietf:params:oauth:grant-type:device_code"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none",
  "application_type": "native",
  "client_id": "https://vscode.dev/oauth/client-metadata.json",
  "client_uri": "https://vscode.dev/product",
  "redirect_uris": [
    "http://127.0.0.1:33418/",
    "https://vscode.dev/redirect"
  ]
}

The above is Visual Studio Code’s client metadata as of December 15, 2025. If this metadata is registered as-is, a CIMD implementation that follows the OpenID Connect Dynamic Client Registration 1.0 specification (DCR) would set the value of the client’s id_token_signed_response_alg property to RS256. This is because the DCR specification defines RS256 as the default value when id_token_signed_response_alg is omitted.

As a result, the ID tokens issued to that client will be signed using RS256. However, some servers do not allow this algorithm, which leads to a situation where the client can be registered successfully, but ID tokens cannot be issued.

📝 NOTE: The FAPI 2.0 Security Profile disallows the use of any algorithms other than PS256, ES256, and EdDSA using Ed25519.

However, since the CIMD specification does not even define a way to verify whether a client is a trustworthy communication partner, it naturally does not define any mechanism for adjusting metadata either.

Metadata Policy

On the other hand, OpenID Federation 1.0 defines a mechanism that allows metadata claimed by a leaf entity as its own to be modified based on the policies of trust anchors and intermediate authorities that make up the trust chain. Such policies are called Metadata Policies.

For example, suppose we have the following client metadata:

{
  "client_name": "Example Client",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none",
  "client_id": "https://example.com/client.json",
  "redirect_uris": [
    "https://example.com/redirect"
  ]
}

When the following metadata policy is applied to this client metadata,

{
  "id_token_signed_response_alg": {
    "default": "ES256",
    "one_of": ["ES256", "ES384", "ES512"]
  },
  "redirect_uris": {
    "add": [
      "http://localhost:12345/redirect"
    ]
  }
}

the following client metadata is obtained. Note that http://localhost:12345/redirect has been added to redirect_uris, and that a new id_token_signed_response_alg property with the value ES256 has been introduced.

{
  "client_name": "Example Client",
  "grant_types": [
    "authorization_code",
    "refresh_token"
  ],
  "response_types": [
    "code"
  ],
  "token_endpoint_auth_method": "none",
  "client_id": "https://example.com/client.json",
  "redirect_uris": [
    "https://example.com/redirect",
    "http://localhost:12345/redirect"
  ],
  "id_token_signed_response_alg": "ES256"
}

📝 NOTE: The syntax of metadata policies is defined in Section 6.1, “Metadata Policy,” of the OpenID Federation 1.0 specification.

CIMD Metadata Policy

OpenID Federation 1.0 defines a mechanism for adjusting metadata. However, the later CIMD specification does not include such a mechanism. Therefore, if equivalent functionality is desired, authorization servers or OpenID providers must implement it as a proprietary extension.

There are several possible ways to implement this, but since OpenID Federation 1.0 already defines a flexible metadata policy syntax (Section 6.1), it makes sense to leverage it.

And just as trust anchors and intermediate authorities in OpenID Federation 1.0 have metadata policies, the most straightforward approach is for the authorization server itself to have a metadata policy.

For this purpose, Authlete has added the following set of properties to the Service.

• cimdMetadataPolicyEnabled — A boolean value indicating whether a metadata policy should be applied to client metadata obtained via CIMD.
• cimdMetadataPolicy — The metadata policy to be applied to client metadata obtained via CIMD.

For example, by configuring these properties as shown below,

{
  "cimdMetadataPolicyEnabled": true,
  "cimdMetadataPolicy": "{\"id_token_signed_response_alg\":{\"default\":\"ES256\"}}"
}

you can set the default value of the id_token_signed_response_alg property to ES256.

Conclusion

Because the MCP specification has decided to recommend CIMD as a replacement for DCR, we will likely see a series of blog posts comparing CIMD and DCR for some time. However, I believe that CIMD should be compared not with DCR, but with OpenID Federation 1.0.

Such a comparison makes it clear what CIMD is missing and what kinds of additional features need to be implemented. The “CIMD Metadata Policy” feature introduced in this article is a capability that could only be designed and implemented by understanding the metadata policy defined in OpenID Federation 1.0 (Section 6.1).

Event Announcement

At the event “OpenID BizDay #18 ~ AIdentity × Security CollabDay”, scheduled to be held in Tokyo on December 19, 2025, a member of our team will give a lightning talk titled “Implementing an MCP OAuth 2.0 Authorization Server with Authlete,” which will include a CIMD demo. Stay tuned!

Liquibase is a tool for managing the revision history of database schema definitions.

Liquibase manages schema changes using changelogs, which are composed of multiple changesets. Each changeset describes a specific modification to be applied to the database.

In the official Liquibase documentation, two approaches are presented for structuring changelogs: one that is object-based and another that is release-based. In this article, I will refer to them as the object-oriented structure and the release-oriented structure, respectively.

Both approaches have their own strengths and weaknesses. This article introduces a hybrid structure that combines the advantages of both while mitigating their drawbacks.

Object-Oriented Structure

In the object-oriented structure, the changelog hierarchy is organized from the perspective of database objects such as tables, views, and indexes.

changelog-root.yaml
|
|-- changelog-table.yaml
|   |
|   |-- changelog-table-user.yaml
|   |
|   |-- ...
|
|-- changelog-view.yaml
|

The advantage of this structure is that it makes it easy to find the change history for a specific object. The downside, however, is that you can’t immediately tell which release a given change belongs to.

Release-Oriented Structure

In the release-oriented structure, the changelog hierarchy is organized from the perspective of releases.

changelog-root.yaml
|
|-- changelog-1.0.yaml
|   |
|   |-- changelog-1.0.0.yaml
|   |
|   |-- ...
|
|-- changelog-1.1.yaml
|

The advantage of this structure is that it makes it easy to see which changes are included in a particular release. Conversely, the drawback is that it becomes harder to track the change history for each individual object.

Hybrid Structure

Both structures have their own advantages and disadvantages. However, by combining these approaches, you can gain the benefits of both while eliminating their respective drawbacks. I will refer to this method as the hybrid structure.

This structure involves the following set of files:

• changelog.yaml — The root file
• changelog-version-X.Y[.Z].yaml — Files whose names include a version number
• changelog-date-YY-MM-DD.yaml — Files whose names include a date
• OBJECT-NAME-NNNN.yaml — Files whose names include the object type, object name, and a sequence number (changesets)

The relationships among these files are as follows:

• The root file, changelog.yaml, includes all changelog-version-X.Y.yaml files.
• Each changelog-version-X.Y.yaml file includes one or more changelog-version-X.Y.Z.yaml files.
• Each changelog-version-X.Y.Z.yaml file includes one or more changelog-date-YY-MM-DD.yaml files.
• Each changelog-date-YY-MM-DD.yaml file includes one or more OBJECT-NAME-NNNN.yaml files.

These files are placed in the following directory structure.

changelog.yaml
changelogs/version/X.Y/changelog-version-X.Y.yaml
changelogs/version/X.Y/changelog-version-X.Y.Z.yaml
changelogs/date/YYYY/MM/changelog-date-YYYY-MM-DD.yaml
chnagesets/OBJECT/NAME/OBJECT-NAME-NNNN.yaml

Hybrid Structure Example

Below is an example of a directory structure and file names when using the hybrid structure.

.
├── changelog.yaml
├── changelogs
│   ├── date
│   │   └── 2025
│   │       ├── 04
│   │       │   └── changelog-date-2025-04-09.yaml
│   │       ├── 06
│   │       │   └── changelog-date-2025-06-10.yaml
│   │       ├── 07
│   │       │   ├── changelog-date-2025-07-11.yaml
│   │       │   ├── changelog-date-2025-07-16.yaml
│   │       │   ├── changelog-date-2025-07-26.yaml
│   │       │   └── changelog-date-2025-07-28.yaml
│   │       ├── 08
│   │       │   └── changelog-date-2025-08-28.yaml
│   │       └── 09
│   │           └── changelog-date-2025-09-06.yaml
│   └── version
│       └── 1.0
│           ├── changelog-version-1.0.0.yaml
│           ├── changelog-version-1.0.1.yaml
│           ├── changelog-version-1.0.2.yaml
│           ├── changelog-version-1.0.3.yaml
│           ├── changelog-version-1.0.4.yaml
│           ├── changelog-version-1.0.5.yaml
│           ├── changelog-version-1.0.6.yaml
│           ├── changelog-version-1.0.7.yaml
│           └── changelog-version-1.0.yaml
└── changesets
    └── table
        ├── arena_key
        │   └── table-arena_key-0000.yaml
        ├── ssf_stream
        │   ├── table-ssf_stream-0000.yaml
        │   └── table-ssf_stream-0001.yaml
        ├── ssf_stream_event
        │   └── table-ssf_stream_event-0000.yaml
        ├── ssf_stream_subject
        │   └── table-ssf_stream_subject-0000.yaml
        ├── ssf_transmitter
        │   ├── table-ssf_transmitter-0000.yaml
        │   └── table-ssf_transmitter-0001.yaml
        └── ssf_transmitter_key
            └── table-ssf_transmitter_key-0000.yaml

# changelog.yaml
databaseChangeLog:
  - logicalFilePath: changelog.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.yaml

# changelog-version-1.0.yaml
databaseChangeLog:
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.0.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.1.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.2.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.3.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.4.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.5.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.6.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.7.yaml

# changelog-version-1.0.0.yaml
databaseChangeLog:
  - include:
      file: changelogs/date/2025/04/changelog-date-2025-04-09.yaml

# changelog-date-2025-04-09.yaml
databaseChangeLog:
  - include:
      file: changesets/table/ssf_transmitter/table-ssf_transmitter-0000.yaml

# table-ssf_transmitter-0000.yaml
databaseChangeLog:
  - changeSet:
      id: table-ssf_transmitter-0000
      author: authlete
      changes:
        - createTable:
            tableName: ssf_transmitter
            columns:
      # Omitted below

Considerations for Changesets

Each changeset has an id attribute and an author attribute. Liquibase identifies each changeset by combining these attribute values with the path to the root changelog file used when the liquibase command is executed. Based on whether this combination exists in the change tracking table (DATABASECHANGELOG), Liquibase determines whether the changeset should be applied.

However, in my project, each changeset is uniquely identified by its id attribute alone. The author attribute and the file path are intentionally kept identical across all changesets.

In the past, we used a convention where the author attribute contained an identifier for the developer who created the changeset. But in my experience, this approach has never provided any practical benefit. On the contrary, it felt increasingly odd that arbitrary developer-specific strings would remain permanently in the change tracking table and could never be modified later. For that reason, in new projects, we set the author attribute to a fixed string, authlete (our company name).

Another issue is that the file path becomes part of a changeset’s identifier. Even if the contents of a changeset remain unchanged, Liquibase will treat it as a different changeset if the file path changes. Moreover, even when the file path itself hasn’t changed, Liquibase may still treat it as a different changeset if it resolves the changelog or changeset location differently — for example, if the value of the LIQUIBASE_CLASSPATH environment variable changes. When using Liquibase via a Docker image, mounting a volume that contains the changelogs can also result in different paths. Frankly speaking, Liquibase’s design of using file paths as part of changeset identification is problematic.

You can avoid file-path-related issues by fixing the logical path of the changelog file using logicalFilePath in changelog.yaml. Below is the beginning of the changelog.yaml file. Note the logicalFilePath attribute.

# changelog.yaml
databaseChangeLog:
  - logicalFilePath: changelog.yaml
  - include:
      file: changelogs/version/1.0/changelog-version-1.0.yaml

Conclusion

The hybrid structure is something I devised myself, so it doesn’t have a track record in the wider community yet. However, if you’re struggling with how to structure your Liquibase changelogs, I encourage you to give it a try.

Selective Disclosure using JWTs — known as SD-JWT — has finally been published by the IETF as an official standard: RFC 9901 Selective Disclosure for JSON Web Tokens. Following RFC 9449 (DPoP), I’m grateful that my company, Authlete, is once again listed among the specification authors.

Because SD-JWT also serves as the foundation for SD-JWT VC, one of the formats for Verifiable Credentials, it is also gaining attention in the context of digital identity.

There are already numerous articles that cover the purpose and format of SD-JWT, so I won’t repeat those explanations here. Instead, this article assumes you are already familiar with the SD-JWT specification and focuses on how to actually read and write SD-JWTs in code.

Programming will be done using Authlete’s open-source Java SD-JWT library (authlete/sd-jwt). This library is used not only in Authlete’s implementation of the OpenID for Verifiable Credential Issuance 1.0 specification, but also in the official conformance suite provided by the OpenID Foundation.

• Source Code: https://github.com/authlete/sd-jwt
• JavaDoc: https://authlete.github.io/sd-jwt

Library Setup

The SD-JWT library is published in the Maven Central Repository under the name com.authlete:sd-jwt. You can use it by adding the following dependency to your pom.xml file:

<dependency>
    <groupId>com.authlete</groupId>
    <artifactId>sd-jwt</artifactId>
    <version>${sd-jwt.version}</version>
</dependency>

Replace ${sd-jwt.version} with the actual version number you intend to use.

NOTE: The SD-JWT library depends on GSON.

Disclosure

The following diagram illustrates the structure of an SD-JWT.

Disclosures are an essential component of SD-JWT. In this SD-JWT library, each Disclosure is represented by the Disclosure class.

A Disclosure consists of three elements — salt, claim name, and claim value — when it corresponds to a property of an object. In contrast, when it corresponds to an array element, it consists of only two elements: salt and claim value. The difference is simply whether a claim name is included.

To create a Disclosure representing an object property, use one of the following constructors, both of which accept the claim name as an argument:

Disclosure(String claimName, Object claimValue)
Disclosure(String salt, String claimName, Object claimValue)

When you use the constructor with two arguments, the salt is automatically generated inside the constructor.

// Three arguments passed to a Disclosure constructor
String salt       = "_26bc4LT-ac6q2KI6cBW5es";
String claimName  = "family_name";
Object claimValue = "Möbius";

// Create a Disclosure instance
Disclosure disclosure = new Disclosure(salt, claimName, claimValue);

// Two arguments passed to a Disclosure constructor
String claimName  = "family_name";
Object claimValue = "Möbius";

// Create a Disclosure instance with a salt generated automatically
Disclosure disclosure = new Disclosure(claimName, claimValue);

To create a Disclosure representing an array element, either pass null for the claim name argument or simply use the constructor that accepts only a single argument.

// A claim value (an array element)
Object claimValue = "array-element0";

// Create a Disclosure instance
Disclosure disclosure = new Disclosure(claimValue);

Once you have created a Disclosure instance, you can obtain its serialized form using either the getDisclosure() method or the toString() method.

// Serialize the Disclosure
// serialized1 and serialized2 will have the same value
String serialized1 = disclosure.getDisclosure();
String serialized2 = disclosure.toString();

You can create a Disclosure instance from its serialized form using the parse(String) method.

// Parse a serialized Disclosure
Disclosure disclosure = Disclosure.parse(
    "WyJfMjZiYzRMVC1hYzZxMktJNmNCVzVlcyIsICJmYW1pbHlfbmFtZSIsICJNw7ZiaXVzIl0");

Disclosure Digest

In the payload of the SD-JWT Issuer-signed JWT, it is not the Disclosure itself but the digest of the Disclosure that is included. You can obtain the digest using one of the following methods:

digest()
digest(String hashAlgorithm)

The digest() method without arguments calculates the digest using the default hash algorithm, SHA-256. On the other hand, the digest(String) method takes a String argument specifying the hash algorithm to use for computing the digest.

// Obtain the digest of a Disclosure using the default hash algorithm (SHA-256)
String digestSha256 = disclosure.digest();

// Obtain the digest using the SHA-512 hash algorithm
String digestSha512 = disclosure.digest("sha-512");

Selective Disclosure Object

The SDObjectBuilder class is a utility for creating a Map instance that represents a JSON object containing the _sd array.

A typical usage pattern for SDObjectBuilder is as follows:

1. Create an instance of SDObjectBuilder.
2. Add regular claims as needed.
3. Add digest values of Disclosures as needed.
4. Call the build() method to generate the Map instance.

// Create an SDObjectBuilder instance
SDObjectBuilder builder = new SDObjectBuilder();

// Add a regular claim
builder.putClaim("my_claim_name", "my_claim_value");

// Add the digest of a Disclosure
Disclosure disclosure = new Disclosure(
    "_26bc4LT-ac6q2KI6cBW5es", "family_name", "Möbius");
builder.putSDClaim(disclosure);

// Generate the Map instance
Map<String, Object> map = builder.build();

The Map instance obtained from the code above contains the same content as the following JSON:

{
    "my_claim_name": "my_claim_value",
    "_sd": [
        "TZjouOTrBKEwUNjNDs9yeMzBoQn8FFLPaJjRRmAtwrM"
    ]
}

If you want to specify a hash algorithm other than the default (SHA-256) for computing Disclosure digests in SDObjectBuilder, use the constructor that accepts the algorithm name as an argument.

// SDObjectBuilder constructor that takes a hash algorithm as an argument
SDObjectBuilder builder = new SDObjectBuilder("sha-512");

When generating the Map instance, if you call build(true) instead of build(), the name of the hash algorithm will be included in the Map as the value of the _sd_alg claim.

// Embed the hash algorithm in the Map
Map<String, Object> map = builder.build(true);

The following JSON illustrates the data contained in a Map instance generated using build(true):

{
    "_sd": [
        "j35wlGQlyQ8b4OE3Py6l3AAvOskjcNOxj0SsiVSrVdmVs8bapSUelViRDbmlntFABkp6_zSz1fA-dlWGUxGpEA"
    ],
    "_sd_alg": "sha-512"
}

Decoy Digest

To prevent an attacker from easily guessing the original number of claims, you can include meaningless Disclosure digest values that do not correspond to any actual claims. These digest values are called Decoy Digests (RFC 9901 Section 4.2.5, Decoy Digests).

You can add Decoy Digests using the putDecoyDigest() or putDecoyDigests(int) methods.

// Add a single Decoy Digest
builder.putDecoyDigest();

// Add the specified number of Decoy Digests
builder.putDecoyDigests(3);

Issuer-signed JWT

When an SD-JWT string is split by ~, the first element is a JWT. In RFC 9901, this JWT is called the Issuer-signed JWT. Note that in the authlete/sd-jwt library, which was implemented when the specification was still in flux, this JWT is referred to as the Credential JWT.

The authlete/sd-jwt library provides the SDObjectBuilder class as a utility for generating the payload of this JWT. However, the library does not provide utilities for creating the JWT itself.

This is an intentional design choice, allowing developers to use any JWT library they prefer. Personally, I recommend the Nimbus JOSE + JWT library, but the authlete/sd-jwt library itself does not depend on Nimbus JOSE + JWT.

Below is an example program that creates an Issuer-signed JWT. The SDObjectBuilder class from authlete/sd-jwt is used to generate the payload, while Nimbus JOSE + JWT classes are used for all other processing.

import java.text.*;
import java.util.*;
import com.authlete.sd.*;
import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.*;
import com.nimbusds.jose.jwk.*;
import com.nimbusds.jose.jwk.gen.*;
import com.nimbusds.jwt.*;

public class SDJWTExample
{
    public static void main(String[] args) throws Exception
    {
        // Prepare selectively-disclosable claims as a list of Disclosures
        List<Disclosure> disclosures = buildDisclosures();

        // Prepare regular claims
        Map<String, Object> regularClaims = buildRegularClaims();

        // Generate a private key to sign the Issuer-signed JWT
        ECKey privateKey = generatePrivateKey();

        // Create the Issuer-signed JWT
        String issuerSignedJwt =
            buildIssuerSignedJwt(disclosures, regularClaims, privateKey);

        // Output the Issuer-signed JWT
        System.out.println(issuerSignedJwt);
    }

    private static List<Disclosure> buildDisclosures()
    {
        // List of Disclosures
        List<Disclosure> disclosures = new ArrayList<>();

        // Add a Disclosure representing the claim "family_name":"Kawasaki"
        disclosures.add(new Disclosure("family_name", "Kawasaki"));

        // Add a Disclosure representing the claim "given_name":"Takahiko"
        disclosures.add(new Disclosure("given_name", "Takahiko"));

        return disclosures;
    }

    private static Map<String, Object> buildRegularClaims()
    {
        // Map of "claim name -> claim value"
        Map<String, Object> claims = new LinkedHashMap<>();

        // Add the claim "nickname":"Taka"
        claims.put("nickname", "Taka");

        // Add the "vct" claim according to the SD-JWT VC specification
        claims.put("vct", "https://credentials.example.com/identity_credential");

        return claims;
    }

    private static ECKey generatePrivateKey() throws JOSEException
    {
        // Generate a private key for the ES256 algorithm
        return new ECKeyGenerator(Curve.P_256).generate();
    }

    private static String buildIssuerSignedJwt(
        List<Disclosure> disclosures, Map<String, Object> regularClaims, ECKey privateKey)
        throws JOSEException, ParseException
    {
        // Create the payload part of the Issuer-signed JWT
        Map<String, Object> claims = buildPayload(disclosures, regularClaims);

        // Create the unsigned Issuer-signed JWT
        SignedJWT jwt = buildJwt(claims);

        // Sign the Issuer-signed JWT
        signJwt(jwt, privateKey);

        // Serialize the Issuer-signed JWT
        String serialized = jwt.serialize();

        return serialized;
    }

    private static Map<String, Object> buildPayload(
        List<Disclosure> disclosures, Map<String, Object> regularClaims)
    {
        // Create an SDObjectBuilder instance to construct the payload
        // of the Issuer-signed JWT. Here we use the default constructor,
        // so the hash algorithm will be the default (SHA-256).
        SDObjectBuilder builder = new SDObjectBuilder();

        // Add selectively-disclosable claims
        disclosures.forEach(builder::putSDClaim);

        // Add regular claims
        regularClaims.forEach((k, v) -> builder.putClaim(k, v));

        // Build the Map instance representing the payload.
        // This Map will include the "_sd" array.
        Map<String, Object> payload = builder.build();

        return payload;
    }

    private static SignedJWT buildJwt(Map<String, Object> payload)
        throws JOSEException, ParseException
    {
        // Create the header part of the Issuer-signed JWT
        //
        // The header will be {"alg":"ES256","typ":"dc+sd-jwt"}.
        // The "typ" value is defined in the SD-JWT VC specification.
        JWSHeader header =
            new JWSHeader.Builder(JWSAlgorithm.ES256)
                .type(new JOSEObjectType("dc+sd-jwt"))
                .build();

        // Convert the Map payload to a JWTClaimsSet using
        // the Nimbus JOSE + JWT library
        JWTClaimsSet claimsSet = JWTClaimsSet.parse(payload);

        // Create the unsigned Issuer-signed JWT
        SignedJWT jwt = new SignedJWT(header, claimsSet);

        return jwt;
    }

    private static void signJwt(SignedJWT jwt, ECKey privateKey) throws JOSEException
    {
        // Create a signer to perform signing
        JWSSigner signer = new ECDSASigner(privateKey);

        // Sign the JWT
        jwt.sign(signer);
    }
}

This program outputs an Issuer-signed JWT as follows:

eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9.eyJuaWNrbmFtZSI6IlRha2EiLCJfc2QiOlsiVmZ5X1MxeEVLQTc4c3Fsa19MMWlHLTZ6NnVkcFpwZGl2di1BMFBaNjNMVSIsImZsRWFDVnVEUWxidV9feDV4Vndpb25iVTIzdUtFZ1pZdW9NZG90Nnp4Y3MiXSwidmN0IjoiaHR0cHM6Ly9jcmVkZW50aWFscy5leGFtcGxlLmNvbS9pZGVudGl0eV9jcmVkZW50aWFsIn0.mYX7hh1jOzQLS_NlUEVgTaPG0sijFSYXGLqANDPQFJD3DAyS-NZSNVmHn_iQWu3Pa9Ev6DNnwOyAPTe-Eg4uEg

Decoding the header and payload of this Issuer-signed JWT using base64url yields the following JSONs:

{
  "typ": "dc+sd-jwt",
  "alg": "ES256"
}

{
  "nickname": "Taka",
  "_sd": [
    "Vfy_S1xEKA78sqlk_L1iG-6z6udpZpdivv-A0PZ63LU",
    "flEaCVuDQlbu__x5xVwionbU23uKEgZYuoMdot6zxcs"
  ],
  "vct": "https://credentials.example.com/identity_credential"
}

In the payload, the nickname and vct claims appear with their names and values as-is, but the family_name and given_name claims are not included. Instead, the _sd array contains the digest values corresponding to the family_name and given_name claims.

Since the original values cannot be derived from the digest values, this Issuer-signed JWT alone does not reveal the information "family_name":"Kawasaki" or "given_name":"Takahiko".

SD-JWT

An SD-JWT consists of:

• An Issuer-signed JWT
• Zero or more Disclosures
• An optional Key Binding JWT

<Issuer-signed JWT>~<Disclosure 1>~...~<Disclosure N>~[<Key Binding JWT>]

The SDJWT class in the SD-JWT library represents an SD-JWT and provides two constructors corresponding to the components described above:

SDJWT(String issuerSignedJwt, Collection<Disclosure> disclosures)
SDJWT(String issuerSignedJwt, Collection<Disclosure> disclosures, String keyBindingJwt)

In these constructors, the first argument is the serialized Issuer-signed JWT, and the second argument is a list of Disclosures.

NOTE: The argument representing the Issuer-signed JWT has the type String, not SignedJWT from the Nimbus JOSE + JWT library. Using String deliberately ensures that the SDJWT class does not depend on any specific JWT library.

By modifying the sample program mentioned earlier as shown below, you can generate an SD-JWT and output its serialized form.

      public static void main(String[] args) throws Exception
      {
          // Prepare selectively-disclosable claims as a list of Disclosures
          List<Disclosure> disclosures = buildDisclosures();

          // Prepare regular claims
          Map<String, Object> regularClaims = buildRegularClaims();

          // Generate a private key to sign the Issuer-signed JWT
          ECKey privateKey = generatePrivateKey();

          // Create the Issuer-signed JWT
          String issuerSignedJwt =
              buildIssuerSignedJwt(disclosures, regularClaims, privateKey);

-         // Output the Issuer-signed JWT
-         System.out.println(issuerSignedJwt);
+         // Create the SD-JWT
+         SDJWT sdjwt = new SDJWT(issuerSignedJwt, disclosures);
+
+         // Serialize the SD-JWT and output it
+         System.out.println(sdjwt);
      }

When you run the modified program, it outputs an SD-JWT like the following:

eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9.eyJuaWNrbmFtZSI6IlRha2EiLCJfc2QiOlsiQmxTRkNtLVJyLVc0UUZSV1pyb09keVNwV3BmUnVuTExGZDh4djB4VXJaVSIsIkk5Z2JrWGxNVEhHTThzTHNjenpVMDNlVEl2U1R2OWlnTlE5alpKLS1XYlkiXSwidmN0IjoiaHR0cHM6Ly9jcmVkZW50aWFscy5leGFtcGxlLmNvbS9pZGVudGl0eV9jcmVkZW50aWFsIn0.G365hmMY_Wp9vSVmifxKNXdVgxcXGuY_wevarIK95sgKFs6U8Me1a7WinSUVlQrWHDjT0AC9nM0GbYYV4hD6DQ~WyI5UFgwUXdUZXo3QlhOcjlkWVhpRVlnIiwiZmFtaWx5X25hbWUiLCJLYXdhc2FraSJd~WyJVTjByajNRTkJTeWJmSnNHY1NEYktBIiwiZ2l2ZW5fbmFtZSIsIlRha2FoaWtvIl0~

You can create an SDJWT instance from its serialized form by using the parse(String) method of the SDJWT class.

SDJWT sdjwt = SDJWT.parse(
    """\
    eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9.eyJua\
    WNrbmFtZSI6IlRha2EiLCJfc2QiOlsiQmxTRkNtLVJyLVc0UUZ\
    SV1pyb09keVNwV3BmUnVuTExGZDh4djB4VXJaVSIsIkk5Z2JrW\
    GxNVEhHTThzTHNjenpVMDNlVEl2U1R2OWlnTlE5alpKLS1XYlk\
    iXSwidmN0IjoiaHR0cHM6Ly9jcmVkZW50aWFscy5leGFtcGxlL\
    mNvbS9pZGVudGl0eV9jcmVkZW50aWFsIn0.G365hmMY_Wp9vSV\
    mifxKNXdVgxcXGuY_wevarIK95sgKFs6U8Me1a7WinSUVlQrWH\
    DjT0AC9nM0GbYYV4hD6DQ~WyI5UFgwUXdUZXo3QlhOcjlkWVhp\
    RVlnIiwiZmFtaWx5X25hbWUiLCJLYXdhc2FraSJd~WyJVTjBya\
    jNRTkJTeWJmSnNHY1NEYktBIiwiZ2l2ZW5fbmFtZSIsIlRha2F\
    oaWtvIl0~\
    """
    );

SDObjectDecoder

You can recover the original claim names and values by computing the digest values of each Disclosure contained in the SD-JWT and matching them against the digest values in the payload of the Issuer-signed JWT.

Since the original claim values can themselves be JSON objects containing an _sd array, the digest matching process may need to be performed recursively. A JSON object representing an array element that contains only a single key "..." is also subject to this processing.

Considering additional checks such as the _sd_alg claim, this matching process is not particularly difficult, but writing the implementation from scratch each time can be tedious. For this reason, the SD-JWT library provides a utility class called SDObjectDecoder that performs this matching process.

By using one of the decode methods of SDObjectDecoder, you can execute the matching process (see the JavaDoc of SDObjectDecoder for details).

The following sample program decodes the payload of the Issuer-signed JWT in an SD-JWT specified by the first argument and displays it in JSON format.

import java.util.*;
import com.authlete.sd.*;
import com.google.gson.*;
import com.nimbusds.jwt.*;

public class DecodeExample
{
    public static void main(String[] args) throws Exception
    {
        // Parse the first argument provided on the command line as an SD-JWT
        SDJWT sdjwt = SDJWT.parse(args[0]);

        // Convert the Issuer-signed JWT represented as a String
        // to an instance of SignedJWT from the Nimbus JOSE + JWT library
        SignedJWT jwt = SignedJWT.parse(sdjwt.getCredentialJwt());

        // Convert the payload of the Issuer-signed JWT to a Map instance
        // In most cases, this Map contains the _sd array
        Map<String, Object> encodedPayload =
            jwt.getJWTClaimsSet().toJSONObject();

        // Extract the list of Disclosures contained in the SD-JWT
        List<Disclosure> disclosures = sdjwt.getDisclosures();

        // Create an SDObjectDecoder that will replace digest values
        // in the payload with their corresponding claims
        SDObjectDecoder decoder = new SDObjectDecoder();

        // Compute the digest value of each Disclosure, match it with
        // the digest values in the payload, and replace the digest
        // values with the original claims
        Map<String, Object> decodedPayload =
            decoder.decode(encodedPayload, disclosures);

        // Convert the Map instance to JSON
        String decodedPayloadJson =
            new GsonBuilder().setPrettyPrinting().create().toJson(decodedPayload);

        // Output the JSON
        System.out.println(decodedPayloadJson);
    }
}

Assuming the shell variable SDJWT contains an SD-JWT:

SDJWT=eyJ0eXAiOiJkYytzZC1qd3QiLCJhbGciOiJFUzI1NiJ9.eyJuaWNrbmFtZSI6IlRha2EiLCJfc2QiOlsiQmxTRkNtLVJyLVc0UUZSV1pyb09keVNwV3BmUnVuTExGZDh4djB4VXJaVSIsIkk5Z2JrWGxNVEhHTThzTHNjenpVMDNlVEl2U1R2OWlnTlE5alpKLS1XYlkiXSwidmN0IjoiaHR0cHM6Ly9jcmVkZW50aWFscy5leGFtcGxlLmNvbS9pZGVudGl0eV9jcmVkZW50aWFsIn0.G365hmMY_Wp9vSVmifxKNXdVgxcXGuY_wevarIK95sgKFs6U8Me1a7WinSUVlQrWHDjT0AC9nM0GbYYV4hD6DQ~WyI5UFgwUXdUZXo3QlhOcjlkWVhpRVlnIiwiZmFtaWx5X25hbWUiLCJLYXdhc2FraSJd~WyJVTjByajNRTkJTeWJmSnNHY1NEYktBIiwiZ2l2ZW5fbmFtZSIsIlRha2FoaWtvIl0~

Running the sample program with $SDJWT as the first argument:

java -cp nimbus-jose-jwt.jar:sd-jwt.jar:gson.jar DecodeExample.java $SDJWT

produces the following JSON output:

{
  "family_name": "Kawasaki",
  "given_name": "Takahiko",
  "vct": "https://credentials.example.com/identity_credential",
  "nickname": "Taka"
}

Verification of SD-JWT VCs/VPs

Decoding the payload of an Issuer-signed JWT by matching it with Disclosures is straightforward using SDObjectDecoder. However, to trust the decoded content, you must verify the signature of the Issuer-signed JWT.

Additionally, if a Verifiable Presentation in SD-JWT format contains a Key Binding JWT (RFC 9901 Section 4.3, Key Binding JWT), you also need to verify the signature of that Key Binding JWT and check the sd_hash claim.

The VerificationTest.java included in the SD-JWT library tests serves as a sample for both generating SD-JWT–formatted Verifiable Credentials / Verifiable Presentations and verifying their signatures. You can refer to it as needed.

Other Topics

There are additional features not covered in this article, such as the SDObjectEncoder class for making the contents of a Map instance recursively selectively disclosable, and the Disclosure.toArrayElement() method for generating Map instances representing selectively disclosable array elements. For more details, please refer to the SD-JWT library documentation (README / JavaDoc) or the source code as needed.

Conclusion

Authlete has contributed to the development of many standards, and the SD-JWT specification (RFC 9901) is just one example. If you are interested in working on cutting-edge industry standards, be sure to check out Authlete’s Careers section!