add changelog

changelog.d/33.feature.md

@@ -0,0 +1,34 @@
+* Support multiple algorithms and keys
+
+  Existing code made key rollovers or algorithm changes hard and
+  basically required a breaking change: Once any of `JWT_ALGORITHM`,
+  `JWT_SECERT_KEY`, or `JWT_PRIVATE_KEY`/`JWT_PUBLIC_KEY` were
+  changed, existing tokens were rendered invalid.
+
+  We now support `JWT_ALGORITHM`, `JWT_SECERT_KEY`, and
+  `JWT_PUBLIC_KEY` optionally being a list, where all members are
+  accepted as valid.
+
+  When `JWT_SECERT_KEY` is a list, the first member is used for
+  signing and all others are accepted for verification.
+
+* Support multiple keys with key ids
+
+  We also support identifing keys by key id (`kid` header): When a JWT
+  carries a key id, we can identify immediately if it is known and
+  only need to make at most one verification attempt.
+
+  To configure keys with ids, `JWT_SECRET_KEY`, `JWT_PRIVATE_KEY` and
+  `JWT_PUBLIC_KEY` can now also be a dict in the form
+
+  ```
+  { "kid1": key1, "kid2": key2, ... }
+  ```
+
+  When a JWT does not carry a key id (`kid` header), the default is to
+  fall back to trying all keys if keys are named (defined as a dict).
+  Setting `JWT_INSIST_ON_KID: True` avoids this fallback and requires
+  any JWT to be validated to carry a key id _if_ key IDs are used
+
+  *NOTE: For python < 3.7, use a `collections.OrderedDict` object
+  instead of a dict