refactor(oauth): reorganize OAuth resource indicators and discovery handling, streamline validation processes, and enhance integration with MCP

Author: rboixaderg

docs/source/contrib/oauth.md

@@ -52,10 +52,13 @@
 
 
 def includeme(root, settings):
-    from guillotina.contrib.oauth.flow.resources import ensure_default_oauth_resources_registered
+    from guillotina.contrib.oauth.indicators.registry import ensure_default_resource_indicators_registered
 
-    ensure_default_oauth_resources_registered()
+    ensure_default_resource_indicators_registered()
     configure.scan("guillotina.contrib.oauth.install")
     configure.scan("guillotina.contrib.oauth.api.services")
     if "guillotina.contrib.mcp" in set(settings.get("applications") or []):
         configure.scan("guillotina.contrib.oauth.integrations.mcp")
+        from guillotina.contrib.oauth.integrations.mcp import register_mcp_oauth_integration
+
+        register_mcp_oauth_integration()

guillotina/contrib/oauth/__init__.py

@@ -12,9 +12,9 @@
 from guillotina.contrib.oauth.flow.consent import build_consent_key
 from guillotina.contrib.oauth.flow.csrf import OAUTH_CSRF_FIELD, csrf_valid
 from guillotina.contrib.oauth.flow.pkce import pkce_challenge_valid
-from guillotina.contrib.oauth.flow.resources import validate_resource
 from guillotina.contrib.oauth.flow.scopes import OAUTH_DEFAULT_SCOPE, oauth_scopes_supported
 from guillotina.contrib.oauth.flow.tokens import generate_opaque_token
