feat: add RFC 8707 Resource Indicators support

Fixes #1102

Implement RFC 8707 to bind access tokens to specific resource servers:
- Add resource field to Grant and AccessToken models (migrations
  included)
- Accept & validate resource parameter in authorization/token requests
- token view: reject unauthorized resources with `invalid_target` error

This change is backward compatible - clients not providing a `resource`
in the request will receive a token providing unrestricted access, as
before.

Author: craigds

CHANGELOG.md

@@ -10,6 +10,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Support for Django 5.2
 * Support for Python 3.14 (Django >= 5.2.8)
 * #1539 Add device authorization grant support
+* RFC 8707 "Resource Indicators" support
+  - clients can optionally specify `resource` parameter during authorization or access token requests
+  - Resource binding stored in Grant and AccessToken models
+  - Token introspection endpoint returns `aud` claim for tokens with resource indicators
 
 
 <!--

docs/getting_started.rst

@@ -302,6 +302,17 @@ Note the parameters we pass:
 
 This identifies your application, the user is asked to authorize your application to access its resources.
 
+.. note::
+   **Optional: Binding Tokens to Specific Resources**
+
+   You can add a ``resource`` parameter to bind the access token to a specific API endpoint,
+   following `RFC 8707 <https://rfc-editor.org/rfc/rfc8707.html>`_::
+
+       &resource=https://api.example.com
+
+   This prevents the token from being used at other resource servers.
+   See :doc:`resource_server` for details on validating token audiences.
+
 Go ahead and authorize the ``web-app``
 
 .. image:: _images/application-authorize-web-app.png

docs/resource_server.rst

@@ -44,9 +44,13 @@ Example Response::
       "client_id": "oUdofn7rfhRtKWbmhyVk",
       "username": "jdoe",
       "scope": "read write dolphin",
-      "exp": 1419356238
+      "exp": 1419356238,
+      "aud": ["https://api.example.com", "https://data.example.com"]
     }
 
+The ``aud`` field (audience) is included when the token has resource binding per RFC 8707.
+Tokens without resource restrictions will not include this field.
+
 Setup the Resource Server
 -------------------------
 Setup the :term:`Resource Server` like the :term:`Authorization Server` as described in the :doc:`tutorial/tutorial`.
@@ -71,3 +75,73 @@ As allowed by RFC 7662, some external OAuth 2.0 servers support HTTP Basic Authe
 For these, use:
 ``RESOURCE_SERVER_INTROSPECTION_CREDENTIALS=('client_id','client_secret')`` instead
 of ``RESOURCE_SERVER_AUTH_TOKEN``.
+
+
+Token Audience Binding (RFC 8707)
+==================================
+Django OAuth Toolkit supports `RFC 8707 <https://rfc-editor.org/rfc/rfc8707.html>`_ Resource Indicators,
+which allows clients to bind access tokens to specific resource servers. This prevents tokens from being
+misused at unintended services.
+
+How It Works
+------------
+Clients include a ``resource`` parameter in authorization and token requests to specify which
+resource servers they want to access:
+
+.. code-block:: http
+
+    GET /o/authorize/?client_id=CLIENT_ID
+        &response_type=code
+        &redirect_uri=https://client.example.com/callback
+        &scope=read
+        &resource=https://api.example.com
+
+The issued access token will be bound to ``https://api.example.com`` and should only be accepted
+by that resource server.
+
+Validating Token Audiences
+---------------------------
+Resource servers should validate that tokens are intended for them using the ``allows_audience()`` method:
+
+.. code-block:: python
+
+    from oauth2_provider.models import AccessToken
+
+    def validate_request(request):
+        """Validate that the token is intended for this resource server."""
+        token_string = request.META.get('HTTP_AUTHORIZATION', '').split(' ')[-1]
+
+        try:
+            token = AccessToken.objects.get(token=token_string)
+
+            # Check token is not expired
+            if token.is_expired():
+                return False
+
+            # Check token audience (RFC 8707)
+            if not token.allows_audience('https://api.example.com'):
+                return False
+
+            return True
+        except AccessToken.DoesNotExist:
+            return False
+
+The ``allows_audience()`` method checks if the token's resource field includes the specified URI.
+Tokens without resource restrictions (legacy tokens) will allow any audience for backward compatibility.
+
+You can also retrieve all audiences for a token:
+
+.. code-block:: python
+
+    audiences = token.get_audiences()  # Returns list of resource URIs
+
+Security Benefits
+-----------------
+RFC 8707 support provides important security benefits:
+
+* **Prevents privilege escalation**: Tokens can only be used at authorized resource servers
+* **Defense in depth**: Even if a token is stolen, it cannot be used at unintended services
+* **Explicit authorization**: Users see which specific resources will be accessed
+
+The authorization server validates that token requests only specify resources from the original
+authorization, rejecting attempts to escalate privileges with an ``invalid_target`` error.

