The rise of mobile and the popularity of OAuth2 has led to JWT being a hot mess these past few years. Today we are going to introduce another specification set, JOSE, called Javascript Object Signing and Encryption, which has a lot to do with JWT.

JOSE Introduction

JOSE is a Javascript object signing and encryption protocol designed to provide a method for securely transmitting declarations (claims, such as authorization information) between communicating parties, purposely built on top of JSON and BASE64 for easy use in Web applications. The specification is still evolving, and we commonly use the following concepts defined by the RFC document:

jose

JWT can be represented by JWS or JWE, I’ll cover this aspect in more detail later.

JWS

JSON Web Signature, content protected using digital signature techniques or message authentication code techniques (MAC) based on JSON data structures can be referred to as JWS. The cryptographic algorithms and identifiers used in this specification are defined in a separate specification JWA. The rules are more see RFC7515, here we just go through the serialization to get a feel for it.

JWS Serialization

The serialization of JWS is divided into JWS Compact Serialization and JWS JSON Serialization.

JWS Compact Serialization

This serialization is represented as a URL-safe, compact string. The format is.

1
2
3

BASE64URL(UTF8(JWS Protected Header)) || '.' ||
      BASE64URL(JWS Payload) || '.' ||
      BASE64URL(JWS Signature)

For example.

1

eyJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFtcGxlLmNvbS9pc19yb290Ijp0cnVlfQ.DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8ISlSApmWQxfKTUJqPP3-Kg6NU1Q

JWT is usually this format.

JWS JSON Serialization

This serialization is represented as a JSON object and comes in two formats. The general format is.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

     {
      "payload":"<payload contents>",
      "signatures":[
       {"protected":"<integrity-protected header 1 contents>",
        "header":"<non-integrity-protected header 1 contents>",
        "signature":"<signature 1 contents>"},
       {"protected":"<integrity-protected header N contents>",
        "header":"<non-integrity-protected header N contents>",
        "signature":"<signature N contents>"}]
     }

The tiled format is

1
2
3
4
5
6

     {
      "payload":"<payload contents>",
      "protected":"<integrity-protected header contents>",
      "header":"<non-integrity-protected header contents>",
      "signature":"<signature contents>"
     }

