feat: add groups management API

- GET /auth/groups - list groups with search/pagination
- POST /auth/groups/sync-from-authentik - bulk sync from Authentik
- Group model and database migration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/auth/controller.py

@@ -11,7 +11,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from src.controllers.base import BaseController
 from src.logging_config import get_logger
 from src.db import get_async_session
-from src.auth.schemas import AuthSyncRequest, AuthSyncResponse, UsersListResponse, BulkSyncResultSchema
+from src.auth.schemas import AuthSyncRequest, AuthSyncResponse, UsersListResponse, BulkSyncResultSchema, GroupsListResponse
 from src.auth.service import AuthService
 
 logger = get_logger(__name__)
@@ -152,6 +152,69 @@ class AuthController(BaseController):
                 logger.error(f"Bulk sync failed: {e}")
                 raise HTTPException(status_code=401, detail=str(e))
 
+        @router.get(
+            "/groups",
+            summary="List all groups",
+            response_model=GroupsListResponse,
+            responses={
+                200: {"description": "List of groups"},
+            },
+        )
+        async def list_groups(
+            search: Optional[str] = Query(None, description="Search by group name"),
+            offset: int = Query(0, ge=0, description="Number of records to skip"),
+            limit: int = Query(50, ge=1, le=100, description="Maximum records to return"),
+            session: AsyncSession = Depends(get_async_session),
+        ) -> GroupsListResponse:
+            """
+            List all groups synced from Authentik
+
+            Returns paginated list of groups with their details.
+            Supports search filtering by name.
+            """
+            service = AuthService(session)
+            items, total = await service.list_groups(
+                search=search,
+                offset=offset,
+                limit=limit,
+            )
+            return GroupsListResponse(items=items, total=total)
+
+        @router.post(
+            "/groups/sync-from-authentik",
+            summary="Bulk sync groups from Authentik",
+            response_model=BulkSyncResultSchema,
+            responses={
+                200: {"description": "Sync completed"},
+                401: {"description": "Authentik API credentials invalid"},
+                503: {"description": "Authentik service unavailable"},
+            },
+        )
+        async def sync_groups_from_authentik(
+            session: AsyncSession = Depends(get_async_session),
+        ) -> BulkSyncResultSchema:
+            """
+            Fetch all groups from Authentik and sync to local database
+
+            This endpoint uses the Authentik admin API to fetch all groups
+            and create/update them in the local database. Requires
+            AUTHENTIK_USERNAME and AUTHENTIK_PASSWORD to be configured.
+
+            Use this to populate groups or to re-sync after changes in Authentik.
+            """
+            service = AuthService(session)
+
+            try:
+                result = await service.bulk_sync_groups_from_authentik()
+                logger.info(
+                    f"Groups bulk sync completed: {result.created} created, "
+                    f"{result.updated} updated, {result.failed} failed"
+                )
+                return result
+            except ValueError as e:
+                logger.error(f"Groups bulk sync failed: {e}")
+                raise HTTPException(status_code=401, detail=str(e))
+
         @router.get(
             "/me",
             summary="Get current user profile",

src/auth/schemas.py

@@ -108,3 +108,22 @@ class BulkSyncResultSchema(BaseSchema):
     failed: int = Field(..., description="Number of users that failed to sync")
     total_in_authentik: int = Field(..., description="Total users in Authentik")
     errors: list[str] = Field(default_factory=list, description="Error messages for failed syncs")
+
+
+class GroupListItemSchema(BaseSchema):
+    """Group item for list display"""
+
+    id: uuid.UUID = Field(..., description="Internal group ID")
+    authentik_id: uuid.UUID = Field(..., description="Authentik group ID")
+    name: str = Field(..., description="Group name")
+    is_superuser: bool = Field(default=False, description="Whether group has superuser privileges")
+    parent_name: Optional[str] = Field(None, description="Parent group name")
+    member_count: int = Field(default=0, description="Number of users in this group")
+    synced_at: datetime = Field(..., description="Last sync timestamp")
+
+
+class GroupsListResponse(BaseSchema):
+    """Response from GET /auth/groups"""
+
+    items: list[GroupListItemSchema] = Field(..., description="List of groups")
+    total: int = Field(..., description="Total count of groups")

src/auth/service.py

@@ -15,8 +15,8 @@ from sqlalchemy.orm import selectinload
 
 from src.config import get_settings
 from src.logging_config import get_logger
-from src.db.models import User, Role, UserPreferences
-from src.auth.schemas import TokenInfoSchema, UserSchema, RoleSchema, UserPreferencesSchema, UserListItemSchema, BulkSyncResultSchema
+from src.db.models import User, Role, UserPreferences, Group
+from src.auth.schemas import TokenInfoSchema, UserSchema, RoleSchema, UserPreferencesSchema, UserListItemSchema, BulkSyncResultSchema, GroupListItemSchema
 
 logger = get_logger(__name__)
 settings = get_settings()
@@ -470,6 +470,160 @@ class AuthService:
             errors=errors,
         )
 