oauth2_provider/forms.py

@@ -12,6 +12,7 @@ class AllowForm(forms.Form):
     code_challenge = forms.CharField(required=False, widget=forms.HiddenInput())
     code_challenge_method = forms.CharField(required=False, widget=forms.HiddenInput())
     claims = forms.CharField(required=False, widget=forms.HiddenInput())
+    resource = forms.CharField(required=False, widget=forms.HiddenInput())  # RFC 8707
 
 
 class ConfirmLogoutForm(forms.Form):

oauth2_provider/migrations/0014_grant_resource.py

@@ -0,0 +1,17 @@
+# Generated by Django 5.2.9 on 2025-12-02 22:20
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oauth2_provider", "0013_alter_application_authorization_grant_type_device"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="grant",
+            name="resource",
+            field=models.TextField(blank=True, default=""),
+        ),
+    ]

oauth2_provider/migrations/0015_accesstoken_resource.py

@@ -0,0 +1,17 @@
+# Generated by Django 5.2.9 on 2025-12-02 22:28
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("oauth2_provider", "0014_grant_resource"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="accesstoken",
+            name="resource",
+            field=models.TextField(blank=True, default=""),
+        ),
+    ]

oauth2_provider/models.py

@@ -1,4 +1,5 @@
 import hashlib
+import json
 import logging
 import time
 import uuid
@@ -320,6 +321,7 @@ class AbstractGrant(models.Model):
     * :attr:`scope` Required scopes, optional
     * :attr:`code_challenge` PKCE code challenge
     * :attr:`code_challenge_method` PKCE code challenge transform algorithm
+    * :attr:`resource` RFC 8707 resource indicator(s), JSON-encoded array of URIs
     """
 
     CODE_CHALLENGE_PLAIN = "plain"
@@ -347,6 +349,9 @@ class AbstractGrant(models.Model):
     nonce = models.CharField(max_length=255, blank=True, default="")
     claims = models.TextField(blank=True)
 
+    # RFC 8707: Resource Indicators - JSON-encoded array of resource URIs
+    resource = models.TextField(blank=True, default="")
+
     def is_expired(self):
         """
         Check token expiration with timezone awareness
@@ -384,6 +389,7 @@ class AbstractAccessToken(models.Model):
     * :attr:`application` Application instance
     * :attr:`expires` Date and time of token expiration, in DateTime format
     * :attr:`scope` Allowed scopes
+    * :attr:`resource` RFC 8707 resource indicator(s) - JSON-encoded array of URIs
     """
 
     id = models.BigAutoField(primary_key=True)
@@ -422,9 +428,13 @@ class AbstractAccessToken(models.Model):
         blank=True,
         null=True,
     )
+
     expires = models.DateTimeField()
     scope = models.TextField(blank=True)
 
+    # RFC 8707: Resource Indicators - JSON-encoded array of resource URIs
+    resource = models.TextField(blank=True, default="")
+
     created = models.DateTimeField(auto_now_add=True)
     updated = models.DateTimeField(auto_now=True)
 
@@ -445,6 +455,43 @@ def is_expired(self):
 
         return timezone.now() >= self.expires
 
+    def get_audiences(self):
+        """
+        Get list of audience URIs from the resource field.
+
+        RFC 8707: Returns the resource indicators as a list of URIs.
+        The resource field is stored as a JSON-encoded array.
+
+        :return: List of audience URI strings. Empty list means the token is not
+                 restricted to specific resource servers (unrestricted access).
+        """
+        if not self.resource:
+            return []
+
+        try:
+            return json.loads(self.resource)
+        except (json.JSONDecodeError, TypeError):
+            return []
+
+    def allows_audience(self, audience_uri):
+        """
+        Check if the token is authorized for the given audience URI.
+
+        RFC 8707: Validates that the token includes the specified resource indicator.
+        If the token has no resource indicators (empty list), it is unrestricted and
+        allows any audience (backward compatibility).
+
+        :param audience_uri: The URI of the resource server to check
+        :return: True if the token is authorized for this audience, False otherwise
+        """
+        audiences = self.get_audiences()
+
+        # Empty list means unrestricted access (backward compatibility)
+        if not audiences:
+            return True
+
+        return audience_uri in audiences
+
     def allow_scopes(self, scopes):
         """
         Check if the token allows the provided scopes

oauth2_provider/oauth2_validators.py

@@ -217,13 +217,16 @@ def _load_application(self, client_id, request):
         if request.client:
             # check for cached client, to save the db hit if this has already been loaded
             if not isinstance(request.client, Application):
-                # resetting request.client (client_id=%r): not an Application, something else set request.client erroneously
+                # resetting request.client (client_id=%r): not an Application, something else set
+                # request.client erroneously
                 request.client = None
             elif request.client.client_id != client_id:
