This specification defines how Verifiable Credentials can be represented as JSON Web Tokens (JWT) [RFC7519] and secured using JSON Web Signatures (JWS) [RFC7515].

Introduction

JSON Web Token (JWT) [[!RFC7519]] is a widely-used means of expressing claims to be transferred between two parties. Providing a representation of the Verifiable Credentials Data Model for JWT allows existing systems and libraries to participate in the ecosystem described in Section . A JWT encodes a set of claims as a JSON object that is contained in a JSON Web Signature (JWS) [[!RFC7515]] and/or JSON Web Encryption (JWE) [[?RFC7516]]. For this specification, the use of JWE is out of scope.

Relation to the Verifiable Credentials Data Model

This specification defines encoding rules of the Verifiable Credential Data Model onto JWT and JWS. It further defines processing rules for how and when to make use of specific JWT-registered claim names and specific JWS-registered header parameter names to allow systems based on JWT to comply with this specification. If these specific claim names and header parameters are present, their respective counterpart in the standard verifiable credential and verifiable presentation MAY be omitted to avoid duplication.

JSON Web Token Extensions

This specification introduces two new registered claim names, which contain those parts of the standard verifiable credentials and verifiable presentations where no explicit encoding rules for JWT exist. These objects are enclosed in the JWT Claims Set as follows:

JWT and JWS Considerations
JWT Encoding

To encode a verifiable credential as a JWT, specific properties introduced by this specification MUST be either:

  • Encoded as standard JOSE header parameters, or
  • Encoded as registered JWT claim names, or
  • Contained in the JWS signature part.

If no explicit rule is specified, properties are encoded in the same way as with a standard credential, and the encoded properties are then added to the vc claim of the JWT. As with all JWTs, the JWS-based signature of a verifiable credential represented in the JWT syntax is calculated against the literal JWT string value as presented across the wire, before any decoding or transformation rules are applied. The following paragraphs describe these encoding rules.

If a JWS is present, the digital signature refers either to the issuer of the verifiable credential, or in the case of a verifiable presentation, to the holder of the verifiable credential. The JWS proves that the iss of the JWT signed the contained JWT Claims Set and therefore, the proof property can be omitted.

If no JWS is present, a proof property MUST be provided. The proof property can be used to represent a more complex proof, as may be necessary if the creator is different from the issuer, or a proof not based on digital signatures, such as Proof of Work. The issuer MAY include both a JWS and a proof property. For backward compatibility reasons, the issuer MUST use JWS to represent proofs based on a digital signature.

The following rules apply to JOSE headers in the context of this specification:

  • alg MUST be set for digital signatures. If only the proof property is needed for the chosen signature method (that is, if there is no choice of algorithm within that method), the alg header MUST be set to none.
  • kid MAY be used if there are multiple keys associated with the issuer of the JWT. The key discovery is out of the scope of this specification. For example, the kid can refer to a key in a DID document, or can be the identifier of a key inside a JWKS.

For backward compatibility with JWT processors, the following registered JWT claim names MUST be used, instead of or in addition to, their respective standard verifiable credential counterparts:

Other JOSE header parameters and JWT claim names not specified herein can be used if their use is not explicitly discouraged. Additional verifiable credential claims MUST be added to the credentialSubject property of the JWT.

For more information about using JOSE header parameters and/or JWT claim names not specified herein, see the Verifiable Credentials Implementation Guidelines [[?VC-IMP-GUIDE]] document.

This version of the specification defines no JWT-specific encoding rules for the concepts outlined in Section Advanced Concepts (for example, refreshService, termsOfUse, and evidence). These concepts can be encoded as they are without any transformation, and can be added to the vc JWT claim.

At the time of this writing, JWTs do not have a representation for multiple subjects and are thus not capable of encoding a verifiable credential with more than one subject. The Working Group may decide to create a new JWT claim for this purpose, and, if so, may register it in the JSON Web Token Claims Registry.

JWT Decoding

To decode a JWT to a standard credential or presentation, the following transformation MUST be performed:

  1. Create a JSON object.
  2. Add the content from the vc or vp claim to the new JSON object.
  3. Transform the remaining JWT specific headers and claims and add the results to the new credential or presentation JSON object.

