JWT Handbook

Contents

1. Special Thanks 4
2. Introduction 5
   1. What is a JSON WebToken? 5
   2. What problem does it solve? 6
   3. A little bit of history 6
3. Practical Applications 8
   1. Client-side/Stateless Sessions 8
      1. Security Considerations 9
         1. Signature Stripping 9
         2. Cross-Site Request Forgery (CSRF) 10
         3. Cross-Site Scripting (XSS) 11
      2. Are Client-Side Sessions Useful? 13
      3. Example 13
   2. FederatedIdentity 16
      1. Access and Refresh Tokens 18
      2. JWTs and OAuth2 19
      3. JWTs and OpenID Connect 20
         1. OpenID Connect Flows and JWTs 20
      4. Example 20
         1. Setting up Auth0 Lock for Node.js Applications 21
4. JSON Web Tokens in Detail 23
   1. The Header 24
   2. The Payload 25
      1. Registered Claims 25
      2. Public and Private Claims 26
   3. Unsecured JWTs 27
   4. Creating an Unsecured JWT 27
      1. Sample Code 28
   5. Parsing an Unsecured JWT 28
      1. Sample Code 29
5. JSON Web Signatures 30
   1. Structure of a Signed JWT 30
      1. Algorithm Overview for Compact Serialization 32
      2. Practical Aspects of Signing Algorithms 33
      3. JWS Header Claims 36
      4. JWS JSON Serialization 36
         1. Flattened JWS JSON Serialization 38
   2. Signing and Validating Tokens 38
      1. HS256: HMAC 1. SHA-256 39
      2. RS256: RSASSA 1. SHA256 39
      3. ES256: ECDSA using P-256 and SHA-256 40
6. JSON Web Encryption (JWE) 41
   1. Structure of an Encrypted JWT 44
      1. Key Encryption Algorithms 45
         1. Key Management Modes 46
         2. Content Encryption Key (CEK) and JWE Encryption Key 47
      2. Content Encryption Algorithms 48
      3. The Header 48
      4. Algorithm Overview for Compact Serialization 49
      5. JWE JSON Serialization 50
         1. Flattened JWE JSON Serialization 52
   2. Encrypting and Decrypting Tokens 52
      1. Introduction: Managing Keys with node-jose 52
      2. AES-128 Key Wrap (Key) 1. AES-128 GCM (Content) 54
      3. RSAES-OAEP (Key) 1. AES-128 CBC 1. SHA-256 (Content) 54
      4. ECDH-ESP-256 (Key)1. AES-128 GCM (Content) 55
      5. Nested JWT: ECDSA using P-256 and SHA-256 (Signature) 1. RSAES-OAEP (Encrypted Key) 1. AES-128 CBC 1. SHA-256 (Encrypted Content) 55
      6. Decryption 56
7. JSON Web Keys (JWK) 58
   1. Structure of a JSON Web Key 59
      1. JSON Web Key Set 60
8. JSON Web Algorithms 61
   1. General Algorithms 61
      1. Base64 61
         1. Base64-URL 63
         2. Sample Code 63
      2. SHA 64
   2. Signing Algorithms 69
      1. HMAC 69
         1. HMAC 1. SHA256 (HS256) 71
      2. RSA 73
         1. Choosing e, d and n 75
         2. Basic Signing 76
         3. RS256: RSASSA PKCS1 v1.5 using SHA-256 76
            1. Algorithm 76
               1. EMSA-PKCS1-v1_5 primitive 78
               2. OS2IP primitive 79
               3. RSASP1 primitive 79
               4. RSAVP1 primitive 80
               5. I2OSP primitive 80
            2. Samplecode 81
         4. PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256 86
            1. Algorithm 86
               1. MGF1: the mask generation function 87
               2. EMSA-PSS-ENCODE primitive 88
               3. EMSA-PSS-VERIFY primitive 89
            2. Sample code 91
      3. Elliptic Curve 94
         1. Elliptic-Curve Arithmetic 96
            1. Point Addition 96
            2. Point Doubling 97
            3. Scalar Multiplication 97
         2. Elliptic-Curve Digital Signature Algorithm (ECDSA) 98
            1. Elliptic-Curve Domain Parameters 100
            2. Public and Private Keys 101
               1. The Discrete Logarithm Problem 101
            3. ES256: ECDSA using P-256 and SHA-256 101
   3. Future Updates 104