The JWT Handbook

Special Thanks Introduction What is a JSON Web Token? What problem does it solve? A little bit of history Practical Applications Client-side/Stateless Sessions Security Considerations Signature Stripping Cross-Site Request Forgery (CSRF) Cross-Site Scripting (XSS) Are Client-Side Sessions Useful? Example Federated Identity Access and Refresh Tokens JWTs and OAuth2 JWTs and OpenID Connect OpenID Connect Flows and JWTs Example Setting up Auth0 Lock for Node.js Applications JSON Web Tokens in Detail The Header The Payload Registered Claims Public and Private Claims Unsecured JWTs Creating an Unsecured JWT Sample Code Parsing an Unsecured JWT Sample Code JSON Web Signatures Structure of a Signed JWT Algorithm Overview for Compact Serialization Practical Aspects of Signing Algorithms JWS Header Claims JWS JSON Serialization Flattened JWS JSON Serialization Signing and Validating Tokens HS256: HMAC + SHA-256 RS256: RSASSA + SHA256 ES256: ECDSA using P-256 and SHA-256 JSON Web Encryption (JWE) Structure of an Encrypted JWT Key Encryption Algorithms Key Management Modes Content Encryption Key (CEK) and JWE Encryption Key Content Encryption Algorithms The Header Algorithm Overview for Compact Serialization JWE JSON Serialization Flattened JWE JSON Serialization Encrypting and Decrypting Tokens Introduction: Managing Keys with node-jose AES-128 Key Wrap (Key) + AES-128 GCM (Content) RSAES-OAEP (Key) + AES-128 CBC + SHA-256 (Content) ECDH-ES P-256 (Key) + AES-128 GCM (Content) Nested JWT: ECDSA using P-256 and SHA-256 (Signature) + RSAES-OAEP (Encrypted Key) + AES-128 CBC + SHA-256 (Encrypted Content) Decryption JSON Web Keys (JWK) Structure of a JSON Web Key JSON Web Key Set JSON Web Algorithms General Algorithms Base64 Base64-URL Sample Code SHA Signing Algorithms HMAC HMAC + SHA256 (HS256) RSA Choosing e, d and n Basic Signing RS256: RSASSA PKCS1 v1.5 using SHA-256 Algorithm EMSA-PKCS1-v1_5 primitive OS2IP primitive RSASP1 primitive RSAVP1 primitive I2OSP primitive Sample code PS256: RSASSA-PSS using SHA-256 and MGF1 with SHA-256 Algorithm MGF1: the mask generation function EMSA-PSS-ENCODE primitive EMSA-PSS-VERIFY primitive Sample code Elliptic Curve Elliptic-Curve Arithmetic Point Addition Point Doubling Scalar Multiplication Elliptic-Curve Digital Signature Algorithm (ECDSA) Elliptic-Curve Domain Parameters Public and Private Keys The Discrete Logarithm Problem ES256: ECDSA using P-256 and SHA-256 Future Updates Annex A. Best Current Practices Pitfalls and Common Attacks ``alg: none'' Attack RS256 Public-Key as HS256 Secret Attack Weak HMAC Keys Wrong Stacked Encryption + Signature Verification Assumptions Invalid Elliptic-Curve Attacks Substitution Attacks Different Recipient Same Recipient/Cross JWT Mitigations and Best Practices Always Perform Algorithm Verification Use Appropriate Algorithms Always Perform All Validations Always Validate Cryptographic Inputs Pick Strong Keys Validate All Possible Claims Use The typ Claim To Separate Types Of Tokens Use Different Validation Rules For Each Token Conclusion