As an example of a general format.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
      "payload":
       "eyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGF
        tcGxlLmNvbS9pc19yb290Ijp0cnVlfQ",
      "signatures":[
       {"protected":"eyJhbGciOiJSUzI1NiJ9",
        "header":
         {"kid":"2010-12-29"},
        "signature":
         "cC4hiUPoj9Eetdgtv3hF80EGrhuB__dzERat0XF9g2VtQgr9PJbu3XOiZj5RZ
          mh7AAuHIm4Bh-0Qc_lF5YKt_O8W2Fp5jujGbds9uJdbF9CUAr7t1dnZcAcQjb
          KBYNX4BAynRFdiuB--f_nZLgrnbyTyWzO75vRK5h6xBArLIARNPvkSjtQBMHl
          b1L07Qe7K0GarZRmB_eSN9383LcOLn6_dO--xi12jzDwusC-eOkHWEsqtFZES
          c6BfI7noOPqvhJ1phCnvWh6IeYI2w9QOYEUipUTI8np6LbgGY9Fs98rqVt5AX
          LIhWkWywlVmtVrBp0igcN_IoypGlUPQGe77Rw"},
       {"protected":"eyJhbGciOiJFUzI1NiJ9",
        "header":
         {"kid":"e9bc097a-ce51-4036-9562-d2ade882db0d"},
        "signature":
         "DtEhU3ljbEg8L38VWAfUAqOyKAM6-Xx-F4GawxaepmXFCgfTjDxw5djxLa8IS
          lSApmWQxfKTUJqPP3-Kg6NU1Q"}]
}

JWE

JWS only signs the claims to ensure that they are not tampered with, but the payload information is exposed. That is, JWS only guarantees the integrity of the data but not its non-disclosure. It is not suitable for passing sensitive data. JWE was created to solve this problem. The details can be seen in the following figure.

JWE

As you can see from the above JWE is very tedious to generate and may be resource and time consuming as a Token. It should be good to use as a secure data transfer path. As an example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

     eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.
     OKOawDo13gRp2ojaHV7LFpZcgV7T6DVZKTyKOMTYUmKoTCVJRgckCL9kiMT03JGe
     ipsEdY3mx_etLbbWSrFr05kLzcSr4qKAq7YN7e9jwQRb23nfa6c9d-StnImGyFDb
     Sv04uVuxIp5Zms1gNxKKK2Da14B8S4rzVRltdYwam_lDp5XnZAYpQdb76FdIKLaV
     mqgfwX7XWRxv2322i-vDxRfqNzo_tETKzpVLzfiwQyeyPGLBIO56YJ7eObdv0je8
     1860ppamavo35UgoRdbYaBcoh9QcfylQr66oc6vFWXRcZ_ZT2LawVCWTIy3brGPi
     6UklfCpIMfIjf7iGdXKHzg.
     48V1_ALb6US04U3b.
     5eym8TW_c8SuK0ltJ3rpYIzOeDQz7TALvtu6UG9oMo4vpzs9tX_EFShS8iB7j6ji
     SdiwkIr3ajwQzaBtQD_A.
     XFBoMYUZodetZdvTiFvSkQ

There are five parts in total, separated by four English periods.

Actually, JWE also has a corresponding JSON format with the same two serialization methods of JWS, see RFC7516.

Relationship of JWT to JWS and JWE

The following is a description of JWT from RFC7519.

JWT

Some conclusions can be drawn from the above.

  • JWT has specific claims which are composed of Payload in the form of JSON.

  • JWT can be structured as JWS or JWE.

  • JWT can only be serialized using Compact Serialization, not JSON Serialization.

In short, JWT is a JWS or JWE string that contains specific claims. Most of our common ones are JWS.

Also, we usually read J, W, T, and actually recommend to read jot (corner special), see RFC7519 for the definition and specification of JWT.

JWK

JWK is the most important point of knowledge in this article, which is important for us to learn about the Resource Server** later.

Scenario Description

I believe Signing Public and Private Keys is not new to anyone. The JWT itself has to be signed with a private key to prevent information tampering, and the public key is used to send to the downstream consumer to verify the reliability of the JWT. Usually, the public key is configured in a static file integration, which has the disadvantage that when the upstream public and private keys are changed, the downstream cannot dynamically adapt the public key. This is the problem that JWK has to solve, with its canonical design of cryptographic algorithms and identifiers, and its compact JSON data structure is very easy to transfer between upstream and downstream.

JWK format

JWK is a JSON object that represents the encryption key. The object contains a key name that must be unique, on top of which JWK can contain some custom fields. The following is a JWK representation of a P-256 EC (Elliptic Curve Discrete Cipher) key.

1
2
3
4
5
6

     {"kty":"EC",
      "crv":"P-256",
      "x":"f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y":"x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "kid":"Public key used in JWS spec Appendix A.3 example"
     }

As defined in RFC7517, a JWK JSON object may contain the following attributes.

JWK JSON

Depending on the algorithm JWK may also contain other properties.

JWK Set

A JWK Set represents a set of JWK with different kids, which is very easy to understand. It is also a JSON object, and the only key is keys. As an example.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

     {"keys":
       [
         {"kty":"EC",
          "crv":"P-256",
          "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
          "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
          "use":"enc",
          "kid":"1"},

         {"kty":"RSA",
          "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
     4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
     tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
     QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
     SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
     w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
          "e":"AQAB",
          "alg":"RS256",
          "kid":"2011-04-29"}
       ]
     }

The JWK Set URL in the > OAuth2 configuration is the endpoint to output the JWK Set.

JWA

The JWA specification specifies which algorithms can be used as cryptographic algorithms for JWS and JWE. It also specifies the alg properties in JWK corresponding to these algorithms, as well as the properties that specific algorithms include in JWK such as crv, x, y in the previous EC algorithm, which are not set in stone, they are adjusted based on the iteration of the algorithm. If you are interested in the details of JWA, see RFC7518.

You can generate JWK by yourself using some algorithms via the JWK generator to observe the differences between the different algorithms.

Summary

Today’s brief introduction to the JOSE specification is very helpful for you to learn about OAuth2 and OIDC related knowledge. It is not required to go deep but must understand the relevant knowledge.