Merge branch 'master' into fix/introspection

Author: ZuSe

AUTHORS

@@ -26,6 +26,7 @@ David Smith
 Diego Garcia
 Dulmandakh Sukhbaatar
 Dylan Giesler
+Dylan Tack
 Emanuele Palazzetti
 Federico Dolce
 Frederico Vieira
@@ -40,6 +41,7 @@ Jonathan Steffan
 Jozef Knaperek
 Jun Zhou
 Kristian Rune Larsen
+Michael Howitz
 Paul Dekkers
 Paul Oswald
 Pavel Tvrdík

CHANGELOG.md

@@ -22,6 +22,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 * #712, #636, #808. Calls to `django.contrib.auth.authenticate()` now pass a `request`
   to provide compatibility with backends that need one.
+* #950 Add support for RSA key rotation.
 
 ### Fixed
 * #524 Restrict usage of timezone aware expire dates to Django projects with USE_TZ set to True.

docs/getting_started.rst

@@ -358,7 +358,7 @@ Export the credential as an environment variable
 
     export CREDENTIAL=YXhYU1NCVnV2T3lHVnpoNFB1cnZLYXE1TUhYTW03RnRySGdETWk0dToxZnV2NVdWZlI3QTVCbEYwbzE1NUg3czViTGdYbHdXTGhpM1k3cGRKOWFKdUNkbDBYVjVDeGdkMHRyaTduU3pDODBxeXJvdmg4cUZYRkhnRkFBYzBsZFBObjVaWUxhbnhTbTFTSTFyeGxScldVUDU5MXdwSERHYTNwU3BCNmRDWg==
 
-To start the Client Credential flow you call ``/token/`` endpoint direct::
+To start the Client Credential flow you call ``/token/`` endpoint directly::
 
     curl -X POST -H "Authorization: Basic ${CREDENTIAL}" -H "Cache-Control: no-cache" -H "Content-Type: application/x-www-form-urlencoded" "http://127.0.0.1:8000/o/token/" -d "grant_type=client_credentials"
 

docs/oidc.rst

@@ -100,6 +100,30 @@ change this class to derive from ``oauthlib.openid.Server`` instead of
 With ``RSA`` key-pairs, the public key can be generated from the private key,
 so there is no need to add a setting for the public key.
 
+
+Rotating the RSA private key
+~~~~~~~~~~~~~~~~~~~~~~~~
+Extra keys can be published in the jwks_uri with the ``OIDC_RSA_PRIVATE_KEYS_INACTIVE``
+setting. For example:::
+
+    OAUTH2_PROVIDER = {
+        "OIDC_RSA_PRIVATE_KEY": os.environ.get("OIDC_RSA_PRIVATE_KEY"),
+        "OIDC_RSA_PRIVATE_KEYS_INACTIVE": [
+            os.environ.get("OIDC_RSA_PRIVATE_KEY_2"),
+            os.environ.get("OIDC_RSA_PRIVATE_KEY_3")
+        ]
+        # ... other settings
+    }
+
+To rotate, follow these steps:
+
+#. Generate a new key, and add it to the inactive set. Then deploy the app.
+#. Swap the active and inactive keys, then re-deploy.
+#. After some reasonable amount of time, remove the inactive key. At a minimum,
+   you should wait ``ID_TOKEN_EXPIRE_SECONDS`` to ensure the key isn't removed
+   before valid tokens expire.
+
+
 Using ``HS256`` keys
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -297,7 +321,7 @@ query, and other details.
 JwksInfoView
 ~~~~~~~~~~~~
 
-Available at ``/o/.well-known/jwks.json``, this view provides details of the key used to sign
+Available at ``/o/.well-known/jwks.json``, this view provides details of the keys used to sign
 the JWTs generated for ID tokens, so that clients are able to verify them.
 
 

docs/settings.rst

@@ -264,6 +264,25 @@ Default: ``""``
 
 The RSA private key used to sign OIDC ID tokens. If not set, OIDC is disabled.
 
+OIDC_RSA_PRIVATE_KEYS_INACTIVE
+~~~~~~~~~~~~~~~~~~~~
+Default: ``[]``
+
+An array of *inactive* RSA private keys. These keys are not used to sign tokens,
+but are published in the jwks_uri location.
+
+This is useful for providing a smooth transition during key rotation.
+``OIDC_RSA_PRIVATE_KEY`` can be replaced, and recently decommissioned keys
+should be retained in this inactive list.
+
+OIDC_JWKS_MAX_AGE_SECONDS
+~~~~~~~~~~~~~~~~~~~~~~
+Default: ``3600``
+
+The max-age value for the Cache-Control header on jwks_uri.
+
+This enables the verifier to safely cache the JWK Set and not have to re-download
+the document for every token.
 
 OIDC_USERINFO_ENDPOINT
 ~~~~~~~~~~~~~~~~~~~~~~