+    async def list_groups(
+        self,
+        search: Optional[str] = None,
+        offset: int = 0,
+        limit: int = 50,
+    ) -> tuple[list[GroupListItemSchema], int]:
+        """
+        List all groups with optional search and pagination
+
+        Args:
+            search: Optional search query (matches name)
+            offset: Number of records to skip
+            limit: Maximum number of records to return
+
+        Returns:
+            Tuple of (list of group schemas, total count)
+        """
+        from sqlalchemy import func
+
+        # Base query
+        base_query = select(Group)
+
+        # Apply search filter if provided
+        if search:
+            search_filter = f"%{search}%"
+            base_query = base_query.where(Group.name.ilike(search_filter))
+
+        # Get total count
+        count_query = select(func.count()).select_from(base_query.subquery())
+        total_result = await self.session.execute(count_query)
+        total = total_result.scalar() or 0
+
+        # Apply pagination and ordering
+        query = base_query.order_by(Group.name).offset(offset).limit(limit)
+        result = await self.session.execute(query)
+        groups = list(result.scalars().all())
+
+        # Convert to schemas
+        items = [
+            GroupListItemSchema(
+                id=group.id,
+                authentik_id=group.authentik_id,
+                name=group.name,
+                is_superuser=group.is_superuser,
+                parent_name=group.parent_name,
+                member_count=group.member_count,
+                synced_at=group.synced_at,
+            )
+            for group in groups
+        ]
+
+        return items, total
+
+    async def bulk_sync_groups_from_authentik(self) -> BulkSyncResultSchema:
+        """
+        Fetch all groups from Authentik admin API and sync to local database
+
+        Returns:
+            BulkSyncResultSchema with counts of created/updated/failed groups
+        """
+        if not settings.authentik_username or not settings.authentik_password:
+            raise ValueError("AUTHENTIK_USERNAME and AUTHENTIK_PASSWORD must be configured")
+
+        created = 0
+        updated = 0
+        failed = 0
+        errors = []
+        total_in_authentik = 0
+
+        # Step 1: Fetch all group data from Authentik API
+        authentik_groups = []
+        try:
+            async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
+                # Authenticate with Authentik to get session cookie
+                session_cookie = await self._authentik_session_login(client)
+
+                # Fetch groups from Authentik admin API using session cookie
+                response = await client.get(
+                    f"{settings.authentik_url}/api/v3/core/groups/",
+                    params={"page_size": 500},
+                    headers={
+                        "Accept": "application/json",
+                        "Cookie": f"authentik_session={session_cookie}",
+                    },
+                )
+
+                if response.status_code == 401:
+                    raise ValueError("Authentik API token is invalid or expired")
+
+                response.raise_for_status()
+                data = response.json()
+
+                authentik_groups = data.get("results", [])
+                total_in_authentik = data.get("pagination", {}).get("count", len(authentik_groups))
+
+        except httpx.HTTPStatusError as e:
+            raise ValueError(f"Authentik API error: {e.response.status_code}")
+        except httpx.RequestError as e:
+            raise ValueError(f"Failed to connect to Authentik: {str(e)}")
+
+        # Step 2: Sync groups to database (outside of httpx context to avoid greenlet issues)
+        for auth_group in authentik_groups:
+            try:
+                # Extract group data from Authentik
+                authentik_id = uuid.UUID(auth_group["pk"])
+                name = auth_group.get("name", "Unknown")
+                is_superuser = auth_group.get("is_superuser", False)
+                parent_name = auth_group.get("parent_name")
+                # users field contains list of user PKs
+                member_count = len(auth_group.get("users", []))
+
+                # Check if group exists
+                stmt = select(Group).where(Group.authentik_id == authentik_id)
+                result = await self.session.execute(stmt)
+                group = result.scalar_one_or_none()
+
+                if group is None:
+                    # Create new group
+                    group = Group(
+                        authentik_id=authentik_id,
+                        name=name,
+                        is_superuser=is_superuser,
+                        parent_name=parent_name,
+                        member_count=member_count,
+                    )
+                    self.session.add(group)
+                    created += 1
+                    logger.info(f"Created group from Authentik: {name}")
+                else:
+                    # Update existing group
+                    group.name = name
+                    group.is_superuser = is_superuser
+                    group.parent_name = parent_name
+                    group.member_count = member_count
+                    updated += 1
+                    logger.info(f"Updated group from Authentik: {name}")
+
+            except Exception as e:
+                failed += 1
+                error_msg = f"Failed to sync group {auth_group.get('name', 'unknown')}: {str(e)}"
+                errors.append(error_msg)
+                logger.warning(error_msg)
+
+        # Commit all changes
+        await self.session.commit()
+
+        return BulkSyncResultSchema(
+            created=created,
+            updated=updated,
+            failed=failed,
+            total_in_authentik=total_in_authentik,
+            errors=errors,
+        )
+
 
 # Factory function for dependency injection
 def get_auth_service(session: AsyncSession) -> AuthService: