Supporting JWT and Data Integrity style authentication

For the SSI Service, we aim to support a broad range of verifiable data use cases. There are two predominant methods for authenticating data in the SSI space—that is, putting the verifiable in verifiable data. The two methods, broadly, are using Data Integrity Style Proofs and using JSON Web Tokens, or JWTs.

Briefly, here is a comparison:

Data Integrity
Data Integrity refers to the family of mechanisms that utilize JSON-LD for

  1. Providing semantic tie-in to a set of known terms and properties used in a piece of data.
  2. Advocating for a process (known as Create-Verify-Hash) to normalize, canonicalize, hash, and generate a proof over a piece of data.

Data Integrity makes use of the Semantic Web – the original web3! – and builds on top of RDF and its canonicalization.

You can tell you’re using a Data Integrity proof when a document you encounter has a top-level @context property, which is core to JSON-LD, and the document has an embedded proof field as seen in this example in the VC Data Model. Using Data Integrity proofs requires use to pick a Linked Data Cryptosuite, which advocates for which keys and algorithms are to be used during the Create-Verify-Hash process.

There are many complexities in implementing and using JSON-LD and Data Integrity. It is an ‘open world’ model that allows for endless flexibility, and attempts to promote reuse without centralization.

JSON Web Tokens
JWTs were standardized back in 2015 in the IETF, and advocates for…

a compact, URL-safe means of representing claims to be transferred between two parties. The claims in a JWT are encoded as a JSON object that is used as the payload of a JSON Web Signature (JWS) structure or as the plaintext of a JSON Web Encryption (JWE) structure, enabling the claims to be digitally signed or integrity protected with a Message Authentication Code (MAC) and/or encrypted.

JWTs have been used widely throughout the internet and specifically in authN/Z protocols like OAuth 2.0, OpenID Connect, and much more! It’s likely you use both OAuth and OIDC nearly every day. The technologies power the interactions behind ‘Sign in with…’ buttons, and each time you connect one web account to another (e.g. giving an account access to your calendars, browsing history, email, and more).

JWTs are fairly simple, though the protocols around them can be a bit more complex. Extensions to JWTs normally rely on centralized registries, such as those hosted by IANA. JWTs are most often used within a framework called Javascript Object Signing and Encryption, or JOSE. JOSE provides a method to represent claims in a JWT, making use of JSON Web Signatures (JWS), JSON Web Encryption (JWE), and JSON Web Keys (JWKs).

Relation to the SSI Service
Though both methods can be applied to any type of data, there are also specific processing rules for certain types of data. For example, for Verifiable Credentials, plain old JOSE is insufficient. A new specification is being worked on in the W3C called VC-JWT that defines rules for signing and verifying JWTs that represent Verifiable Credentials. It is possible that similar rules apply to other objects too. As an additional example, specifications like Presentation Exchange and Credential Manifest are integrity-format agnostic, allowing ‘embed targets’ of multiple types which you can read about here.

Having a variety of integrity formats, key types, signing and verification algorithms, canonicalization schemes and so on can create a lot of complexity as an implementer of these systems! The SSI projects we work on are an attempt to wrangle this complexity, and limit confusion. To that end, our APIs need to support both. Luckily, there is precedent for supporting both representations…

In the W3C Claims & Credentials Group there has been an effort called Traceability Interoperability which attempts to describe discovery and exchange mechanisms for supply chain use cases. The spec not only covers data types, schemas, and processing workflows, but also provides an API for using and exchanging credentials related to traceability. One such API around issuing a credential returns a SerializedVerifiableCredentialObject, which is an XOR of VerifiableCredential, a Data Integrity style cred, and VC-JWT, the JWT representation, which can be seen here.

Our APIs will follow a similar path, exposing both, starting with a recent change supporting credential signing.

I am interested in improving the developer experience in limiting confusion, and am open to suggestions and contributions to improve the code an API. Some considerations…

  • The possibility of duplicate APIs for each signing representation
  • Service-level configuration to enable/disable one option
  • Needing more robust support around Data Integrity representations and supporting additional cryptosuites
  • How to surface processing and verification errors, and their configurability

Looking forward to hearing what you think!