Browse Source

Repropose JWT specification for Stein

This spec was something we agreed upon as a team during the Queens
release. This commit reproposes it for Stein.

Major differences between this specification the original proposal
from Queens include:

  - the algorithm targeted for the implementation
  - the library being used to sign and validate JWTs
  - the payload data and claim information
  - asymmetric key rotation details

bp json-web-tokens

Change-Id: I598faca40a6d81dd58155165d4a323fb437f7a6c
changes/03/541903/12
Lance Bragstad 1 year ago
parent
commit
c87a0230b3
2 changed files with 406 additions and 197 deletions
  1. 0
    197
      specs/keystone/backlog/json-web-tokens.rst
  2. 406
    0
      specs/keystone/stein/json-web-tokens.rst

+ 0
- 197
specs/keystone/backlog/json-web-tokens.rst View File

@@ -1,197 +0,0 @@
1
-..
2
- This work is licensed under a Creative Commons Attribution 3.0 Unported
3
- License.
4
-
5
- http://creativecommons.org/licenses/by/3.0/legalcode
6
-
7
-======================================================
8
-Add JSON Web Tokens as a Non-persistent Token Provider
9
-======================================================
10
-
11
-`bp json-web-tokens <https://blueprints.launchpad.net/keystone/+spec/json-web-tokens>`_
12
-
13
-
14
-JSON Web Token is a type of non-persistent bearer token similar to the fernet
15
-tokens we use today. JWT is an `open standard`_ with `actively maintained
16
-libraries`_.
17
-
18
-.. _`open standard`: https://tools.ietf.org/html/rfc7519
19
-.. _`actively maintained libraries`: https://jwt.io/#libraries
20
-
21
-Problem Description
22
-===================
23
-
24
-We currently support two types of tokens. The UUID persistent token format is
25
-the original format. The fernet token format is a non-persistent format based
26
-on a spec by Heroku and was made the default token format for keystone.
27
-
28
-The UUID token format suffers a number of performance and maintainability
29
-problems. It is already deprecated and we intend to eventually remove it, in
30
-favor of non-persistent token formats.
31
-
32
-However, the fernet format has its own problems that make it non-ideal. The
33
-`fernet spec`_ is largely abandoned, making it hard to `get changes into it`_
34
-and thereby into the `cryptography` implementation of it. Moreover, the fernet
35
-spec is not recognized by any standards body and therefore not as closely
36
-audited as an IETF standard, making it more susceptable to zero-day
37
-vulnerabilities. Addressing these vulnerabilities falls solely on the
38
-OpenStack, specifically the keystone, community.
39
-
40
-It would be nice to offer a new type of token that is backed by a widely used
41
-standard before we totally remove support for UUID tokens. This also increases
42
-interoperability between the OpenStack ecosystem and other communities that
43
-support JWT.
44
-
45
-.. _`fernet spec`: https://github.com/fernet/spec/blob/master/Spec.md
46
-.. _`get changes into it`: https://github.com/fernet/spec/pull/13
47
-
48
-
49
-Proposed Change
50
-===============
51
-
52
-Create a new non-persistent keystone token backend based on the `JSON Web Token
53
-standard`_. These will behave in much the same way as our current fernet tokens
54
-do.
55
-
56
-The token will be a nested JWT which is a signed JWT (`JWS`_) as the payload of
57
-an encrypted JWT (`JWE`_), meaning the token data is signed and then encrypted.
58
-This is the order specifically recommended in the JWT spec due to its use of
59
-Authenticated Encryption which eliminates the need to sign after encryption.
60
-
61
-Similar to the fernet, JWTs will require a key repository be set up to use for
62
-signing tokens. A new ``keystone-manage`` command will be added to handle
63
-secret generation and rotation which will likely re-use much of the utilities
64
-in the fernet_setup and fernet_rotate commands. JWE can use symmetric keys for
65
-encryption and signing the way fernet does but it is more typical to use an
66
-asymmetric key pair to encrypt the Content Encryption Key (which is then used
67
-as a symmetric key to encrypt the payload, but this is an implementation detail
68
-that will be handled by the chosen library), so the JWT key repository should
69
-have asymmetric key pairs which we can use for encryption and signing. The
70
-specific algorithms used will depend on the support for them in the chosen
71
-library.
72
-
73
-The payload of the JWS will use the following `registered claims`_:
74
-
75
-* the "sub" claim for the subject, i.e. the user. This claim will include the
76
-  same data that fernet tokens do, such as user information and scope.
77
-* the "exp" claim for expiry
78
-* the "iat" claim for "issued at", analogous to the timestamp field in the
79
-  fernet token.
80
-
81
-The `PyJWT library`_ is already present in the requirements repository and so
82
-would be a convenient choice to use for this implementation, but it
83
-unfortunately `does not yet support JWE`_. We will need to evaluate the
84
-`JWCrypto library`_ which does support encryption or consider contributing the
85
-feature to PyJWT.
86
-
87
-Users will request and present tokens in exactly the same way they currently do
88
-with either UUID or Fernet tokens. There is no need to add or change any APIs.
89
-
90
-.. _`JSON Web Token standard`: https://tools.ietf.org/html/rfc7519
91
-.. _`JWS`: https://tools.ietf.org/html/rfc7515
92
-.. _`JWE`: https://tools.ietf.org/html/rfc7516
93
-.. _`registered claims`: https://tools.ietf.org/html/rfc7519#section-4.1
94
-.. _`Python libraries`: https://jwt.io/#libraries
95
-.. _`PyJWT library`: https://pyjwt.readthedocs.io/en/latest/
96
-.. _`does not yet support JWE`: https://github.com/jpadilla/pyjwt/issues/143
97
-.. _`JWCrypto library`: http://jwcrypto.readthedocs.org/
98
-
99
-Alternatives
100
-------------
101
-
102
-Not applicable, this is an additive change. The alternative is not to add it or
103
-to find a different token format.
104
-
105
-Security Impact
106
----------------
107
-
108
-Since JWT is a widely used web standard, this will have a net positive impact
109
-on security. The implementation will use JWE even though it is an optional
110
-feature of the JWT spec. While this will not protect against an attacker using
111
-a valid token to query keystone for information about the token, it protects
112
-against an attacker gaining information from an expired or revoked token. This
113
-will ensure that the data within the token is at least as secure as it is in
114
-fernet tokens. These will still be bearer tokens and so interception of one
115
-must still be guarded against.
116
-
117
-Notifications Impact
118
---------------------
119
-
120
-Notifications for JWTs will behave in the same way that they do for fernet
121
-tokens, including for revocation events.
122
-
123
-Other End User Impact
124
----------------------
125
-
126
-This will have no end user impact. They will request and use JWTs in exactly
127
-the same way that they currently use fernet or UUID tokens.
128
-
129
-Performance Impact
130
-------------------
131
-
132
-Performance will be on-par with fernet tokens.
133
-
134
-Other Deployer Impact
135
----------------------
136
-
137
-This is an optional, opt-in feature that will not be the default, so deployers
138
-will not be affected unless they choose to deploy this feature. In that case,
139
-deployers will need to set up a key repository before using JWTs. The key
140
-repository will contain asymmetric key pairs rather than just secret keys. The
141
-deployer will need to take care to sync and rotate keys the way they do with
142
-fernet tokens.
143
-
144
-Developer Impact
145
-----------------
146
-
147
-The new token type will reuse much of the work already done for fernet tokens
148
-and will follow similar code paths, so this will be relatively easy to
149
-maintain.
150
-
151
-Implementation
152
-==============
153
-
154
-Assignee(s)
155
------------
156
-
157
-TBD: Please update this section when this spec is reproposed to a release.
158
-
159
-Primary assignee:
160
-  <launchpad-id or None>
161
-
162
-Other contributors:
163
-  <launchpad-id or None>
164
-
165
-Work Items
166
-----------
167
-
168
-* Decide on an implementation library
169
-* Refactor the fernet utilities modules to be generic enough to work with JWT
170
-  or inheritable
171
-* Add a ``keystone-manage`` command to set up and rotate JWT signing/encryption
172
-  keys
173
-* Generalize the ``TokenFormatter`` class to support JWT
174
-* Refactor the fernet token provider module to be inheritable or generic
175
-* Add a keystone doctor command to validate the setup in the same way that
176
-  fernet is validated
177
-
178
-
179
-Dependencies
180
-============
181
-
182
-* A JWT library to be decided on
183
-
184
-
185
-Documentation Impact
186
-====================
187
-
188
-The new ``[token]/provider`` configuration option will need to be documented,
189
-as will the new ``keystone-manage`` commands.
190
-
191
-
192
-References
193
-==========
194
-
195
-* `JSON Web Token RFC <https://tools.ietf.org/html/rfc7519>`_
196
-* `JSON Web Token light introduction <https://jwt.io/introduction/>`_
197
-* `History of cryptography's adoption of fernet <https://github.com/pyca/cryptography/issues/2900>`_