docs/tutorial/tutorial_01.rst

@@ -33,6 +33,8 @@ Include the Django OAuth Toolkit urls in your `urls.py`, choosing the urlspace y
 
 .. code-block:: python
 
+    from django.urls import path, include
+
     urlpatterns = [
         path("admin", admin.site.urls),
         path("o/", include('oauth2_provider.urls', namespace='oauth2_provider')),

docs/tutorial/tutorial_03.rst

@@ -15,21 +15,21 @@ which takes care of token verification. In your settings.py:
 
 .. code-block:: python
 
-    AUTHENTICATION_BACKENDS = (
+    AUTHENTICATION_BACKENDS = [
         'oauth2_provider.backends.OAuth2Backend',
         # Uncomment following if you want to access the admin
-        #'django.contrib.auth.backends.ModelBackend'
+        #'django.contrib.auth.backends.ModelBackend',
         '...',
-    )
+    ]
 
-    MIDDLEWARE = (
+    MIDDLEWARE = [
         '...',
         # If you use SessionAuthenticationMiddleware, be sure it appears before OAuth2TokenMiddleware.
         # SessionAuthenticationMiddleware is NOT required for using django-oauth-toolkit.
         'django.contrib.auth.middleware.SessionAuthenticationMiddleware',
         'oauth2_provider.middleware.OAuth2TokenMiddleware',
         '...',
-    )
+    ]
 
 You will likely use the `django.contrib.auth.backends.ModelBackend` along with the OAuth2 backend
 (or you might not be able to log in into the admin), only pay attention to the order in which

oauth2_provider/settings.py

@@ -72,6 +72,8 @@
     "OIDC_ISS_ENDPOINT": "",
     "OIDC_USERINFO_ENDPOINT": "",
     "OIDC_RSA_PRIVATE_KEY": "",
+    "OIDC_RSA_PRIVATE_KEYS_INACTIVE": [],
+    "OIDC_JWKS_MAX_AGE_SECONDS": 3600,
     "OIDC_RESPONSE_TYPES_SUPPORTED": [
         "code",
         "token",

oauth2_provider/views/oidc.py

@@ -71,12 +71,23 @@ class JwksInfoView(OIDCOnlyMixin, View):
     def get(self, request, *args, **kwargs):
         keys = []
         if oauth2_settings.OIDC_RSA_PRIVATE_KEY:
-            key = jwk.JWK.from_pem(oauth2_settings.OIDC_RSA_PRIVATE_KEY.encode("utf8"))
-            data = {"alg": "RS256", "use": "sig", "kid": key.thumbprint()}
-            data.update(json.loads(key.export_public()))
-            keys.append(data)
+            for pem in [
+                oauth2_settings.OIDC_RSA_PRIVATE_KEY,
+                *oauth2_settings.OIDC_RSA_PRIVATE_KEYS_INACTIVE,
+            ]:
+
+                key = jwk.JWK.from_pem(pem.encode("utf8"))
+                data = {"alg": "RS256", "use": "sig", "kid": key.thumbprint()}
+                data.update(json.loads(key.export_public()))
+                keys.append(data)
         response = JsonResponse({"keys": keys})
         response["Access-Control-Allow-Origin"] = "*"
+        response["Cache-Control"] = (
+            "Cache-Control: public, "
+            + f"max-age={oauth2_settings.OIDC_JWKS_MAX_AGE_SECONDS}, "
+            + f"stale-while-revalidate={oauth2_settings.OIDC_JWKS_MAX_AGE_SECONDS}, "
+            + f"stale-if-error={oauth2_settings.OIDC_JWKS_MAX_AGE_SECONDS}"
+        )
         return response
 
 

tests/presets.py

@@ -12,6 +12,7 @@
     "OIDC_ISS_ENDPOINT": "http://localhost/o",
     "OIDC_USERINFO_ENDPOINT": "http://localhost/o/userinfo/",
     "OIDC_RSA_PRIVATE_KEY": settings.OIDC_RSA_PRIVATE_KEY,
+    "OIDC_RSA_PRIVATE_KEYS_INACTIVE": settings.OIDC_RSA_PRIVATE_KEYS_INACTIVE,
     "SCOPES": {
         "read": "Reading scope",
         "write": "Writing scope",