+from guillotina.contrib.oauth.indicators.grant import validate_resource_indicator
 from guillotina.contrib.oauth.utils.ratelimit import rate_limit_check, rate_limit_exceeded
 from guillotina.contrib.oauth.utils.request import (
     normalize_list,
@@ -55,7 +55,7 @@ async def authorization_endpoint(service, store):
         return _authorization_redirect(redirect_uri, params, issuer, {"error": authorization_error})
 
     try:
-        resources = validate_resource(service.request, service.context, params.get("resource"))
+        resources = validate_resource_indicator(service.request, service.context, params.get("resource"))
     except HTTPBadRequest:
         return _authorization_redirect(redirect_uri, params, issuer, {"error": "invalid_target"})
 

guillotina/contrib/oauth/api/endpoints/authorize.py

@@ -1,3 +1,4 @@
+import guillotina.contrib.oauth.discovery  # noqa — triggers well-known handler registrations
 from guillotina import configure
 from guillotina.api.service import Service
 from guillotina.contrib.oauth.api.endpoints.authorize import authorization_endpoint
@@ -6,7 +7,7 @@
 from guillotina.contrib.oauth.api.endpoints.register import client_registration_endpoint
 from guillotina.contrib.oauth.api.endpoints.revoke import token_revocation_endpoint
 from guillotina.contrib.oauth.api.endpoints.token import token_endpoint
-from guillotina.contrib.oauth.api.well_known import WELL_KNOWN_HANDLERS, serve_well_known_metadata
+from guillotina.contrib.oauth.discovery.routing import WELL_KNOWN_HANDLERS, serve_well_known_metadata
 from guillotina.interfaces import IApplication, IContainer
 from guillotina.response import HTTPNotFound
 

guillotina/contrib/oauth/api/services.py

@@ -0,0 +1,13 @@
+"""Typed context for a validated OAuth access token attached to the request."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class OAuthTokenContext:
+    client_id: str
+    scopes: frozenset[str]
+    resource_indicators: frozenset[str]
+    claims: dict

guillotina/contrib/oauth/api/well_known.py

@@ -2,8 +2,9 @@
 
 from guillotina import app_settings, task_vars
 from guillotina.auth import find_user
-from guillotina.contrib.oauth.flow.resources import oauth_required_audience
+from guillotina.contrib.oauth.auth.context import OAuthTokenContext
 from guillotina.contrib.oauth.flow.scopes import OAUTH_DEFAULT_SCOPE
+from guillotina.contrib.oauth.indicators.access import required_resource_indicator
 from guillotina.contrib.oauth.utils.crypto import access_token_signing_key
 from guillotina.contrib.oauth.utils.urls import container_issuer_url
 
@@ -35,7 +36,7 @@ async def validate(self, token):
             if claims.get("iss") != issuer:
                 return
             aud = set(claims.get("aud") or [])
-            if oauth_required_audience(request, container) not in aud:
+            if required_resource_indicator(request, container) not in aud:
                 return
         if not claims.get("client_id"):
             return
@@ -45,12 +46,11 @@ async def validate(self, token):
         token["id"] = claims.get("id", claims.get("sub"))
         token["decoded"] = claims
         user = await find_user(token)
-        if user is not None and user.id == token["id"]:
-            if request is not None:
-                request.oauth = {
-                    "client_id": claims.get("client_id"),
-                    "scopes": scopes,
-                    "resources": set(claims.get("aud") or []),
-                    "claims": claims,
-                }
-            return user
+        if user is not None and user.id == token["id"] and request is not None:
+            request.oauth = OAuthTokenContext(
+                client_id=claims.get("client_id"),
+                scopes=frozenset(scopes),
+                resource_indicators=frozenset(claims.get("aud") or []),
+                claims=claims,
+            )
+        return user

guillotina/contrib/oauth/auth/context.py

@@ -0,0 +1,4 @@
+"""Discovery package — triggers registration of well-known handlers on import."""
+
+from guillotina.contrib.oauth.discovery import authorization_server as _as  # noqa
+from guillotina.contrib.oauth.discovery import protected_resource as _pr  # noqa

guillotina/contrib/oauth/auth/validators.py

@@ -0,0 +1,27 @@
+"""OAuth 2.0 Authorization Server Metadata (RFC 8414)."""
+
+from guillotina.contrib.oauth.discovery.routing import register_well_known_handler
+from guillotina.contrib.oauth.flow.scopes import oauth_scopes_supported
+from guillotina.contrib.oauth.utils.urls import container_issuer_url
+
+
+def _authorization_server_metadata(request, container):
+    issuer = container_issuer_url(request, container)
+    return {
+        "issuer": issuer,
+        "authorization_endpoint": f"{issuer}/oauth/authorize",
+        "token_endpoint": f"{issuer}/oauth/token",
+        "registration_endpoint": f"{issuer}/oauth/register",
+        "revocation_endpoint": f"{issuer}/oauth/revoke",
+        "response_types_supported": ["code"],
+        "grant_types_supported": ["authorization_code", "refresh_token"],
+        "code_challenge_methods_supported": ["S256"],
+        "token_endpoint_auth_methods_supported": ["none"],
+        "revocation_endpoint_auth_methods_supported": ["none"],
+        "resource_indicators_supported": True,
+        "authorization_response_iss_parameter_supported": True,
+        "scopes_supported": oauth_scopes_supported(),
+    }
+
+
+register_well_known_handler("oauth-authorization-server", _authorization_server_metadata)

guillotina/contrib/oauth/discovery/__init__.py

@@ -0,0 +1,27 @@
+"""OAuth 2.0 Protected Resource Metadata (RFC 9728)."""
+
+from guillotina.contrib.oauth.discovery.routing import register_well_known_handler
+from guillotina.response import HTTPNotFound
+
+
+_PROTECTED_RESOURCE_PROVIDERS = []
+
+
+def register_protected_resource_provider(provider):
+    _PROTECTED_RESOURCE_PROVIDERS.append(provider)
+
+
+def reset_protected_resource_providers() -> None:
+    _PROTECTED_RESOURCE_PROVIDERS.clear()
+
+
+def _protected_resource_metadata(request, container):
+    protected_path = getattr(request, "oauth_protected_resource_path", None)
+    for provider in _PROTECTED_RESOURCE_PROVIDERS:
+        metadata = provider(request, container, protected_path)
+        if metadata is not None:
+            return metadata
+    raise HTTPNotFound(content={"reason": "Unknown protected resource"})
+
+
+register_well_known_handler("oauth-protected-resource", _protected_resource_metadata)