Tell a client only about the tokens that were issued to it by default

Author: cicnavi

config/module_oidc.php.dist

@@ -1890,6 +1890,31 @@ $config = [
      */
     ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_ENDPOINT_ENABLED => false,
 
+    /**
+     * (optional) Client IDs allowed to introspect tokens issued to any client,
+     * and not only to themselves. Default is an empty list.
+     *
+     * A client which authenticates at the introspection endpoint may always ask
+     * about tokens issued to itself, which tells it nothing it did not already
+     * hold. Asking about another client's token is a different matter, since
+     * the answer carries that token's subject, scopes and lifetime, so it is
+     * refused unless the client is named here. A refused request is answered as
+     * if the token was not active, rather than with an error, so that the
+     * endpoint can not be used to find out which tokens exist.
+     *
+     * This is deliberately a deployment decision instead of a client property.
+     * Were it registered client metadata, a client registering itself through
+     * Dynamic Client Registration could ask for the ability to read every other
+     * party's tokens.
+     *
+     * Callers authorized with an API token holding an introspection scope, and
+     * logged in SimpleSAMLphp administrators, may introspect any token and are
+     * not affected by this option.
+     */
+    ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_RESOURCE_SERVER_CLIENT_IDS => [
+//        'resource-server-client-id',
+    ],
+
     /**
      * List of API tokens which can be used to access API endpoints based on
      * given scopes. The format is: ['token' => [ApiScopesEnum]]

docs/6-oidc-upgrade.md

@@ -263,6 +263,13 @@ setting allowed time tolerance for timestamp validation in artifacts like JWSs.
 multiple Federation-related signing algorithms and key pairs.
 - `ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_ENDPOINT_ENABLED` -
 optional, enables the OAuth2 token introspection endpoint as per RFC7662.
+- `ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_RESOURCE_SERVER_CLIENT_IDS` -
+optional, client IDs allowed to introspect tokens issued to any client (default
+`[]`). A client which authenticates at the introspection endpoint is otherwise
+told only about tokens issued to itself, and answered `active: false` for
+anyone else's. Name a resource server here if it introspects tokens issued to
+other clients. API tokens with an introspection scope and logged in
+administrators are unaffected.
 - `ModuleConfig::OPTION_PAR_REQUEST_URI_TTL` - optional, lifetime of a PAR
 `request_uri` (default `PT10M`).
 - `ModuleConfig::OPTION_REQUIRE_PUSHED_AUTHORIZATION_REQUESTS` - optional,

docs/8-api.md

@@ -336,6 +336,31 @@ authentication methods (Basic, Post, Private Key JWT, Bearer).
 * Or, if the request is authorized using an API Bearer Token with
 the appropriate scope.
 
+Authenticating is not on its own permission to introspect any given token.
+A client which authenticates as itself is told about tokens issued to it, and
+answered with `active: false` for tokens issued to anyone else. It already
+holds its own tokens, so it learns nothing new about them, while another
+client's token would answer with that token's subject, scopes and lifetime.
+
+A deployment which runs a resource server as a client of its own names it in
+`config/module_oidc.php`, and that client may then introspect any token:
+
+```php
+use SimpleSAML\Module\oidc\ModuleConfig;
+
+ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_RESOURCE_SERVER_CLIENT_IDS => [
+    'resource-server-client-id',
+],
+```
+
+This is configuration rather than client metadata on purpose: a client
+registering itself through Dynamic Client Registration must not be able to ask
+for the ability to read every other party's tokens.
+
+Requests authorized with an API Bearer Token holding an introspection scope,
+and those made by a logged in SimpleSAMLphp administrator, may introspect any
+token and are unaffected by that option.
+
 #### Request
 
 The request is sent with `application/x-www-form-urlencoded` encoding with the
@@ -368,7 +393,9 @@ authorized the token.
 * __jti__ (string, optional): Identifier for the token.
 
 If the token is not active, only the `active` field with a value of
-`false` is returned.
+`false` is returned. The same answer is given when the caller is not entitled
+to be told about the token, so an inactive answer does not distinguish a token
+which does not exist from one the caller may not see.
 
 #### Sample 1
 

src/Admin/ConfigOverview/ProtocolOverviewBuilder.php

@@ -809,6 +809,32 @@ protected function buildApiSection(): Section
                 ConfigOverviewValueTypeEnum::Text,
                 ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_ENDPOINT_ENABLED,
             ),
+            $this->guardRow(
+                Translate::noop('Token Introspection Resource Servers'),
+                ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_RESOURCE_SERVER_CLIENT_IDS,
+                function (): Row {
+                    $resourceServers = $this->moduleConfig
+                        ->getApiOAuth2TokenIntrospectionResourceServerClientIds();
+
+                    return new Row(
+                        Translate::noop('Token Introspection Resource Servers'),
+                        $resourceServers,
+                        ConfigOverviewValueTypeEnum::StringList,
+                        ModuleConfig::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_RESOURCE_SERVER_CLIENT_IDS,
+                        $resourceServers === [] ?
+                        Translate::noop(
+                            'None, so a client authenticating at the introspection endpoint is only ' .
+                            'told about tokens issued to itself. API tokens and administrators are ' .
+                            'unaffected.',
+                        ) :
+                        Translate::noop(
+                            'These clients may introspect tokens issued to any client, and not only ' .
+                            'their own, so each one can read every other client\'s token subject and ' .
+                            'scopes.',
+                        ),
+                    );
+                },
+            ),
             $this->buildSecretCountRow(
                 Translate::noop('API Tokens'),
                 $apiTokenCount,

src/Controllers/OAuth2/TokenIntrospectionController.php

@@ -16,6 +16,7 @@
 use SimpleSAML\Module\oidc\Utils\AuthenticatedOAuth2ClientResolver;
 use SimpleSAML\Module\oidc\Utils\RequestParamsResolver;
 use SimpleSAML\Module\oidc\Utils\Routes;
+use SimpleSAML\Module\oidc\ValueAbstracts\IntrospectionAuthorization;
 use SimpleSAML\Module\oidc\ValueAbstracts\ResolvedClientAuthenticationMethod;
 use SimpleSAML\OpenID\Codebooks\ClaimsEnum;
 use SimpleSAML\OpenID\Codebooks\HttpMethodsEnum;
@@ -53,7 +54,7 @@ public function __construct(
     public function __invoke(Request $request): Response
     {
         try {
-            $this->ensureAuthenticatedClient($request);
+            $introspectionAuthorization = $this->resolveIntrospectionAuthorization($request);
         } catch (AuthorizationException $e) {
             $this->loggerService->error(
                 'TokenIntrospectionController::invoke: AuthorizationException: ' . $e->getMessage(),
@@ -89,21 +90,55 @@ public function __invoke(Request $request): Response
 
         $payload = null;
         if (is_null($tokenTypeHintParam)) {
-            $payload = $this->resolveAccessTokenPayload($tokenParam) ??
-            $this->resolveRefreshTokenPayload($tokenParam);
+            $payload = $this->resolveAccessTokenPayload($tokenParam, $introspectionAuthorization) ??
+            $this->resolveRefreshTokenPayload($tokenParam, $introspectionAuthorization);
         } elseif ($tokenTypeHintParam === 'access_token') {
-            $payload = $this->resolveAccessTokenPayload($tokenParam);
+            $payload = $this->resolveAccessTokenPayload($tokenParam, $introspectionAuthorization);
         } elseif ($tokenTypeHintParam === 'refresh_token') {
-            $payload = $this->resolveRefreshTokenPayload($tokenParam);
+            $payload = $this->resolveRefreshTokenPayload($tokenParam, $introspectionAuthorization);
         }
 
         $payload = $payload ?? ['active' => false];
 
         return $this->routes->newJsonResponse($payload);
     }
 
-    protected function resolveAccessTokenPayload(string $tokenParam): ?array
-    {
+    /**
+     * Whether the caller is to be told about a token issued to the given client, logging any refusal.
+     *
+     * Asked with the owner as the token itself gives it, before the payload is assembled: the payload has
+     * its empty values dropped, so reading the owner back out of it would lose a client identifier which
+     * PHP considers falsy, and refuse that client its own tokens.
+     */
+    protected function isTokenIntrospectableBy(
+        IntrospectionAuthorization $introspectionAuthorization,
+        mixed $tokenClientId,
+    ): bool {
+        $clientId = (is_string($tokenClientId) && $tokenClientId !== '') ? $tokenClientId : null;
+
+        if ($introspectionAuthorization->mayIntrospectTokenOf($clientId)) {
+            return true;
+        }
+
+        $this->loggerService->warning(
+            sprintf(
+                'Client %s asked about a token which was not issued to it. Answering as if the token ' .
+                'was not active.',
+                (string)$introspectionAuthorization->getClientId(),
+            ),
+        );
+
+        // Deliberately the same answer an expired, revoked or made up token gets. Saying that the token
+        // exists but is none of the caller's business would turn the endpoint into an oracle it could ask
+        // about tokens it has come into possession of, which is what RFC 7662 section 2.2 has in mind when
+        // it has an unauthorized request answered as an inactive token.
+        return false;
+    }
+
+    protected function resolveAccessTokenPayload(
+        string $tokenParam,
+        IntrospectionAuthorization $introspectionAuthorization,
+    ): ?array {
         try {
             $accessToken = $this->bearerTokenValidator->ensureValidAccessToken($tokenParam);
         } catch (\Throwable $e) {
@@ -123,6 +158,10 @@ protected function resolveAccessTokenPayload(string $tokenParam): ?array
 
         $clientId = is_array($audience = $accessToken->getAudience()) ? $audience[0] ?? null : null;
 
+        if (!$this->isTokenIntrospectableBy($introspectionAuthorization, $clientId)) {
+            return null;
+        }
+
         return array_filter([
             'active' => true,
             'scope' => $scopeClaim,
@@ -141,8 +180,10 @@ protected function resolveAccessTokenPayload(string $tokenParam): ?array
     /**
      * @psalm-suppress MixedAssignment
      */
-    public function resolveRefreshTokenPayload(string $tokenParam): ?array
-    {
+    protected function resolveRefreshTokenPayload(
+        string $tokenParam,
+        IntrospectionAuthorization $introspectionAuthorization,
+    ): ?array {
         try {
             $decryptedToken = $this->oAuth2Bridge->decrypt($tokenParam);
             $tokenData = json_decode($decryptedToken, true, 512, JSON_THROW_ON_ERROR);
@@ -196,6 +237,10 @@ public function resolveRefreshTokenPayload(string $tokenParam): ?array
 
         $clientId = is_string($clientId = $tokenData['client_id'] ?? null) ? $clientId : null;
 
+        if (!$this->isTokenIntrospectableBy($introspectionAuthorization, $clientId)) {
+            return null;
+        }
+
         return array_filter([
             'active' => true,
             'scope' => $scopeClaim,
@@ -218,11 +263,19 @@ protected function prepareScopeString(array $scopes): string
     }
 
     /**
+     * Establish who is asking, and with it which tokens they are entitled to be told about.
+     *
+     * Authenticating is not on its own permission to introspect. A client which authenticates as itself is
+     * held to its own tokens, since anything else would let any registered client - including one which
+     * registered itself through Dynamic Client Registration - read the subject, scopes and lifetime of
+     * tokens belonging to every other client of this OP.
+     *
      * @throws AuthorizationException
+     * @throws \Exception
      */
-    protected function ensureAuthenticatedClient(Request $request): void
+    protected function resolveIntrospectionAuthorization(Request $request): IntrospectionAuthorization
     {
-        $this->loggerService->debug('TokenIntrospectionController::ensureAuthenticatedClient - start');
+        $this->loggerService->debug('TokenIntrospectionController::resolveIntrospectionAuthorization - start');
         $this->loggerService->debug('Trying supported OAuth2 client authentication methods.');
 
         // First, try regular OAuth2 client authentication methods.
@@ -232,15 +285,34 @@ protected function ensureAuthenticatedClient(Request $request): void
             $resolvedClientAuthenticationMethod instanceof ResolvedClientAuthenticationMethod &&
             $resolvedClientAuthenticationMethod->getClientAuthenticationMethod()->isNotNone()
         ) {
+            $clientId = $resolvedClientAuthenticationMethod->getClient()->getIdentifier();
+
             $this->loggerService->debug(
                 sprintf(
                     'Client %s authenticated using supported OAuth2 client authentication method %s.',
-                    $resolvedClientAuthenticationMethod->getClient()->getIdentifier(),
+                    $clientId,
                     $resolvedClientAuthenticationMethod->getClientAuthenticationMethod()->value,
                 ),
             );
 
-            return;
+            if (
+                in_array(
+                    $clientId,
+                    $this->moduleConfig->getApiOAuth2TokenIntrospectionResourceServerClientIds(),
+                    true,
+                )
+            ) {
+                $this->loggerService->debug(
+                    sprintf(
+                        'Client %s is configured as a resource server, so it may introspect any token.',
+                        $clientId,
+                    ),
+                );
+
+                return IntrospectionAuthorization::forAnyToken();
+            }
+
+            return IntrospectionAuthorization::forTokensOfClient($clientId);
         }
 
         $this->loggerService->debug('No regular OAuth2 client authentication method found.');
@@ -252,5 +324,9 @@ protected function ensureAuthenticatedClient(Request $request): void
         );
 
         $this->loggerService->debug('API client authenticated.');
+
+        // The administrative path. Reaching it means either a logged in SimpleSAMLphp administrator or an
+        // API token the deployment issued and scoped by hand, neither of which is tied to a single client.
+        return IntrospectionAuthorization::forAnyToken();
     }
 }

src/ModuleConfig.php

@@ -152,6 +152,8 @@ class ModuleConfig
     'api_vci_credential_status_endpoint_enabled';
     final public const string OPTION_API_OAUTH2_TOKEN_INTROSPECTION_ENDPOINT_ENABLED =
     'api_oauth2_token_introspection_endpoint_enabled';
+    final public const string OPTION_API_OAUTH2_TOKEN_INTROSPECTION_RESOURCE_SERVER_CLIENT_IDS =
+    'api_oauth2_token_introspection_resource_server_client_ids';
     final public const string OPTION_API_TOKENS = 'api_tokens';
 
     /** Optional key naming an API token, so that an audit trail can say who made a change. */
@@ -2172,6 +2174,29 @@ public function getApiOAuth2TokenIntrospectionEndpointEnabled(): bool
         return $this->config()->getOptionalBoolean(self::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_ENDPOINT_ENABLED, false);
     }
 
+    /**
+     * Clients allowed to introspect tokens issued to any client, and not only to themselves.
+     *
+     * Introspection is a protected resource's capability, and which resource servers a deployment has
+     * is something only that deployment knows, so it is named here instead of being a property of a
+     * client registration: were it registered metadata, a client could grant itself the ability to read
+     * every other party's tokens by asking for it during Dynamic Client Registration.
+     *
+     * @return list<string>
+     * @throws \Exception
+     */
+    public function getApiOAuth2TokenIntrospectionResourceServerClientIds(): array
+    {
+        $clientIds = $this->config()->getOptionalArray(
+            self::OPTION_API_OAUTH2_TOKEN_INTROSPECTION_RESOURCE_SERVER_CLIENT_IDS,
+            [],
+        );
+
+        return array_values(
+            array_filter($clientIds, static fn(mixed $clientId): bool => is_string($clientId) && $clientId !== ''),
+        );
+    }
+
     /**
      * @return mixed[]|null
      */