To transform the JWT specific headers and claims, the following MUST be done:

  • If exp is present, the UNIX timestamp MUST be converted to an [XMLSCHEMA11-2] date-time, and MUST be used to set the value of the expirationDate property of credentialSubject of the new JSON object.
  • If iss is present, the value MUST be used to set the issuer property of the new credential JSON object or the holder property of the new presentation JSON object.
  • If nbf is present, the UNIX timestamp MUST be converted to an [XMLSCHEMA11-2] date-time, and MUST be used to set the value of the issuanceDate property of the new JSON object.
  • If sub is present, the value MUST be used to set the value of the id property of credentialSubject of the new credential JSON object.
  • If jti is present, the value MUST be used to set the value of the id property of the new JSON object.
{
"alg": "RS256",
"kid": "did:example:abfe13f712120431c276e12ecab#keys-1"
}
          

In the example above, the verifiable credential uses a proof based on JWS digital signatures, and the corresponding verification key can be obtained using the kid header parameter.

{
"sub": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"jti": "http://example.edu/credentials/3732",
"iss": "https://example.com/keys/foo.jwk",
"nbf": 1541493724,
"iat": 1541493724,
"exp": 1573029723,
"nonce": "660!6345FSer",
"vc": {
"@context": [
  "https://www.w3.org/2018/credentials/v1",
  "https://www.w3.org/2018/credentials/examples/v1"
],
"type": ["VerifiableCredential", "UniversityDegreeCredential"],
"credentialSubject": {
  "degree": {
    "type": "BachelorDegree",
    "name": "Bachelor of Science and Arts"
  }
}
}
}
          

In the example above, vc does not contain the id property because the JWT encoding uses the jti attribute to represent a unique identifier. The sub attribute encodes the information represented by the id property of credentialSubject. The nonce has been added to stop a replay attack.

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOmFiZmUxM2Y3MTIxMjA0
MzFjMjc2ZTEyZWNhYiNrZXlzLTEifQ.eyJzdWIiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxY
zI3NmUxMmVjMjEiLCJqdGkiOiJodHRwOi8vZXhhbXBsZS5lZHUvY3JlZGVudGlhbHMvMzczMiIsImlzc
yI6Imh0dHBzOi8vZXhhbXBsZS5jb20va2V5cy9mb28uandrIiwibmJmIjoxNTQxNDkzNzI0LCJpYXQiO
jE1NDE0OTM3MjQsImV4cCI6MTU3MzAyOTcyMywibm9uY2UiOiI2NjAhNjM0NUZTZXIiLCJ2YyI6eyJAY
29udGV4dCI6WyJodHRwczovL3d3dy53My5vcmcvMjAxOC9jcmVkZW50aWFscy92MSIsImh0dHBzOi8vd
3d3LnczLm9yZy8yMDE4L2NyZWRlbnRpYWxzL2V4YW1wbGVzL3YxIl0sInR5cGUiOlsiVmVyaWZpYWJsZ
UNyZWRlbnRpYWwiLCJVbml2ZXJzaXR5RGVncmVlQ3JlZGVudGlhbCJdLCJjcmVkZW50aWFsU3ViamVjd
CI6eyJkZWdyZWUiOnsidHlwZSI6IkJhY2hlbG9yRGVncmVlIiwibmFtZSI6IjxzcGFuIGxhbmc9J2ZyL
UNBJz5CYWNjYWxhdXLDqWF0IGVuIG11c2lxdWVzIG51bcOpcmlxdWVzPC9zcGFuPiJ9fX19.KLJo5GAy
BND3LDTn9H7FQokEsUEi8jKwXhGvoN3JtRa51xrNDgXDb0cq1UTYB-rK4Ft9YVmR1NI_ZOF8oGc_7wAp
8PHbF2HaWodQIoOBxxT-4WNqAxft7ET6lkH-4S6Ux3rSGAmczMohEEf8eCeN-jC8WekdPl6zKZQj0YPB
1rx6X0-xlFBs7cl6Wt8rfBP_tZ9YgVWrQmUWypSioc0MUyiphmyEbLZagTyPlUyflGlEdqrZAv6eSe6R
txJy6M1-lD7a5HTzanYTWBPAUHDZGyGKXdJw-W_x0IWChBzI8t3kpG253fg6V3tPgHeKXE94fz_QpYfg
--7kLsyBAfQGbg
          
{
"alg": "RS256",
"kid": "did:example:ebfeb1f712ebc6f1c276e12ec21#keys-1"
}
          

In the example above, the verifiable presentation uses a proof based on JWS digital signatures, and the corresponding verification key can be obtained using the kid header parameter.

{
"iss": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"jti": "urn:uuid:3978344f-8596-4c3a-a978-8fcaba3903c5",
"aud": "did:example:4a57546973436f6f6c4a4a57573",
"nbf": 1541493724,
"iat": 1541493724,
"exp": 1573029723,
"nonce": "343s$FSFDa-",
"vp": {
"@context": [
  "https://www.w3.org/2018/credentials/v1",
  "https://www.w3.org/2018/credentials/examples/v1"
],
"type": ["VerifiablePresentation"],
// base64url-encoded JWT as string
"verifiableCredential": ["..."]
}
}
          

