✨(backend) complete admin maildomain api

- Create user (if needed) and mailbox access on mailbox creation
- If identify provider is keycloak, generate a one time password
at mailbox creation
- At nested endpoint to search users related to a maildomain

Co-authored-by: Sylvain Zimmer <[email protected]>

Author: jbpenrath

src/backend/core/api/openapi.json

@@ -4827,4 +4827,4 @@
             }
         }
     }
-}
+}

src/backend/core/api/serializers.py

@@ -547,6 +547,27 @@ class Meta:
         read_only_fields = fields
 
 
+class MailboxAdminCreateSerializer(MailboxAdminSerializer):
+    """
+    Serialize Mailbox details for create admin endpoint, including users with access and
+    metadata.
+    """
+
+    one_time_password = serializers.SerializerMethodField(
+        read_only=True, required=False
+    )
+
+    def get_one_time_password(self, instance) -> str | None:
+        """
+        Fake method just to make the OpenAPI schema valid.
+        """
+
+    class Meta:
+        model = models.Mailbox
+        fields = MailboxAdminSerializer.Meta.fields + ["one_time_password"]
+        read_only_fields = fields
+
+
 class ImportBaseSerializer(serializers.Serializer):
     """Base serializer for import actions that disables create and update."""
 

src/backend/core/api/viewsets/maildomain.py

@@ -1,17 +1,35 @@
 """Admin ViewSets for MailDomain and Mailbox management."""
 
+from django.conf import settings
+from django.db.models import Q
 from django.shortcuts import get_object_or_404
 from django.utils.translation import gettext_lazy as _  # For user-facing error messages
 
-from rest_framework import mixins, status, viewsets
+from drf_spectacular.utils import (
+    OpenApiParameter,
+    OpenApiResponse,
+    OpenApiTypes,
+    extend_schema,
+    inline_serializer,
+)
+from rest_framework import (
+    mixins,
+    response,
+    status,
+    viewsets,
+)
+from rest_framework import (
+    serializers as drf_serializers,
+)
 from rest_framework.response import Response
 
 from core import models
 from core.api import permissions as core_permissions
 from core.api import serializers as core_serializers