+ 406
- 0
specs/keystone/stein/json-web-tokens.rst View File

@@ -0,0 +1,406 @@
1
+..
2
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
3
+ License.
4
+
5
+ http://creativecommons.org/licenses/by/3.0/legalcode
6
+
7
+======================================================
8
+Add JSON Web Tokens as a Non-persistent Token Provider
9
+======================================================
10
+
11
+`bp json-web-tokens <https://blueprints.launchpad.net/keystone/+spec/json-web-tokens>`_
12
+
13
+
14
+JSON Web Token is a type of non-persistent bearer token similar to the fernet
15
+tokens we use today. JWT is an `open standard`_ with `actively maintained
16
+libraries`_.
17
+
18
+.. _`open standard`: https://tools.ietf.org/html/rfc7519
19
+.. _`actively maintained libraries`: https://jwt.io/#libraries
20
+
21
+Problem Description
22
+===================
23
+
24
+We currently support one token format called fernet. The fernet token format is
25
+a non-persistent format based on a spec by Heroku and was made the default
26
+token format for keystone.
27
+
28
+However, the fernet format has its own problems that make it non-ideal. The
29
+`fernet spec`_ is largely abandoned, making it hard to `get changes into it`_
30
+and thereby into the `cryptography`_ implementation of it. Moreover, the fernet
31
+spec is not recognized by any standards body and therefore not as closely
32
+audited as an IETF standard, making it more susceptible to zero-day
33
+vulnerabilities. Addressing these vulnerabilities falls solely on the
34
+OpenStack, specifically the keystone, community.
35
+
36
+It would be nice to offer a new type of token that is backed by a widely used
37
+standard. This also increases the chances of interoperability between the
38
+OpenStack ecosystem and other communities that support JWT.
39
+
40
+.. _`get changes into it`: https://github.com/fernet/spec/pull/13
41
+
42
+Use Cases
43
+---------
44
+
45
+* As a operator, I want to use a non-persistent token provider that isn't
46
+  coupled to a symmetric encryption or signing implementation. An
47
+  implementation built on asymmetric signing or encryption allows me to
48
+  distribute public keys from one node to another instead of syncing a
49
+  repository of symmetric keys. This makes it easier to deploy keystone nodes
50
+  with read-only capabilities strictly used for token validation. The
51
+  specific usecase for this allows me to deploy read-only regions keeping token
52
+  validation within the region, while having tokens issued from a central
53
+  identity management system in a separate region.
54
+
55
+* As an operator, I want to be have a token provider to fall back on in the
56
+  event there is a security vulnerability in the `fernet spec`_ or the
57
+  `cryptography`_ implementation consumed by keystone.
58
+
59
+* As a user, I want to be able to authenticate for a token that I can use with
60
+  other pieces of software outside of the OpenStack ecosystem that prove my
61
+  identity.
62
+
63
+.. _`fernet spec`: https://github.com/fernet/spec/blob/master/Spec.md
64
+.. _`cryptography`: https://github.com/pyca/cryptography
65
+
66
+Proposed Change
67
+===============
68
+
69
+Create a new non-persistent keystone token backend based on the `JSON Web Token
70
+standard`_. These will behave in much the same way as our current fernet tokens
71
+do.
72
+
73
+The token will be a signed JWT (`JWS`_) containing the authentication payload.
74
+Note that signed tokens are web safe and integrity verified, but token payload
75
+is not opaque to its holder. It is possible to decode a token and inspect the
76
+payload with `JWS`_ tokens. Using nested `JWE`_ tokens are the JSON Web Token
77
+equivalent to Fernet tokens and they are encrypted and signed.
78
+
79
+This implementation reserves the right to change, modify, or remove items in
80
+the payload at any point in time and for any reason. Decoding and relying on
81
+attributes within the payload is not a supported API, nor should it be assumed
82
+as one. Users should use formal APIs to request information from keystone. The
83
+development team will not prevent or stall changes to token payloads, which are
84
+internal implementation details of the token provider, due to users relying on
85
+those attributes in ways they shouldn't. Likewise, deployment that consider
86
+information in the token payload sensitive should rely on Fernet to prevent
87
+that information from being exposed to users.
88
+
89
+Similar to the Fernet, JWTs will require a key repository be set up to use for
90
+signing tokens. A new ``keystone-manage`` command will be added to handle
91
+secret generation and rotation which will likely re-use much of the utilities
92
+in the ``fernet_setup`` and ``fernet_rotate`` commands. The recommended
93
+algorithm to be used is ``ES256``.  Keystone should not expose the ability to
94
+end users to ask for a specific JWS algorithm. Support should be limited to
95
+only supported or trusted algorithms that the end user cannot specify. JWS
96
+tokens will be integrity verified with a private key and validated using a
97
+corresponding public key. Since the ``ES256`` implementation only uses signing
98
+(as opposed to signed encrypted payloads), this adheres to slightly better
99
+security practices over fernet because private keys never have to be synced
100
+across keystone API nodes. Only public keys need to be transferred to other
101
+keystone API servers to validate tokens across a cluster.
102
+
103
+The payload of the JWS will use the following `registered claims`_:
104
+
105
+* the `sub` claim will be a **required** string containing the ID of the user
106
+  who authenticated for the token
107
+* the `exp` claim will be a **required** numeric value for token expiration
108
+* the `iat` claim will be a **required** numeric value for the time a token was
109
+  issued
110
+
111
+The following private claims will be used to relay additional required
112
+information and will be prefixed with `openstack` to avoid collisions with
113
+future upstream claims:
114
+
115
+* `openstack_methods` will be a **required** claim denoting the authentication
116
+  methods used to obtain the token
117
+* `openstack_audit_ids` will be a **required** claim containing the audit
118
+  information associated to a token
119
+* `openstack_system` will be an **optional** claim only present in
120
+  system-scoped tokens
121
+* `openstack_domain_id` will be an **optional** claim only present in
122
+  domain-scoped tokens
123
+* `openstack_project_id` will be an **optional** claim only present in
124
+  project-scoped tokens
125
+* `openstack_trust_id` will be an **optional** claim only present in
126
+  trust-scoped tokens
127
+* `openstack_app_cred_id` will be an **optional** claim only present in
128
+  application credential tokens
129
+* `openstack_group_ids` will be an **optional** claim only present in federated
130
+  tokens to carry an ephemeral user's group assignments
131
+* `openstack_idp_id` will be an **optional** claim only present in federated
132
+  tokens to carry the ID of a user's identity provider
133
+* `openstack_protocol_id` will be an **optional** claim only present in
134
+  federated tokens to denote the protocol used by a federated user to
135
+  authenticate
136
+* `openstack_access_token` will be an **optional** claim only present in OAuth
137
+  tokens
138
+
139
+The `PyJWT library`_ is already present in the requirements repository and
140
+would be a convenient choice to use for this implementation. Both the `PyJWT
141
+library`_ and the `JWCrypto library`_ implement support for JWS. Since the
142
+implementation detailed in this specification is unique to ``ES256``, a library
143
+that supports JWE isn't necessary. If supporting another encrypted token type,
144
+like fernet, is a requirement in the future, then finding or contributing JWE
145
+support to the consuming library would be necessary.
146
+
147
+Users will request and present tokens in exactly the same way they currently do
148
+with Fernet tokens. There is no need to add or change any APIs.
149
+
150
+.. _`JSON Web Token standard`: https://tools.ietf.org/html/rfc7519
151
+.. _`JWS`: https://tools.ietf.org/html/rfc7515
152
+.. _`JWE`: https://tools.ietf.org/html/rfc7516
153
+.. _`registered claims`: https://tools.ietf.org/html/rfc7519#section-4.1
154
+.. _`Python libraries`: https://jwt.io/#libraries
155
+.. _`PyJWT library`: https://pyjwt.readthedocs.io/en/latest/
156
+.. _`does not yet support JWE`: https://github.com/jpadilla/pyjwt/issues/143
157
+.. _`JWCrypto library`: http://jwcrypto.readthedocs.org/
158
+
159
+Key Setup & Rotation
160
+--------------------
161
+
162
+Much like the Fernet implementation, a JWT provider will require a key rotation
163
+strategy. Since ``ES256`` relies on asymmetric signing, the suggested rotation
164
+strategy will be slightly different than what is known with Fernet.
165
+
166
+The Fernet implementation requires the usage of a staged key, which is just a
167
+key with a special name, in order to ensure tokens can be validated during the
168
+rotation process. This won't be required with JWT and the following steps
169
+should be sufficient to perform key rotation without token invalidation due to
170
+missing signing keys. Assume the following steps are being performed on three
171
+different API servers, named `K1`, `K2`, and  `K3`, that need to validate
172
+tokens issued by each other.
173
+
174
+1. A key pair is created for each API server. `K1.private`, `K1.pub` for
175
+   `K1`, `K2.private`, `K2.pub` for `K2`, and `K3.private`, `K3.pub` for `K3`.
176
+2. A copy of each public key is transferred to each API server. `K1`, `K2`, and
177
+   `K3` all have copies of `K1.pub`, `K2.pub`, and `K3.pub`.
178
+
179
+At this point, tokens issued from any API server can be validated anywhere. In
180
+the event a single API server needs to rotate keypairs:
181
+
182
+1. A new key pair is created for `K1` called `K1-new.private` and `K1-new.pub`.
183
+   `K1` is configured to start signing tokens with both `K1.private` and
184
+   `K1-new.private.`
185
+2. `K1-new.pub` is copied to the public key repository of each API server. So
186
+   long as `K2` and `K3` have either `K1.pub` or `K1-new.pub` they can validate
187
+   tokens issued by `K1`.
188
+3. After `K2` and `K3` have been updated with copies of `K1-new.pub`,
189
+   `K1.private` can be removed from `K1` and `K1.pub` can be removed from `K2`
190
+   and `K3`. Tokens that were signed with only `K1.private` are unable to be
191
+   verified and `K1.pub` should only be removed after those tokens have expired
192
+   anyway.
193
+
194
+Traditional asymmetric keys can be revoked using revocation lists. At this time
195
+we are not going to support a revocation list implementation for JWT key pairs.
196
+The operator has the ability to sync public keys accordingly when they rotate
197
+new keys in and out. Keystone will only use the public keys on disk to validate
198
+tokens. Is could change in the future, but for now it keeps the key rotation
199
+and key utilities with keystone simpler.
200
+
201
+Crypto-Agility & Future Work
202
+----------------------------
203
+
204
+This specification is targeting a single algorithm for the initial JWT
205
+implementation. If and when keystone decides to expand the implementation to
206
+include additional algorithms, we should allow for flexibility between
207
+configured algorithms, which will make it easier for operators to switch from
208
+one algorithm to another if they need to.
209
+
210
+For example, the validation process using a JWT token provider might support
211
+validating multiple blessed algorithms, allowing multiple tokens signed with
212
+different algorithms to be validated without require configuration changes
213
+except on the signing node.
214
+
215
+Alternatives
216
+------------
217
+
218
+Recently, there have been various efforts that help solve authenticated
219
+encryption. One of these efforts was sparked by a `concern`_ with JWT, namely
220
+the `JOSE`_ header. The issue detailed in the report was specific to users
221
+being able to specify algorithms and exploit a validation weakness in various
222
+JWT libraries. All python libraries have been patched, but keystone should
223
+specifically rely on validating algorithm usage and never assuming algorithms
224
+to be supplied by end users. Please see the full `report`_ for details on the
225
+vulnerability and why we are going to strictly validate this information.
226
+
227
+There is a proof-of-concept implementation for Platform Agnostic Security
228
+Tokens, or `PASETO`_ that takes a more strict stance on algorithm validation
229
+and the intended audience of the token. The strict stance of `versioned
230
+protocols` with `PASETO`_ is certainly advantageous, but the implementation and
231
+idea are still in the incipient stage. It's certainly worth noting that we
232
+should keep out eye on this development and re-evaluate it if, or when, it gets
233
+more adoption.
234
+
235
+For now, if keystone supplies strict algorithm validation to the JWT
236
+implementation, we should be able to offer a comparable backup option to
237
+fernet.
238
+
239
+.. _`concern`: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
240
+.. _`report`: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
241
+.. _`JOSE`: https://tools.ietf.org/html/rfc7519#section-5
242
+.. _`PASETO`: https://github.com/paragonie/paseto
243
+
244
+Security Impact
245
+---------------
246
+
247
+Since JWT is a widely used web standard, this will have a net positive impact
248
+on security. The implementation will use asymmetric signing, reducing risk of
249
+having to replicate or transfer private keys from one host to another. Since
250
+the token payloads are signed, data within the token will be readable to anyone
251
+who has the token. The token can only be validated using the corresponding
252
+public key of the private key used to sign the token originally.  These will
253
+still be bearer tokens and so interception of one must still be guarded
254
+against.
255
+
256
+Known Vulnerabilities
257
+~~~~~~~~~~~~~~~~~~~~~
258
+
259
+There is a documented `vulnerability`_ that affected several JWT libraries,
260
+including one library written in Python.
261
+
262
+In most cases, JSON Web Tokens will have a header, payload, and signature where
263
+each section is delimited by a period (``.``). The header contains an important
264
+piece of information, which is how the token's integrity is protected. This is
265
+stored as the ``alg`` attribute of the header. The library verifying the token
266
+uses the algorithm specified in the header to perform an integrity check and
267
+compares its results to the signature portion of the token.
268
+
269
+Security concerns have been documented and raised that describe the issues with
270
+allowing clients to dictate algorithms used for token verification. This is a
271
+concern specifically with applications that support asymmetric and symmetric
272
+signing. An attacker could effectively bypass the verification check of a
273
+token by using a published, or known, public key to generate a JWT with a
274
+symmetric signing algorithm.
275
+
276
+This would be applicable if keystone supported signed tokens and encrypted
277
+tokens with the same token provider implementation. This vulnerability has been
278
+addressed across various libraries after its discovery, but keystone should be
279
+aware of the overall technique that lead to it in the first place. We can
280
+mitigate this type of vulnerability in keystone by:
281
+
282
+* Ensuring keystone doesn't blindly allow end users to specify which algorithm
283
+  is used to verify the integrity of a token (e.g., only implementing support
284
+  for ``ES256``)
285
+* Ensure the ``alg`` supplied in the token header is only ever populated by
286
+  keystone
287
+* Ensure keystone only issues tokens of a single encryption or signing strategy
288
+  (e.g., not allowing users to get signed token and encrypted tokens from the
289
+  same server, thus mixing asymmetric and symmetric key usage at runtime)
290
+
291
+Specifics about the `vulnerability`_ can be found in the report.
292
+
293
+.. _`vulnerability`: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
294
+
295
+Notifications Impact
296
+--------------------
297
+
298
+Notifications for JWTs will behave in the same way that they do for fernet
299
+tokens, including for revocation events.
300
+
301
+Other End User Impact
302
+---------------------
303
+
304
+This will have no end user impact. They will request and use JWTs in exactly
305
+the same way that they currently use fernet tokens.
306
+
307
+Performance Impact
308
+------------------
309
+
310
+It will be worth investigating performance differences between token providers
311
+that use asymmetric signing (JWT) and symmetric encryption (fernet). These
312
+difference, if significant, should be published in documentation as it might be
313
+useful for operators when choosing a token provider.
314
+
315
+Other Deployer Impact
316
+---------------------
317
+
318
+This is an optional, opt-in feature that will not be the default, so deployers
319
+will not be affected unless they choose to use JWT. In that case, deployers
320
+will need to set up a key repository before using JWTs. The key repository will
321
+contain asymmetric key pairs rather than just secret keys. The deployer will
322
+need to take care to sync and rotate keys the way they do with fernet tokens.
323
+
324
+Developer Impact
325
+----------------
326
+
327
+The new token type will reuse much of the work already done for fernet tokens
328
+and will follow similar code paths, so this will be relatively easy to
329
+maintain.
330
+
331
+Implementation
332
+==============
333
+
334
+Assignee(s)
335
+-----------
336
+
337
+Primary assignee:
338
+  Gage Hugo (gagehugo)
339
+  Lance Bragstad (lbragstad)
340
+  XiYuan Wang (wxy)
341
+
342
+Work Items
343
+----------
344
+
345
+* Refactor the fernet utilities modules to be generic enough to work with JWT
346
+  or inheritable
347
+* Add a ``keystone-manage`` command to set up and rotate JWT signing keys
348
+* Generalize the ``TokenFormatter`` class to support JWT
349
+* Refactor the fernet token provider module to be inheritable or generic
350
+* Add a keystone doctor command to validate the setup in the same way that
351
+  fernet is validated
352
+
353
+
354
+Dependencies
355
+============
356
+
357
+There are three different libraries we can use to implement this functionality.
358
+
359
+1. `PyJWT`_
360
+
361
+   This library only supports token signing, or JWS. It does not support JWE,
362
+   or authenticated encryption, yet. A minimum version of **1.0.1** is
363
+   `required`_, but this library is already included in OpenStack global
364
+   requirements repository.
365
+
366
+2. `python-jose`_
367
+
368
+   This library only supports token signing, or JWS. It does not support JWE,
369
+   or authenticated encryption, yet. This library is not included in OpenStack
370
+   global requirements.
371
+
372
+3. `JWCrypto`_
373
+
374
+   This library supports both JWS and JWE, but it is not included in OpenStack
375
+   global requirements.
376
+
377
+3. `Authlib`_
378
+
379
+   This library supports both JWS and JWE, but its licensing is incompatible
380
+   with OpenStack as it is AGPL.
381
+
382
+Given the fact that the initial implementation of JWT is not going to rely on
383
+nested JWT tokens or encrypted payloads, it's safe to assume that signing
384
+support will be sufficient. The PyJWT library is already included in global
385
+requirements and we don't have a case to not use that specific library, which
386
+is compatible with OpenStack licensing.
387
+
388
+.. _`PyJWT`: https://pyjwt.readthedocs.io/en/latest/
389
+.. _`required`: https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/
390
+.. _`python-jose`: https://python-jose.readthedocs.io/en/latest/
391
+.. _`JWCrypto`: http://jwcrypto.readthedocs.io/en/latest/
392
+.. _`Authlib`: https://docs.authlib.org/en/latest/
393
+
394
+Documentation Impact
395
+====================
396
+
397
+The new ``[token]/provider`` configuration option will need to be documented,
398
+as will the new ``keystone-manage`` commands.
399
+
400
+
401
+References
402
+==========
403
+
404
+* `JSON Web Token RFC <https://tools.ietf.org/html/rfc7519>`_
405
+* `JSON Web Token light introduction <https://jwt.io/introduction/>`_
406
+* `History of cryptography's adoption of fernet <https://github.com/pyca/cryptography/issues/2900>`_

Loading…
Cancel
Save