Add Google Group Management app-group-lifecycle plugin

Dockerfile

@@ -49,6 +49,12 @@ COPY requirements.txt api/ ./api/
 COPY migrations/ ./migrations/
 COPY alembic.ini setup.py ./
 COPY ./config ./config
+
+# Ship prod-ready plugin source into the image WITHOUT installing it here.
+# Downstream images opt in by pip installing the plugins,
+# which keeps the source single-homed in this repo while leaving activation to the consumer.
+COPY ./examples/plugins/app_group_lifecycle_google ./plugins/app_group_lifecycle_google
+
 RUN pip install -r ./api/requirements.txt
 # Install the project itself so the `access` console script declared in
 # setup.py (entry_points -> api.manage:cli) is available on PATH for

Makefile

@@ -28,6 +28,7 @@ help:
 	@echo "Management commands:"
 	@echo "  make sync               access sync"
 	@echo "  make notify             access notify"
+	@echo "  make sync-app-groups    access sync-app-groups (loads .env)"
 	@echo ""
 	@echo "Docker:"
 	@echo "  make build              docker build"
@@ -80,7 +81,7 @@ run: .env dev db-migrate
 	@mkdir -p .claude
 	@printf '%s\n' "$(BACKEND_PORT)" > .claude/.api-port
 	$(ACTIVATE) DATABASE_URI=$(LOCAL_DB_URI) \
-	uvicorn --reload --host 0.0.0.0 --port $(BACKEND_PORT) api.asgi:app & \
+	uvicorn --env-file .env --reload --host 0.0.0.0 --port $(BACKEND_PORT) api.asgi:app & \
 	npm install && npx vite --host 0.0.0.0 --port $(FRONTEND_PORT)
 
 .PHONY: run-frontend
@@ -92,7 +93,7 @@ run-backend: .env dev db-migrate
 	@mkdir -p .claude
 	@printf '%s\n' "$(BACKEND_PORT)" > .claude/.api-port
 	$(ACTIVATE) DATABASE_URI=$(LOCAL_DB_URI) \
-	uvicorn --reload --host 0.0.0.0 --port $(BACKEND_PORT) api.asgi:app
+	uvicorn --env-file .env --reload --host 0.0.0.0 --port $(BACKEND_PORT) api.asgi:app
 
 # ----------------------------------------------------------------------
 # Database / migrations
@@ -136,6 +137,18 @@ sync: dev
 notify: dev
 	$(ACTIVATE) DATABASE_URI=$(LOCAL_DB_URI) access notify
 
+# Unlike `sync`/`notify`, this loads the full .env so the app-group lifecycle
+# plugins get the credentials they need (e.g. Google/Okta). `access` has no
+# --env-file flag, so we source .env into the environment ourselves: `set -a`
+# auto-exports every var defined while sourcing. We then force
+# DATABASE_URI=$(LOCAL_DB_URI) -- exactly like `sync`/`notify`/`run-backend` --
+# so this points at the same migrated instance/access.db the dev server uses,
+# rather than whatever DATABASE_URI .env happens to set.
+.PHONY: sync-app-groups
+sync-app-groups: .env dev
+	$(ACTIVATE) set -a && . ./.env && set +a && \
+	DATABASE_URI=$(LOCAL_DB_URI) access sync-app-groups
+
 # ----------------------------------------------------------------------
 # Docker
 # ----------------------------------------------------------------------

api/app.py

@@ -96,8 +96,9 @@ def _flatten_query_param_models(openapi_schema: dict[str, Any]) -> None:
 
 
 def _configure_logging() -> None:
-    logging.basicConfig(level=logging.INFO, stream=sys.stdout, format="%(message)s")
-    logging.root.setLevel(logging.INFO)
+    level = environ.get("LOG_LEVEL", "INFO").upper()
+    logging.basicConfig(level=level, stream=sys.stdout, format="%(message)s")
+    logging.root.setLevel(level)
     token_filter = TokenSanitizingFilter()
     logging.getLogger("authlib").addFilter(token_filter)
     logging.getLogger("uvicorn.access").addFilter(token_filter)

api/manage.py

@@ -48,7 +48,7 @@ def wrapper(*args: Any, **kwargs: Any) -> Any:
             db.init_app(engine=build_engine())
         # Trigger plugin discovery once per CLI run. Notification, conditional
         # access, and app-group-lifecycle hooks are all consumed by the
-        # `sync` / `notify` / `sync-app-group-memberships` commands; the
+        # `sync` / `notify` / `sync-app-groups` commands; the
         # `init` family doesn't need them but the call is cheap (memoized).
         load_plugins()
         token = _session_scope.set(f"cli-{uuid.uuid4().hex}")
@@ -308,13 +308,10 @@ def notify(owner: bool, role_owner: bool) -> None:
         expiring_access_notifications_user()
 
 
-@cli.command("sync-app-group-memberships")
-@_with_app_context
-def sync_app_group_memberships() -> None:
-    """Invoke the periodic membership sync hook for all apps with app group lifecycle plugins configured."""
+def _sync_all_app_groups() -> None:
     from api.extensions import db
     from api.models import App
-    from api.plugins.app_group_lifecycle import get_app_group_lifecycle_hook
+    from api.plugins.app_group_lifecycle import invoke_sync_all_groups
 
     click.echo("Starting app group lifecycle plugin sync")
 