+from core.identity.keycloak import reset_keycloak_user_password
 
 
-class MailDomainAdminViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
+class AdminMailDomainViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
     """
     ViewSet for listing MailDomains the user administers.
     Provides a top-level entry for mail domain administration.
@@ -29,16 +47,12 @@ def get_queryset(self):
         if user.is_superuser and user.is_staff:
             return models.MailDomain.objects.all().order_by("name")
 
-        accessible_maildomain_ids = models.MailDomainAccess.objects.filter(
-            user=user, role=models.MailDomainAccessRoleChoices.ADMIN
-        ).values_list("maildomain_id", flat=True)
-
         return models.MailDomain.objects.filter(
-            id__in=list(accessible_maildomain_ids)
+            accesses__user=user, accesses__role=models.MailDomainAccessRoleChoices.ADMIN
         ).order_by("name")
 
 
-class MailboxAdminViewSet(
+class AdminMailDomainMailboxViewSet(
     mixins.CreateModelMixin,
     mixins.RetrieveModelMixin,
     mixins.UpdateModelMixin,
@@ -68,10 +82,45 @@ def get_queryset(self):
             "local_part"
         )
 
+    @extend_schema(
+        description="Create new mailbox in a specific maildomain.",
+        request=inline_serializer(
+            name="MailboxAdminCreatePayload",
+            fields={
+                "local_part": drf_serializers.CharField(required=True),
+                "alias_of": drf_serializers.UUIDField(required=False),
+                "metadata": inline_serializer(
+                    name="MailboxAdminCreateMetadata",
+                    fields={
+                        "type": drf_serializers.ChoiceField(
+                            choices=("personal", "shared", "redirect"), required=True
+                        ),
+                        "first_name": drf_serializers.CharField(
+                            required=False, allow_blank=True
+                        ),
+                        "last_name": drf_serializers.CharField(
+                            required=False, allow_blank=True
+                        ),
+                    },
+                ),
+            },
+        ),
+        responses={
+            200: OpenApiResponse(
+                response=core_serializers.MailboxAdminCreateSerializer(),
+                description=(
+                    "The new mailbox with one extra field `one_time_password` "
+                    "if identity provider is keycloak."
+                ),
+            ),
+        },
+    )
     def create(self, request, *args, **kwargs):
         maildomain_pk = self.kwargs.get("maildomain_pk")
         domain = get_object_or_404(models.MailDomain, pk=maildomain_pk)
+        metadata = request.data.get("metadata", {})
 
+        mailbox_type = metadata.get("type")
         local_part = request.data.get("local_part")
         alias_of_id = request.data.get("alias_of")
 
@@ -124,8 +173,90 @@ def create(self, request, *args, **kwargs):
             domain=domain, local_part=local_part, alias_of=alias_of
         )
 
+        # --- Create user and mailbox access if type is personal ---
+        if mailbox_type == "personal":
+            email = f"{local_part}@{domain.name}"
+            first_name = metadata.get("first_name")
+            last_name = metadata.get("last_name")
+            user, _created = models.User.objects.get_or_create(
+                email=email,
+                defaults={
+                    "full_name": f"{first_name} {last_name}",
+                    "short_name": first_name,
+                    "password": "?",
+                },
+            )
+            models.MailboxAccess.objects.create(
+                mailbox=mailbox,
+                user=user,
+                role=models.MailboxRoleChoices.ADMIN,
+            )
+
         serializer = self.get_serializer(mailbox)
         headers = self.get_success_headers(serializer.data)
-        return Response(
-            serializer.data, status=status.HTTP_201_CREATED, headers=headers
+        payload = serializer.data
+        if mailbox_type == "personal" and settings.IDENTITY_PROVIDER == "keycloak":
+            mailbox_password = reset_keycloak_user_password(email)
+            payload["one_time_password"] = mailbox_password
+        return Response(payload, status=status.HTTP_201_CREATED, headers=headers)
+
+
+class AdminMailDomainUserViewSet(mixins.ListModelMixin, viewsets.GenericViewSet):
+    """
+    ViewSet for listing users in a specific MailDomain.
+    Nested under /maildomains/{maildomain_pk}/users/
+    Permissions are checked by IsMailDomainAdmin for the maildomain_pk.
+    """
+
+    permission_classes = [
+        core_permissions.IsAuthenticated,
+        core_permissions.IsMailDomainAdmin,
+    ]
+    serializer_class = core_serializers.UserSerializer
+    pagination_class = None
+
+    def get_queryset(self):
+        """
+        Get all users having an access to a mailbox or an admin access to the maildomain.
+        """
+        maildomain_pk = self.kwargs.get("maildomain_pk")
+        # Get all users with an email ending with maildomain.name or with an admin access to the maildomain
+        return (
+            models.User.objects.filter(
+                Q(mailbox_accesses__mailbox__domain_id=maildomain_pk)
+                | Q(
+                    maildomain_accesses__maildomain_id=maildomain_pk,
+                    maildomain_accesses__role=models.MailDomainAccessRoleChoices.ADMIN,
+                )
+            )
+            .distinct()
+            .order_by("full_name", "short_name", "email")
         )
+
+    @extend_schema(
+        tags=["admin-maildomain-user"],
+        parameters=[
+            OpenApiParameter(
+                name="q",
+                type=OpenApiTypes.STR,
+                location=OpenApiParameter.QUERY,
+                description="Search maildomains user by full name, short name or email.",
+            ),
+        ],
+        responses=core_serializers.UserSerializer(many=True),
+    )
+    def list(self, request, *args, **kwargs):
+        """
+        Search users by email, first name and last name.
+        """
+        queryset = self.get_queryset()
+
+        if query := request.query_params.get("q", ""):
+            queryset = queryset.filter(
+                Q(email__unaccent__icontains=query)
+                | Q(full_name__unaccent__icontains=query)
+                | Q(short_name__unaccent__icontains=query)
+            )
+
+        serializer = core_serializers.UserSerializer(queryset, many=True)
+        return response.Response(serializer.data)