-                # resetting request.client (client_id=%r): request.client.client_id does not match the given client_id
+                # resetting request.client (client_id=%r): request.client.client_id does not match
+                # the given client_id
                 request.client = None
             elif not request.client.is_usable(request):
-                # resetting request.client (client_id=%r): request.client is a valid Application, but is not usable
+                # resetting request.client (client_id=%r): request.client is a valid Application,
+                # but is not usable
                 request.client = None
             else:
                 # request.client is a valid Application, reusing it
@@ -614,6 +617,81 @@ def _save_bearer_token(self, token, request, *args, **kwargs):
         if "scope" not in token:
             raise FatalClientError("Failed to renew access token: missing scope")
 
+        # RFC 8707: Extract resource parameter from request
+        # For authorization_code grant, resource comes from the grant (already JSON-encoded)
+        # but can be narrowed by the token request
+        # For other grants, it comes from the request directly and needs encoding
+        if request.grant_type == "authorization_code":
+            # Get resource from the grant that was validated
+            grant = Grant.objects.filter(code=request.code, application=request.client).first()
+            grant_resource = grant.resource if (grant and grant.resource) else ""
+
+            # Check if token request specifies a subset of resources
+            requested_resource = getattr(request, "resource", None)
+            if requested_resource:
+                # RFC 8707: Token request is narrowing the resource scope
+                # Validate that requested resources are a subset of granted resources
+                if isinstance(requested_resource, str):
+                    requested_list = [requested_resource]
+                else:
+                    requested_list = requested_resource
+
+                # Parse granted resources
+                if grant_resource:
+                    try:
+                        granted_list = json.loads(grant_resource)
+                    except (json.JSONDecodeError, TypeError):
+                        granted_list = []
+                else:
+                    granted_list = []
+
+                # Validate that all requested resources were granted
+                if granted_list:  # Only validate if resources were originally granted
+                    for res in requested_list:
+                        if res not in granted_list:
+                            # RFC 8707: Use invalid_target error per spec
+                            raise errors.CustomOAuth2Error(
+                                error="invalid_target",
+                                description=(
+                                    f"Requested resource '{res}' was not included in the "
+                                    "original authorization grant"
+                                ),
+                                request=request,
+                            )
+
+                request.resource = json.dumps(requested_list)
+            elif grant_resource:
+                # Use all resources from the grant
+                request.resource = grant_resource
+            else:
+                request.resource = ""
+        else:
+            # For other grant types (client_credentials, password, implicit, etc.)
+            # Extract resource from request and JSON-encode it if needed
+            resource = getattr(request, "resource", None)
+            if resource:
+                # Check if already JSON-encoded (from authorization endpoint)
+                # vs raw from token endpoint
+                if isinstance(resource, str):
+                    # Could be either a single URI or already JSON-encoded
+                    try:
+                        # Try to parse as JSON
+                        parsed = json.loads(resource)
+                        if isinstance(parsed, list):
+                            # Already JSON-encoded, use as-is
+                            request.resource = resource
+                        else:
+                            # Single URI, needs encoding
+                            request.resource = json.dumps([resource])
+                    except (json.JSONDecodeError, TypeError):
+                        # Not JSON, it's a single URI
+                        request.resource = json.dumps([resource])
+                else:
+                    # It's a list, encode it
+                    request.resource = json.dumps(resource)
+            else:
+                request.resource = ""
+
         # expires_in is passed to Server on initialization
         # custom server class can have logic to override this
         expires = timezone.now() + timedelta(
@@ -717,11 +795,22 @@ def _create_access_token(self, expires, request, token, source_refresh_token=Non
             id_token=id_token,
             application=request.client,
             source_refresh_token=source_refresh_token,
+            resource=getattr(request, "resource", ""),  # RFC 8707
         )
 
     def _create_authorization_code(self, request, code, expires=None):
         if not expires:
             expires = timezone.now() + timedelta(seconds=oauth2_settings.AUTHORIZATION_CODE_EXPIRE_SECONDS)
+
+        # RFC 8707: Extract resource parameter
+        # The resource parameter is already JSON-encoded from the view
+        resource = getattr(request, "resource", None)
+        if resource:
+            # Resource is already JSON-encoded from the view, just use it
+            resource_json = resource
+        else:
+            resource_json = ""
+
         return Grant.objects.create(
             application=request.client,
             user=request.user,
@@ -733,6 +822,7 @@ def _create_authorization_code(self, request, code, expires=None):
             code_challenge_method=request.code_challenge_method or "",
             nonce=request.nonce or "",
             claims=json.dumps(request.claims or {}),
+            resource=resource_json,
         )
 
     def _create_refresh_token(self, request, refresh_token_code, access_token, previous_refresh_token):