Demystifying JOSE, the JWT Family: JWS, JWE, JWA, and JWK Explained

If you've worked with modern authentication or secure data exchange, you've undoubtedly encountered JSON Web Tokens, or JWTs. However, if you dig deeper, you may encounter a series of confusing acronyms: JWS, JWE, JWK, JWA, and the umbrella term, JOSE. What do they all mean? How do they relate to each other?

It's easy to get lost, but these concepts are actually designed to work together in a logical system. Think of it like a secure shipping company. You have the package, the tamper-proof seal, the locked box, the keys, and the set of rules for how to handle everything. This article will unpack each of these components, trying to clarify their roles and how they come together to create the secure tokens we rely on.

What Is JOSE (JSON Object Signing and Encryption)?

Let's start with the big picture: JOSE.

JOSE isn't a single technology you can install or a specific format. Instead, it's a framework or a collection of IETF (Internet Engineering Task Force) standards. Its purpose is to provide a standardized way to securely transfer claims between parties.

Think of JOSE as the entire shipping and logistics company. It doesn't represent a single box or key, but rather the complete set of rules, tools, and specifications for shipping things securely. It defines how to create signed messages (JWS), encrypted messages (JWE), the keys to use (JWK), and the algorithms allowed (JWA).

The JOSE framework is composed of several key specifications, which we will explore next.

JWS (JSON Web Signature)

JWS is a standard for signing data. Its primary goals are to ensure integrity and authenticity:

• Integrity: Guarantees that the data has not been tampered with in transit.
• Authenticity: Verifies that the sender is who they claim to be.

A JWS object doesn't hide the data; it just adds a signature that the recipient can verify. It's like putting a letter in a clear envelope and sealing it with a unique, tamper-proof wax seal. Anyone can read the letter, but the seal proves it came from the right person and hasn't been opened.

A JWS object, or more simply a JWS, can be represented in a compact, URL-safe string composed of three parts, separated by dots (.):

This representation is called JWS Compact Serialization.

A JWS can also be represented as a JSON object in two different flavors: General JWS JSON Serialization and Flattened JWS JSON Serialization.

Here is an example of a JWS object represented through JWS Compact Serialization:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

Decoding each of these parts, you’ll get the following:

• Header: Metadata about the signature, such as the signing algorithm used:

{
  "alg": "HS256",
  "typ": "JWT"
}

• Payload: The actual data being secured (the claims):

{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022
}

• Signature: Created by signing the encoded header and payload with a secret key.

JWE (JSON Web Encryption)

JWE is a standard for encrypting data. Its primary goal is confidentiality.

Unlike JWS, which leaves the data readable, JWE makes it unreadable to anyone without the correct keys. This is like putting your letter inside a locked metal box before shipping it. Only the person with the key can open it and see the contents.

A JWE object, or more simply a JWE, can also be represented in a compact string, but it has five parts separated by dots (.):

This is the JWE Compact Serialization representation.

As for a JWS, a JWE can also be represented as a JSON object in two different flavors: General JWE JSON Serialization and Flattened JWE JSON Serialization.

Here is an example of the JWE Compact Serialization representation:

eyJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2v6GZfDqztYe70eG6o0f6ZlH5_yl1TjSGhbyT2KVdD2iM0ik2aO_hJAFy8uMwk2nN25OJaSqa1L58U9b2JTJmYnE9LzE6W1-nZz1tQ1tY4C8z4p2v6G.AxY8DCtDaGlsbGljb3RoZQ.KDlT9LgK3-tV3hVucpYh_g.GawgguFyGrWKav7AX4VKUg

Breaking it down, you will find the following parts:

• JOSE Header: Contains metadata about the encryption algorithms.
• JWE Encrypted Key: The key used to encrypt the content, which itself is encrypted with the recipient's public key.
• JWE Initialization Vector: A random value to ensure the encryption is unique. If an algorithm does not utilize an Initialization Vector, this value will be an empty octet sequence..
• JWE Ciphertext: The encrypted payload.
• JWE Authentication Tag: A value used to verify the integrity of the encrypted data. In case an algorithm does not use an Authentication Tag, this value will be an empty octet sequence.

JWA and JWK

Now, both JWS and JWE use algorithms and keys to sign and encrypt data. How do they know which algorithms and which keys to use? That's where JWA and JWK come in. They represent the tools for sealing, locking, and unlocking in our metaphorical shipping company.

JWA (JSON Web Algorithms)