@@ -330,12 +327,10 @@ def sync_app_group_memberships() -> None:
 
     click.echo(f"Found {len(apps)} app(s) with plugins configured")
 
-    hook = get_app_group_lifecycle_hook()
-
     for app in apps:
         click.echo(f"Syncing app '{app.name}' (plugin: {app.app_group_lifecycle_plugin})")
         try:
-            hook.sync_all_group_membership(session=db.session, app=app, plugin_id=app.app_group_lifecycle_plugin)
+            invoke_sync_all_groups(session=db.session, app=app, plugin_id=app.app_group_lifecycle_plugin)
             db.session.commit()
             click.echo(f"  ✓ Synced app '{app.name}'")
         except Exception as e:
@@ -345,5 +340,19 @@ def sync_app_group_memberships() -> None:
     click.echo("Completed app group lifecycle plugin sync")
 
 
+@cli.command("sync-app-groups")
+@_with_app_context
+def sync_app_groups() -> None:
+    """Invoke the periodic group-sync hook for all apps with app group lifecycle plugins configured."""
+    _sync_all_app_groups()
+
+
+@cli.command("sync-app-group-memberships", hidden=True)
+@_with_app_context
+def sync_app_group_memberships() -> None:
+    """Deprecated alias for `sync-app-groups`; kept so existing automation keeps working."""
+    _sync_all_app_groups()
+
+
 if __name__ == "__main__":
     cli()

api/operations/__init__.py

@@ -18,6 +18,7 @@
 from api.operations.modify_app_tags import ModifyAppTags
 from api.operations.modify_group_tags import ModifyGroupTags
 from api.operations.modify_group_details import ModifyGroupDetails
+from api.operations.modify_group_plugin_data import ModifyGroupPluginData
 from api.operations.modify_group_type import ModifyGroupType
 from api.operations.modify_group_users import ModifyGroupUsers
 from api.operations.modify_role_groups import ModifyRoleGroups
@@ -39,6 +40,7 @@
     "CreateGroup",
     "ModifyAppTags",
     "ModifyGroupDetails",
+    "ModifyGroupPluginData",
     "ModifyGroupTags",
     "ModifyGroupType",
     "ModifyGroupUsers",

api/operations/modify_group_plugin_data.py

@@ -0,0 +1,81 @@
+import logging
+from typing import Any
+
+from api.extensions import db
+from api.models import AppGroup, OktaGroup
+from api.plugins.app_group_lifecycle import (
+    get_app_group_lifecycle_hook,
+    get_app_group_lifecycle_plugin_to_invoke,
+    is_plugin_config_changed,
+    merge_app_lifecycle_plugin_data,
+)
+
+
+class ModifyGroupPluginData:
+    """Apply a (partial) plugin_data patch to a group and fire group_updated when the
+    configured app group lifecycle plugin's *configuration* changes.
+
+    Owns the plugin_data merge semantics so callers only supply the patch:
+    - top-level plugin entries the patch omits are preserved;
+    - for app group lifecycle plugins, per-plugin configuration/status keys the patch
+      omits are preserved too, so a partial configuration edit does not wipe
+      plugin-managed status (e.g. a linked external group id).
+
+    group_updated fires only on configuration changes -- never on status-only changes,
+    which the plugin itself writes and which would otherwise re-trigger reconciliation in
+    a loop -- and only after the merge, so the hook observes the fully-merged plugin_data.
+    """
+
+    def __init__(self, *, group: OktaGroup, plugin_data: dict[str, Any]):
+        self.group = group
+        self.plugin_data = plugin_data
+
+    def execute(self) -> OktaGroup:
+        old_plugin_data = self.group.plugin_data or {}
+        old_name = self.group.name
+        old_description = self.group.description or ""
+        plugin_id = get_app_group_lifecycle_plugin_to_invoke(self.group)
+
+        # Apply the patch: start from the incoming data, preserving top-level plugin
+        # entries it didn't mention.
+        merged_plugin_data = dict(self.plugin_data)
+        changed = bool(old_plugin_data) and merged_plugin_data != old_plugin_data
+        if changed:
+            for key in old_plugin_data:
+                if key not in merged_plugin_data:
+                    merged_plugin_data[key] = old_plugin_data[key]
+
+        # Decide whether to fire the hook before the per-plugin merge below, which
+        # mutates old_plugin_data in place (it shares the configuration/status dicts)
+        # and would otherwise erase the difference we're testing for.
+        config_changed = plugin_id is not None and is_plugin_config_changed(
+            old_plugin_data, merged_plugin_data, plugin_id
+        )
+
+        self.group.plugin_data = merged_plugin_data
+
+        # Preserve per-plugin configuration/status keys the patch omitted for app group
+        # lifecycle plugins (partial-patch semantics).
+        if changed and type(self.group) is AppGroup:
+            merge_app_lifecycle_plugin_data(self.group, old_plugin_data)
+
+        db.session.commit()
+
+        if config_changed:
+            try:
+                hook = get_app_group_lifecycle_hook()
+                hook.group_updated(
+                    session=db.session,
+                    group=self.group,
+                    old_name=old_name,
+                    old_description=old_description,
+                    plugin_id=plugin_id,
+                )
+                db.session.commit()
+            except Exception:
+                logging.getLogger("api").exception(
+                    f"Failed to invoke group_updated hook for group {self.group.id} with plugin '{plugin_id}'"
+                )
+                db.session.rollback()
+
+        return self.group