A JSON Web Signature (JWS) packages content with a tamper-detecting signature or MAC in a standard JSON-based format. It helps independently developed services exchange protected data without managing separate content and signature files. JWS provides integrity and authenticity, not confidentiality: anyone who can read the JWS can read its payload. section 11.0 section 11.4 section 11.8
A compact JWS has three parts, serialized with dots:
- Header — JSON metadata identifying the signing algorithm, such as HS256, the JWA identifier for HMAC with SHA-256. section 11.4.1 section 11.1
- Payload — arbitrary bytes, such as JSON data. Unlike a JWT payload, it does not have to be a JSON object. section 11.4.1 section 11.6
- Signature — a MAC or digital signature calculated from the protected header and payload. section 11.4.1 section 11.8
- Encoding — each part uses Base64 URL encoding, making the result suitable for HTTP headers and URL query parameters. section 11.4.1
Signed refund instructions
A warehouse service can produce one refunds.jws file containing refund data and its signature. A payments service parses the object, verifies it with the shared secret, rejects altered content, and extracts the original payload. With HMAC alone, the data and checksum were separate files; JWS combines them and carries the algorithm metadata with them. The payload remains readable, so encryption would require JWE instead. section 11.4.3 section 11.4.1
In Java, Nimbus can create a JWS from a JWSHeader, Payload, and JWSObject, then sign it with MACSigner. Verification parses the compact string and uses MACVerifier to check the signature. Keep secrets out of source code and properties files; configure verification explicitly rather than trusting the header’s algorithm choice. section 11.4.2 section 11.6
Figure 11.3 The logical structure of JWS: a JSON metadata header describing the type of signature used, a payload that can be any type of data format, and a signature used to verify that the header and payload weren’t altered. A JWS payload is always readable by anyone who can access the JWS object.
Use the structure diagram to distinguish readable payload data from the header metadata and signature used for validation. section 11.4.1
