Add an admin endpoint to allow authorizing server to signal token revocations

changelog.d/16117.misc

@@ -0,0 +1 @@
+Cache token introspection response from OIDC provider.

changelog.d/16125.misc

@@ -0,0 +1 @@
+Add an admin endpoint to allow authorizing server to signal token revocations.

synapse/api/auth/msc3861_delegated.py

@@ -39,6 +39,7 @@
 from synapse.types import Requester, UserID, create_requester
 from synapse.util import json_decoder
 from synapse.util.caches.cached_call import RetryOnExceptionCachedCall
+from synapse.util.caches.expiringcache import ExpiringCache
 
 if TYPE_CHECKING:
     from synapse.server import HomeServer
@@ -106,6 +107,14 @@ def __init__(self, hs: "HomeServer"):
 
         self._issuer_metadata = RetryOnExceptionCachedCall(self._load_metadata)
 
+        self._clock = hs.get_clock()
+        self._token_cache: ExpiringCache[str, IntrospectionToken] = ExpiringCache(
+            cache_name="introspection_token_cache",
+            clock=self._clock,
+            max_len=10000,
+            expiry_ms=5 * 60 * 1000,
+        )
+
         if isinstance(auth_method, PrivateKeyJWTWithKid):
             # Use the JWK as the client secret when using the private_key_jwt method
             assert self._config.jwk, "No JWK provided"
@@ -144,6 +153,20 @@ async def _introspect_token(self, token: str) -> IntrospectionToken:
         Returns:
             The introspection response
         """
+        # check the cache before doing a request
+        introspection_token = self._token_cache.get(token, None)
+
+        if introspection_token:
+            # check the expiration field of the token (if it exists)
+            exp = introspection_token.get("exp", None)
+            if exp:
+                time_now = self._clock.time()
+                expired = time_now > exp
+                if not expired:
+                    return introspection_token
+            else:
+                return introspection_token
+
         metadata = await self._issuer_metadata.get()
         introspection_endpoint = metadata.get("introspection_endpoint")
         raw_headers: Dict[str, str] = {
@@ -157,7 +180,10 @@ async def _introspect_token(self, token: str) -> IntrospectionToken:
 
         # Fill the body/headers with credentials
         uri, raw_headers, body = self._client_auth.prepare(
-            method="POST", uri=introspection_endpoint, headers=raw_headers, body=body
+            method="POST",
+            uri=introspection_endpoint,
+            headers=raw_headers,
+            body=body,
         )
         headers = Headers({k: [v] for (k, v) in raw_headers.items()})
 
@@ -187,7 +213,17 @@ async def _introspect_token(self, token: str) -> IntrospectionToken:
                 "The introspection endpoint returned an invalid JSON response."
             )
 
-        return IntrospectionToken(**resp)
+        expiration = resp.get("exp", None)
+        if expiration:
+            if self._clock.time() > expiration:
+                raise InvalidClientTokenError("Token is expired.")
+
+        introspection_token = IntrospectionToken(**resp)
+
+        # add token to cache
+        self._token_cache[token] = introspection_token
+
+        return introspection_token
 
     async def is_server_admin(self, requester: Requester) -> bool:
         return "urn:synapse:admin:*" in requester.scope

synapse/rest/admin/__init__.py

@@ -47,6 +47,7 @@
     ListDestinationsRestServlet,
 )
 from synapse.rest.admin.media import ListMediaInRoom, register_servlets_for_media_repo
+from synapse.rest.admin.oidc import OIDCTokenRevocationRestServlet
 from synapse.rest.admin.registration_tokens import (
     ListRegistrationTokensRestServlet,
     NewRegistrationTokenRestServlet,
@@ -297,6 +298,8 @@ def register_servlets(hs: "HomeServer", http_server: HttpServer) -> None:
     BackgroundUpdateRestServlet(hs).register(http_server)
     BackgroundUpdateStartJobRestServlet(hs).register(http_server)
     ExperimentalFeaturesRestServlet(hs).register(http_server)
+    if hs.config.experimental.msc3861.enabled:
+        OIDCTokenRevocationRestServlet(hs).register(http_server)
 
 
 def register_servlets_for_client_rest_resource(

synapse/rest/admin/oidc.py

@@ -0,0 +1,50 @@
+# Copyright 2023 The Matrix.org Foundation C.I.C
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Dict, Tuple
+
+from synapse.api.errors import InvalidClientTokenError
+from synapse.http.servlet import RestServlet
+from synapse.http.site import SynapseRequest
+from synapse.rest.admin._base import admin_patterns, assert_requester_is_admin
+
+if TYPE_CHECKING:
+    from synapse.server import HomeServer
+
+
+class OIDCTokenRevocationRestServlet(RestServlet):
+    """
+    Delete a given token introspection response - identified by the `jti` field - from the
+    introspection token cache when a token is revoked at the authorizing server
+    """
+
+    PATTERNS = admin_patterns("/OIDC_token_revocation/(?P<token_id>[^/]*)")
+
+    def __init__(self, hs: "HomeServer"):
+        super().__init__()
+        self.auth = hs.get_auth()
+
+    async def on_DELETE(
+        self, request: SynapseRequest, token_id: str
+    ) -> Tuple[HTTPStatus, Dict]:
+        await assert_requester_is_admin(self.auth, request)
+
+        try:
+            # mypy ignore - this attribute is defined on MSC3861DelegatedAuth, which is loaded via a config flag
+            # this endpoint will only be loaded if the same config flag is present
+            self.auth._token_cache.pop(token_id)  # type: ignore[attr-defined]
+        except KeyError:
+            raise InvalidClientTokenError("Token not found.")
+
+        return HTTPStatus.OK, {}

tests/handlers/test_oauth_delegation.py

@@ -14,7 +14,7 @@
 
 from http import HTTPStatus
 from typing import Any, Dict, Union
-from unittest.mock import ANY, Mock
+from unittest.mock import ANY, AsyncMock, Mock
 from urllib.parse import parse_qs
 
 from signedjson.key import (
@@ -491,6 +491,100 @@ def test_unavailable_introspection_endpoint(self) -> None:
         error = self.get_failure(self.auth.get_user_by_req(request), SynapseError)
         self.assertEqual(error.value.code, 503)
 
+    def test_introspection_token_cache(self) -> None:
+        access_token = "open_sesame"
+        self.http_client.request = simple_async_mock(
+            return_value=FakeResponse.json(
+                code=200,
+                payload={"active": "true", "scope": "guest", "jti": access_token},
+            )
+        )
+
+        # first call should cache response
+        # Mpyp ignores below are due to mypy not understanding the dynamic substitution of msc3861 auth code
+        # for regular auth code via the config
+        self.get_success(
+            self.auth._introspect_token(access_token)  # type: ignore[attr-defined]
+        )
+        introspection_token = self.auth._token_cache.get(access_token)  # type: ignore[attr-defined]
+        self.assertEqual(introspection_token["jti"], access_token)
+        # there's been one http request
+        self.http_client.request.assert_called_once()
+
+        # second call should pull from cache, there should still be only one http request
+        token = self.get_success(self.auth._introspect_token(access_token))  # type: ignore[attr-defined]
+        self.http_client.request.assert_called_once()
+        self.assertEqual(token["jti"], access_token)
+
+        # advance past five minutes and check that cache expired - there should be more than one http call now
+        self.reactor.advance(360)
+        token_2 = self.get_success(self.auth._introspect_token(access_token))  # type: ignore[attr-defined]
+        self.assertEqual(self.http_client.request.call_count, 2)
+        self.assertEqual(token_2["jti"], access_token)
+
+        # test that if a cached token is expired, a fresh token will be pulled from authorizing server - first add a
+        # token with a soon-to-expire `exp` field to the cache
+        self.http_client.request = simple_async_mock(
+            return_value=FakeResponse.json(
+                code=200,
+                payload={
+                    "active": "true",
+                    "scope": "guest",
+                    "jti": "stale",
+                    "exp": self.clock.time() + 100,
+                },
+            )
+        )
+        self.get_success(
+            self.auth._introspect_token("stale")  # type: ignore[attr-defined]
+        )
+        introspection_token = self.auth._token_cache.get("stale")  # type: ignore[attr-defined]
+        self.assertEqual(introspection_token["jti"], "stale")
+        self.assertEqual(self.http_client.request.call_count, 1)
+
+        # advance the reactor past the token expiry but less than the cache expiry
+        self.reactor.advance(120)
+        self.assertEqual(self.auth._token_cache.get("stale"), introspection_token)  # type: ignore[attr-defined]
+
+        # check that the next call causes another http request (which will fail because the token is technically expired
+        # but the important thing is we discard the token from the cache and try the network)
+        self.get_failure(
+            self.auth._introspect_token("stale"), InvalidClientTokenError  # type: ignore[attr-defined]
+        )
+        self.assertEqual(self.http_client.request.call_count, 2)
+
+    def test_revocation_endpoint(self) -> None:
+        # mock introspection response and then admin verification response
+        self.http_client.request = AsyncMock(
+            side_effect=[
+                FakeResponse.json(
+                    code=200, payload={"active": True, "jti": "open_sesame"}
+                ),
+                FakeResponse.json(
+                    code=200,
+                    payload={
+                        "active": True,
+                        "sub": SUBJECT,
+                        "scope": " ".join([SYNAPSE_ADMIN_SCOPE, MATRIX_USER_SCOPE]),
+                        "username": USERNAME,
+                    },
+                ),
+            ]
+        )
+
+        # cache a token to delete
+        introspection_token = self.get_success(
+            self.auth._introspect_token("open_sesame")  # type: ignore[attr-defined]
+        )
+        self.assertEqual(self.auth._token_cache.get("open_sesame"), introspection_token)  # type: ignore[attr-defined]
+
+        # delete the revoked token
+        introspection_token_id = "open_sesame"
+        url = f"/_synapse/admin/v1/OIDC_token_revocation/{introspection_token_id}"
+        channel = self.make_request("DELETE", url, access_token="mockAccessToken")
+        self.assertEqual(channel.code, 200)
+        self.assertEqual(self.auth._token_cache.get("open_sesame"), None)  # type: ignore[attr-defined]
+
     def make_device_keys(self, user_id: str, device_id: str) -> JsonDict:
         # We only generate a master key to simplify the test.
         master_signing_key = generate_signing_key(device_id)