In the example above, vp does not contain the id property because the JWT encoding uses the jti attribute to represent a unique identifier. verifiableCredential contains a string array of verifiable credentials using JWT compact serialization. The nonce has been added to stop a replay attack.


eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImRpZDpleGFtcGxlOjB4YWJjI2tleTEifQ.e
yJpc3MiOiJkaWQ6ZXhhbXBsZTplYmZlYjFmNzEyZWJjNmYxYzI3NmUxMmVjMjEiLCJqdGkiOiJ1cm46d
XVpZDozOTc4MzQ0Zi04NTk2LTRjM2EtYTk3OC04ZmNhYmEzOTAzYzUiLCJhdWQiOiJkaWQ6ZXhhbXBsZ
To0YTU3NTQ2OTczNDM2ZjZmNmM0YTRhNTc1NzMiLCJuYmYiOjE1NDE0OTM3MjQsImlhdCI6MTU0MTQ5M
zcyNCwiZXhwIjoxNTczMDI5NzIzLCJub25jZSI6IjM0M3MkRlNGRGEtIiwidnAiOnsiQGNvbnRleHQiO
lsiaHR0cHM6Ly93d3cudzMub3JnLzIwMTgvY3JlZGVudGlhbHMvdjEiLCJodHRwczovL3d3dy53My5vc
mcvMjAxOC9jcmVkZW50aWFscy9leGFtcGxlcy92MSJdLCJ0eXBlIjpbIlZlcmlmaWFibGVQcmVzZW50Y
XRpb24iLCJDcmVkZW50aWFsTWFuYWdlclByZXNlbnRhdGlvbiJdLCJ2ZXJpZmlhYmxlQ3JlZGVudGlhb
CI6WyJleUpoYkdjaU9pSlNVekkxTmlJc0luUjVjQ0k2SWtwWFZDSXNJbXRwWkNJNkltUnBaRHBsZUdGd
GNHeGxPbUZpWm1VeE0yWTNNVEl4TWpBME16RmpNamMyWlRFeVpXTmhZaU5yWlhsekxURWlmUS5leUp6Z
FdJaU9pSmthV1E2WlhoaGJYQnNaVHBsWW1abFlqRm1OekV5WldKak5tWXhZekkzTm1VeE1tVmpNakVpT
ENKcWRHa2lPaUpvZEhSd09pOHZaWGhoYlhCc1pTNWxaSFV2WTNKbFpHVnVkR2xoYkhNdk16Y3pNaUlzS
W1semN5STZJbWgwZEhCek9pOHZaWGhoYlhCc1pTNWpiMjB2YTJWNWN5OW1iMjh1YW5kcklpd2libUptS
WpveE5UUXhORGt6TnpJMExDSnBZWFFpT2pFMU5ERTBPVE0zTWpRc0ltVjRjQ0k2TVRVM016QXlPVGN5T
Xl3aWJtOXVZMlVpT2lJMk5qQWhOak0wTlVaVFpYSWlMQ0oyWXlJNmV5SkFZMjl1ZEdWNGRDSTZXeUpvZ
EhSd2N6b3ZMM2QzZHk1M015NXZjbWN2TWpBeE9DOWpjbVZrWlc1MGFXRnNjeTkyTVNJc0ltaDBkSEJ6T
2k4dmQzZDNMbmN6TG05eVp5OHlNREU0TDJOeVpXUmxiblJwWVd4ekwyVjRZVzF3YkdWekwzWXhJbDBzS
W5SNWNHVWlPbHNpVm1WeWFXWnBZV0pzWlVOeVpXUmxiblJwWVd3aUxDSlZibWwyWlhKemFYUjVSR1ZuY
21WbFEzSmxaR1Z1ZEdsaGJDSmRMQ0pqY21Wa1pXNTBhV0ZzVTNWaWFtVmpkQ0k2ZXlKa1pXZHlaV1VpT
25zaWRIbHdaU0k2SWtKaFkyaGxiRzl5UkdWbmNtVmxJaXdpYm1GdFpTSTZJanh6Y0dGdUlHeGhibWM5S
jJaeUxVTkJKejVDWVdOallXeGhkWExEcVdGMElHVnVJRzExYzJseGRXVnpJRzUxYmNPcGNtbHhkV1Z6U
EM5emNHRnVQaUo5ZlgxOS5LTEpvNUdBeUJORDNMRFRuOUg3RlFva0VzVUVpOGpLd1hoR3ZvTjNKdFJhN
TF4ck5EZ1hEYjBjcTFVVFlCLXJLNEZ0OVlWbVIxTklfWk9GOG9HY183d0FwOFBIYkYySGFXb2RRSW9PQ
nh4VC00V05xQXhmdDdFVDZsa0gtNFM2VXgzclNHQW1jek1vaEVFZjhlQ2VOLWpDOFdla2RQbDZ6S1pRa
jBZUEIxcng2WDAteGxGQnM3Y2w2V3Q4cmZCUF90WjlZZ1ZXclFtVVd5cFNpb2MwTVV5aXBobXlFYkxaY
WdUeVBsVXlmbEdsRWRxclpBdjZlU2U2UnR4Snk2TTEtbEQ3YTVIVHphbllUV0JQQVVIRFpHeUdLWGRKd
y1XX3gwSVdDaEJ6STh0M2twRzI1M2ZnNlYzdFBnSGVLWEU5NGZ6X1FwWWZnLS03a0xzeUJBZlFHYmciX
X19.ft_Eq4IniBrr7gtzRfrYj8Vy1aPXuFZU-6_ai0wvaKcsrzI4JkQEKTvbJwdvIeuGuTqy7ipO-EYi
7V4TvonPuTRdpB7ZHOlYlbZ4wA9WJ6mSVSqDACvYRiFvrOFmie8rgm6GacWatgO4m4NqiFKFko3r58Lu
eFfGw47NK9RcfOkVQeHCq4btaDqksDKeoTrNysF4YS89INa-prWomrLRAhnwLOo1Etp3E4ESAxg73CR2
kA5AoMbf5KtFueWnMcSbQkMRdWcGC1VssC0tB0JffVjq7ZV6OTyV4kl1-UVgiPLXUTpupFfLRhf9QpqM
BjYgP62KvhIvW8BbkGUelYMetA
          