JWA is simply a specification that defines the cryptographic algorithms that can be used for signing and encryption within the JOSE framework. It doesn't contain any code; it's a registry of identifiers.

For example, when the JWS header contains "alg": "HS256", it's referring to the HMAC algorithm using SHA-256 algorithm. Other examples include "RS256" for RSA signatures or "A256GCM" for AES-GCM encryption.

JWK (JSON Web Key)

JWK is a standard for representing cryptographic keys in a JSON format. Instead of passing around key files in different formats (like PEM or DER), you can represent them as a JSON object. This is especially useful for web-based applications where JSON is the native language.

A JWK contains metadata about the key, such as its type, usage (signing or encryption), and the key values themselves.

Here is an example of an RSA Public JWK:

{
  "kty": "RSA",
  "use": "sig",
  "kid": "my-rsa-key-1",
  "n": "u4V_...",
  "e": "AQAB"
}

• kty (Key Type): Identifies the crypto family (e.g., "RSA", "EC").
• use (Public Key Use): Defines the intended use (e.g., "sig" for signature, "enc" for encryption).
• kid (Key ID): A unique identifier for the key, useful when an application has multiple keys.
• n and e: The modulus and exponent values for the RSA public key.

JWKS (JWK SET)

You may have heard about JWKS. This is a standard specification to represent a set of JWK objects. The following is an example of JWKS object containing two JWK objects:

{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "n": "sySYvu...",
      "e": "AQAB",
      "kid": "MDc...",
    },
    {
      "kty": "RSA",
      "use": "sig",
      "n": "rxFxz...",
      "e": "AQAB",
      "kid": "_dqx...",
      "x5t": "IwL...",
      "x5c": [
        "MIIDAz..."
      ],
      "alg": "RS256"
    }
  ]
}

The JWKS object must have a keys member, which is an array of JWKs.

Auth0 provides a JWKS endpoint for each tenant at https://<YOUR-DOMAIN>/.well-known/jwks.json. This endpoint returns the JWK objects associated with that specific tenant. Applications use this endpoint to dynamically fetch the public keys needed to verify JWTs issued by your Auth0 tenant.

What About JWT?

Finally, we arrive at the most well-known acronym: JWT (JSON Web Token).

A JWT is not a new technology separate from the others. A JWT is a specific type of payload or a set of claims that is transported using JWS or JWE. It's the "what" that goes inside the secure container.

Referring once again to the metaphor of the shipping company, if JWS is the sealed envelope, the JWT is the letter inside it. The JWT standard defines a compact, self-contained way for representing information between two parties. It specifies a set of standard claim names like iss (issuer), exp (expiration time), sub (subject), and aud (audience).

Here is an example of a JWT Payload (Claims Set):

{
  "iss": "https://my-auth-server.com",
  "sub": "user-123",
  "aud": "my-api",
  "exp": 1664532000,
  "name": "Jane Doe",
  "isAdmin": true
}

Why Is a JWT Often Called a JWS or JWE?

This is the most common point of confusion. People often use "JWT" and "JWS" interchangeably. Is that correct?

Mostly, yes. A JWT is just the set of claims. To be useful, it must be securely transmitted. The way you make it secure is by signing it (creating a JWS) or encrypting it (creating a JWE).

• When you sign a JWT payload, the resulting token is technically a JWS. This is the most common form of JWT.
• When you encrypt a JWT payload, the resulting token is technically a JWE.
• It's also possible to have a nested JWT, where a JWT payload is signed (JWS) and then the entire JWS is encrypted (JWE).

So, when someone says "here is my JWT," they are almost always handing you a JWS whose payload is a set of JWT claims. The term "JWT" has become a colloquial shortcut for "a JWS containing JWT claims."

You learned earlier that JWS and JWE objects can be represented as JSON objects. However, these representations can’t be used for JWTs. As the specifications say, a JWT is always represented through JWS or JWE Compact Serialization.

Recap

Although the JOSE acronyms may seem intimidating, the underlying concepts are actually distinct and logical once understood correctly. So, to summarize:

• JOSE is the overarching framework.
• JWS and JWE are the secure containers—one is signed, the other is encrypted.
• JWA and JWK are the tools—the algorithms and keys used to secure the containers.
• JWT is the content—the standardized set of claims you put inside the container.

For your convenience, here is a summary table that recaps the differences between the items of the JOSE framework, including the references to the secure shipping company’s metaphor: