(backend) add application model with secure secret handling

We need to integrate with external applications. Objective: enable them to
securely generate room links with proper ownership attribution.

Proposed solution: Following the OAuth2 Machine-to-Machine specification,
we expose an endpoint allowing external applications to exchange a client_id
and client_secret pair for a JWT. This JWT is valid only within a well-scoped,
isolated external API, served through a dedicated viewset.

This commit introduces a model to persist application records in the database.
The main challenge lies in generating a secure client_secret and ensuring
it is properly stored.

The restframework-apikey dependency was discarded, as its approach diverges
significantly from OAuth2. Instead, inspiration was taken from oauthlib and
django-oauth-toolkit. However, their implementations proved either too heavy or
not entirely suitable for the intended use case. To avoid pulling in large
dependencies for minimal utility, the necessary components were selectively
copied, adapted, and improved.

A generic SecretField was introduced, designed for reuse and potentially
suitable for upstream contribution to Django.

Secrets are exposed only once at object creation time in the Django admin.
Once the object is saved, the secret is immediately hashed, ensuring it can
never be retrieved again.

One limitation remains: enforcing client_id and client_secret as read-only
during edits. At object creation, marking them read-only excluded them from
the Django form, which unintentionally regenerated new values.
This area requires further refinement.

The design prioritizes configurability while adhering to the principle of least
privilege. By default, new applications are created without any assigned scopes,
preventing them from performing actions on the API until explicitly configured.

If no domain is specified, domain delegation is not applied, allowing tokens
to be issued for any email domain.
This commit is contained in:
lebaudantoine
2025-10-02 23:12:42 +02:00
committed by aleb_the_flash
parent c07b8f920f
commit 3fd5a4404c
8 changed files with 680 additions and 1 deletions
+101
View File
@@ -11,6 +11,7 @@ from typing import List, Optional
from django.conf import settings
from django.contrib.auth import models as auth_models
from django.contrib.auth.base_user import AbstractBaseUser
from django.contrib.postgres.fields import ArrayField
from django.core import mail, validators
from django.core.exceptions import PermissionDenied, ValidationError
from django.db import models
@@ -18,8 +19,10 @@ from django.utils import timezone
from django.utils.text import capfirst, slugify
from django.utils.translation import gettext_lazy as _
from lasuite.tools.email import get_domain_from_email
from timezone_field import TimeZoneField
from . import fields, utils
from .recording.enums import FileExtension
logger = getLogger(__name__)
@@ -717,3 +720,101 @@ class RecordingAccess(BaseAccess):
Compute and return abilities for a given user on the recording access.
"""
return self._get_abilities(self.recording, user)
class ApplicationScope(models.TextChoices):
"""Available permission scopes for application operations."""
ROOMS_CREATE = "rooms:create", _("Create rooms")
ROOMS_LIST = "rooms:list", _("List rooms")
ROOMS_RETRIEVE = "rooms:retrieve", _("Retrieve room details")
ROOMS_UPDATE = "rooms:update", _("Update rooms")
ROOMS_DELETE = "rooms:delete", _("Delete rooms")
class Application(BaseModel):
"""External application for API authentication and authorization.
Represents a third-party integration or automated system that accesses
the API using OAuth2-style client credentials (client_id/client_secret).
Supports scoped permissions and optional domain restrictions for delegation.
"""
name = models.CharField(
max_length=255,
verbose_name=_("Application name"),
help_text=_("Descriptive name for this application."),
)
active = models.BooleanField(default=True)
client_id = models.CharField(
max_length=100, unique=True, default=utils.generate_client_id
)
client_secret = fields.SecretField(
max_length=255,
blank=True,
default=utils.generate_client_secret,
help_text=_("Hashed on Save. Copy it now if this is a new secret."),
)
scopes = ArrayField(
models.CharField(max_length=50, choices=ApplicationScope.choices),
default=list,
blank=True,
)
class Meta:
db_table = "meet_application"
ordering = ("-created_at",)
verbose_name = _("Application")
verbose_name_plural = _("Applications")
def __str__(self):
return f"{self.name!s}"
def can_delegate_email(self, email):
"""Check if this application can delegate the given email."""
if not self.allowed_domains.exists():
return True # No domain restrictions
domain = get_domain_from_email(email)
return self.allowed_domains.filter(domain__iexact=domain).exists()
class ApplicationDomain(BaseModel):
"""Domain authorized for application delegation."""
domain = models.CharField(
max_length=253, # Max domain length per RFC 1035
validators=[
validators.DomainNameValidator(
accept_idna=False,
message=_("Enter a valid domain"),
)
],
verbose_name=_("Domain"),
help_text=_("Email domain this application can act on behalf of."),
)
application = models.ForeignKey(
"Application",
on_delete=models.CASCADE,
related_name="allowed_domains",
)
class Meta:
db_table = "meet_application_domain"
ordering = ("domain",)
verbose_name = _("Application domain")
verbose_name_plural = _("Application domains")
unique_together = [("application", "domain")]
def __str__(self):
"""Return string representation of the domain."""
return self.domain
def save(self, *args, **kwargs):
"""Save the domain after normalizing to lowercase."""
self.domain = self.domain.lower().strip()
super().save(*args, **kwargs)