Version 1.1

Production

This section describes how to produce a VC-JWT encoded VerifiableCredential from an object of media type application/credential+ld+json.

There are currently 2 competing solutions to this problem described below. It is a goal of the v2 work to resolve them and reduce production rules to a single, simple, set of instructions that any implementer can easily meet if they possess a software library supporting [[RFC7515]] or [[RFC7519]].

In addition to...

There are several members (claims) of the application/credential+ld+json which will need to be translated to their JOSE form, and included next to the vc or vp member in the JWT Claims Set. We refer to the JWT Claims Set as payload in this section.

If a member is not present in the application/credential+ld+json it MUST NOT be present in the VerifiableCredential as either a claim in the payload or a claim in the vc attribute of the payload.

We start with an empty header, and payload objects, and we add members to the header and the payload based on the content in the application/credential+ld+json.

issuer -> iss

This member MUST be present in the payload.vc.issuer attribute as either a string or an object with and id.

This member MUST be present payload.iss.

In the case that payload.vc.issuer is an object, payload.iss MUST be payload.vc.issuer.id.

In the case that payload.vc.issuer is a string, payload.iss must be payload.vc.issuer

issuanceDate -> nbf

This member MUST be present in the payload.vc.issuanceDate attribute as an XMLDateTime String.

This member MUST be present payload.nbf as a unix timestamp.

In the case that the issuanceDate includes leap seconds, it is not possible to detect them when the date time is represented in nbf

This section needs to be defined.

issuance

The header and payload converted into a JWT, in accorance with the RFC: RFC7519 Section 7.1

Instead of...

The following steps are one way to obtain this representation:

  1. Complete the mapping for In Addition To....
  2. Remove any properties from the application/credential+ld+json that were mapped.
  3. Set the resulting object to be the vc member of the claim set.

The object value for the vc property, when Instead of... production rules have been applied, is not of media type application/credential+ld+json.

Privacy Considerations

Security Considerations

IANA Considerations

The application/credential-claims-set-1.1+json Media Type

This specification registers the application/credential-claims-set-1.1+json MIME Media Type specifically for identifying a JWT Claims Set conforming to the Verifiable Credentials 1.1 JWT format in the `cty` header.

Type name: application
Subtype name: application/credential-claims-set-1.1+json
Required parameters: None
Encoding considerations: Resources that use the "application/credential-claims-set-1.1+json" Media Type are required to conform to all of the requirements for the "application/json" Media Type and are therefore subject to the same encoding considerations specified in Section 11 of [[!RFC7159]].
Security considerations: As defined in this specification.
Contact: W3C Verifiable Credentials Working Group public-vc-wg@w3.org