✨(backend) add delegation mechanism to external app /token endpoint

This endpoint does not strictly follow the OAuth2 Machine-to-Machine
specification, as we introduce the concept of user delegation (instead of
using the term impersonation).

Typically, OAuth2 M2M is used only to authenticate a machine in server-to-server
exchanges. In our case, we require external applications to act on behalf of a
user in order to assign room ownership and access.

Since these external applications are not integrated with our authorization
server, a workaround was necessary. We treat the delegated user’s email as a
form of scope and issue a JWT to the application if it is authorized to request
it.

Using the term scope for an email may be confusing, but it remains consistent
with OAuth2 vocabulary and allows for future extension, such as supporting a
proper M2M process without any user delegation.

It is important not to confuse the scope in the request body with the scope in
the generated JWT. The request scope refers to the delegated email, while the
JWT scope defines what actions the external application can perform on our
viewset, matching Django’s viewset method naming.

The viewset currently contains a significant amount of logic. I did not find
a clean way to split it without reducing maintainability, but this can be
reconsidered in the future.

Error messages are intentionally vague to avoid exposing sensitive
information to attackers.

src/backend/core/tests/test_external_api_token.py

@@ -0,0 +1,275 @@
+"""
+Tests for external API /token endpoint
+"""
+
+# pylint: disable=W0621
+
+import jwt
+import pytest
+from freezegun import freeze_time
+from rest_framework.test import APIClient
+
+from core.factories import (
+    ApplicationDomainFactory,
+    ApplicationFactory,
+    UserFactory,
+)
+from core.models import ApplicationScope
+
+pytestmark = pytest.mark.django_db
+
+
+def test_api_applications_generate_token_success(settings):
+    """Valid credentials should return a JWT token."""
+    settings.APPLICATION_JWT_SECRET_KEY = "devKey"
+    user = UserFactory(email="user@example.com")
+    application = ApplicationFactory(
+        active=True,
+        scopes=[ApplicationScope.ROOMS_LIST, ApplicationScope.ROOMS_CREATE],
+    )
+
+    # Store plain secret before it's hashed
+    plain_secret = "test-secret-123"
+    application.client_secret = plain_secret
+    application.save()
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": plain_secret,
+            "grant_type": "client_credentials",
+            "scope": user.email,
+        },
+        format="json",
+    )
+
+    assert response.status_code == 200
+    assert "access_token" in response.data
+
+    response.data.pop("access_token")
+
+    assert response.data == {
+        "token_type": "Bearer",
+        "expires_in": settings.APPLICATION_JWT_EXPIRATION_SECONDS,
+        "scope": "rooms:list rooms:create",
+    }
+
+
+def test_api_applications_generate_token_invalid_client_id():
+    """Invalid client_id should return 401."""
+    user = UserFactory(email="user@example.com")
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": "invalid-client-id",
+            "client_secret": "some-secret",
+            "grant_type": "client_credentials",
+            "scope": user.email,
+        },
+        format="json",
+    )
+
+    assert response.status_code == 401
+    assert "Invalid credentials" in str(response.data)
+
+
+def test_api_applications_generate_token_invalid_client_secret():
+    """Invalid client_secret should return 401."""
+    user = UserFactory(email="user@example.com")
+    application = ApplicationFactory(active=True)
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": "wrong-secret",
+            "grant_type": "client_credentials",
+            "scope": user.email,
+        },
+        format="json",
+    )
+
+    assert response.status_code == 401
+    assert "Invalid credentials" in str(response.data)
+
+
+def test_api_applications_generate_token_inactive_application():
+    """Inactive application should return 401."""
+    user = UserFactory(email="user@example.com")
+    application = ApplicationFactory(active=False)
+
+    plain_secret = "test-secret-123"
+    application.client_secret = plain_secret
+    application.save()
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": plain_secret,
+            "grant_type": "client_credentials",
+            "scope": user.email,
+        },
+        format="json",
+    )
+
+    assert response.status_code == 401
+    assert "Application is inactive" in str(response.data)
+
+
+def test_api_applications_generate_token_invalid_email_format():
+    """Invalid email format should return 400."""
+    application = ApplicationFactory(active=True)
+
+    plain_secret = "test-secret-123"
+    application.client_secret = plain_secret
+    application.save()
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": plain_secret,
+            "grant_type": "client_credentials",
+            "scope": "not-an-email",
+        },
+        format="json",
+    )
+
+    assert response.status_code == 400
+    assert "scope should be a valid email address." in str(response.data).lower()
+
+
+def test_api_applications_generate_token_domain_not_authorized():
+    """Application without domain authorization should return 403."""
+    user = UserFactory(email="user@denied.com")
+    application = ApplicationFactory(active=True)
+    ApplicationDomainFactory(application=application, domain="allowed.com")
+
+    plain_secret = "test-secret-123"
+    application.client_secret = plain_secret
+    application.save()
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": plain_secret,
+            "grant_type": "client_credentials",
+            "scope": user.email,
+        },
+        format="json",
+    )
+
+    assert response.status_code == 403
+    assert "not authorized for this email domain" in str(response.data)
+
+
+def test_api_applications_generate_token_domain_authorized(settings):
+    """Application with domain authorization should succeed."""
+    settings.APPLICATION_JWT_SECRET_KEY = "devKey"
+    user = UserFactory(email="user@allowed.com")
+    application = ApplicationFactory(
+        active=True,
+        scopes=[ApplicationScope.ROOMS_LIST],
+    )
+    ApplicationDomainFactory(application=application, domain="allowed.com")
+
+    plain_secret = "test-secret-123"
+    application.client_secret = plain_secret
+    application.save()
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": plain_secret,
+            "grant_type": "client_credentials",
+            "scope": user.email,
+        },
+        format="json",
+    )
+
+    assert response.status_code == 200
+    assert "access_token" in response.data
+
+
+def test_api_applications_generate_token_user_not_found():
+    """Non-existent user should return 404."""
+    application = ApplicationFactory(active=True)
+
+    plain_secret = "test-secret-123"
+    application.client_secret = plain_secret
+    application.save()
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": plain_secret,
+            "grant_type": "client_credentials",
+            "scope": "nonexistent@example.com",
+        },
+        format="json",
+    )
+
+    assert response.status_code == 404
+    assert "User not found" in str(response.data)
+
+
+@freeze_time("2023-01-15 12:00:00")
+def test_api_applications_token_payload_structure(settings):
+    """Generated token should have correct payload structure."""
+    settings.APPLICATION_JWT_SECRET_KEY = "devKey"
+    user = UserFactory(email="user@example.com")
+    application = ApplicationFactory(
+        active=True,
+        scopes=[ApplicationScope.ROOMS_LIST, ApplicationScope.ROOMS_CREATE],
+    )
+
+    plain_secret = "test-secret-123"
+    application.client_secret = plain_secret
+    application.save()
+
+    client = APIClient()
+    response = client.post(
+        "/external-api/v1.0/application/token/",
+        {
+            "client_id": application.client_id,
+            "client_secret": plain_secret,
+            "grant_type": "client_credentials",
+            "scope": user.email,
+        },
+        format="json",
+    )
+
+    # Decode token to verify payload
+    token = response.data["access_token"]
+    payload = jwt.decode(
+        token,
+        settings.APPLICATION_JWT_SECRET_KEY,
+        algorithms=[settings.APPLICATION_JWT_ALG],
+        issuer=settings.APPLICATION_JWT_ISSUER,
+        audience=settings.APPLICATION_JWT_AUDIENCE,
+    )
+
+    assert payload == {
+        "iss": settings.APPLICATION_JWT_ISSUER,
+        "aud": settings.APPLICATION_JWT_AUDIENCE,
+        "client_id": application.client_id,
+        "exp": 1673787600,
+        "iat": 1673784000,
+        "user_id": str(user.id),
+        "delegated": True,
+        "scope": "rooms:list rooms:create",
+    }