The JWT Handbook Sebastián E. Peyrott, Auth0 Inc. Version 0.14.1, 2016-2018 Contents Special Thanks 4 1 Introduction 1.1 What is a JSON Web Token? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.2 What problem does it solve? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1.3 A little bit of history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5 6 6 2 Practical Applications 2.1 Client-side/Stateless Sessions . . . . . . . . . . . . . . . . . . . . 2.1.1 Security Considerations . . . . . . . . . . . . . . . . . . . 2.1.1.1 Signature Stripping . . . . . . . . . . . . . . . . 2.1.1.2 Cross-Site Request Forgery (CSRF) . . . . . . . 2.1.1.3 Cross-Site Scripting (XSS) . . . . . . . . . . . . 2.1.2 Are Client-Side Sessions Useful? . . . . . . . . . . . . . . 2.1.3 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2 Federated Identity . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.1 Access and Refresh Tokens . . . . . . . . . . . . . . . . . 2.2.2 JWTs and OAuth2 . . . . . . . . . . . . . . . . . . . . . . 2.2.3 JWTs and OpenID Connect . . . . . . . . . . . . . . . . . 2.2.3.1 OpenID Connect Flows and JWTs . . . . . . . . 2.2.4 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2.2.4.1 Setting up Auth0 Lock for Node.js Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 8 9 9 10 11 13 13 16 18 19 20 20 20 21 3 JSON Web Tokens in Detail 3.1 The Header . . . . . . . . . . . . 3.2 The Payload . . . . . . . . . . . 3.2.1 Registered Claims . . . . 3.2.2 Public and Private Claims 3.3 Unsecured JWTs . . . . . . . . . 3.4 Creating an Unsecured JWT . . 3.4.1 Sample Code . . . . . . . 3.5 Parsing an Unsecured JWT . . . 3.5.1 Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 24 25 25 26 27 27 28 28 29 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 JSON Web Signatures 4.1 Structure of a Signed JWT . . . . . . . . . . . . . . . 4.1.1 Algorithm Overview for Compact Serialization 4.1.2 Practical Aspects of Signing Algorithms . . . . 4.1.3 JWS Header Claims . . . . . . . . . . . . . . . 4.1.4 JWS JSON Serialization . . . . . . . . . . . . . 4.1.4.1 Flattened JWS JSON Serialization . . 4.2 Signing and Validating Tokens . . . . . . . . . . . . . 4.2.1 HS256: HMAC + SHA-256 . . . . . . . . . . . 4.2.2 RS256: RSASSA + SHA256 . . . . . . . . . . . 4.2.3 ES256: ECDSA using P-256 and SHA-256 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 30 32 33 36 36 38 38 39 39 40 5 JSON Web Encryption (JWE) 41 5.1 Structure of an Encrypted JWT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 5.1.1 Key Encryption Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 5.1.1.1 Key Management Modes . . . . . . . . . . . . . . . . . . . . . . . . 46 5.1.1.2 Content Encryption Key (CEK) and JWE Encryption Key . . . . . 47 5.1.2 Content Encryption Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.1.3 The Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 5.1.4 Algorithm Overview for Compact Serialization . . . . . . . . . . . . . . . . . 49 5.1.5 JWE JSON Serialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 5.1.5.1 Flattened JWE JSON Serialization . . . . . . . . . . . . . . . . . . 52 5.2 Encrypting and Decrypting Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 5.2.1 Intr