Add Google Group Management app-group-lifecycle plugin

[barborico]

Summary

Adds a google_group_manager app-group-lifecycle plugin that automatically creates, updates, and deletes Google groups for Access groups and links them to the Access-managed Okta group via Okta group push, plus the core-Access enablers it needs. Group CRUD uses the Cloud Identity Groups API.

Urgency: 1 week?
Expected review effort: HIGH (~1h), since there's quite a lot of code but it's well-organized and -tested, if I do say so myself :)

Motivation

Access apps need Google groups that mirror their Access groups: when an Access group is created, reconfigured, or deleted, the matching Google group should be created/updated/deleted and linked via Okta group push, which then keeps membership in sync. This plugin delivers that as an opt-in example plugin which can replace manual toil to keep the two group management systems in sync.

Plugin Capabilities

• Enabled at app level: The plugin is configured (and can be separately enabled/disabled) at the scope of individual applications.
• Lifecycle automation: creating, updating (display name / description), or deleting an Access group with the plugin enabled creates/updates/deletes the corresponding Google group.
• Okta group push linking: creates the push mapping between the Access-managed Okta group and the Google group; Okta then owns membership sync.
• Idempotent reconciliation: a single _reconcile drives create/update and a periodic sync_all_groups sweep; it is safe to re-run and converges to the desired state.
• Access as source of truth, with graceful backfill from Google: When Google group config is present in Access, it's pushed to Google. Google groups already linked out-of-band are adopted (missing Access-side config is inferred from live Google/Okta state). If there's no Access-side config or existing link, the plugin does nothing.
• App-level email-prefix pattern: an optional regex (e.g. ^gcp-) is enforced on create/update and surfaced as both client-side and server-side validation.
• Status visibility: each group surfaces sync_status (synced / pending / error), sync_error, last_synced_at, google_group_id, and push_mapping_id.

Limitations & behavior notes

• Membership is Okta's responsibility: the plugin implements no membership hooks; it only manages the Google group and the push mapping. Membership flows entirely through Okta group push.
• Email is immutable: the Google group email (Cloud Identity groupKey) cannot change after creation, so the email config field is enforced immutable on update (rendered read-only in the UI when editing). Display name and description stay mutable.
• Linking is best-effort and eventually consistent — if Okta has not yet imported the new Google group, the push mapping cannot be created; the group is marked pending and linked on a later reconcile/sweep.
• The join key is the email: link discovery relies on Okta's googleGroupEmail profile attribute on the imported target app group (Cloud Identity IDs differ from the Directory IDs Okta stores--two different Google APIs for group management).
• Errors are recorded, not fatal: blocking Google/Okta errors during reconcile are written to sync_status=error (committed so they survive the host's post-error rollback) rather than aborting the operation; a legacy email that predates a later-added pattern is grandfathered (never re-enforced, since the email can't change), and editing a group's other properties is not blocked by an unchanged, non-conforming legacy email.
• Opt-in: the published Access image ships the plugin source (/app/plugins) but does not install it; a downstream/overlay image opts in by pip-installing it. The README documents this, the Cloud Identity auth model, and the required GOOGLE_WORKSPACE_* env vars.

Description of Changes

Core Access enablers (api/, src/)

• OktaService gains create / delete / list_group_push_mappings (Okta Group Push Mapping API).
• App-config-aware group-config hooks, plus set_config_value / is_plugin_config_changed framework helpers. The bulk-sync hook sync_all_group_membership is renamed to sync_all_groups (with a backward-compatible deprecated alias, and renamed CLI command / make target).
• New ModifyGroupPluginData operation: merges a partial plugin_data patch (preserving other plugins' entries and plugin-managed status) and fires group_updated only when the plugin's configuration changes — never on status writes, which would otherwise re-trigger reconciliation in a loop. put_group routes through it; post_group validates group config at creation.
• Immutable group-config fields: a schema flag, generic host-side enforcement on update, and read-only rendering in the config form.
• The group-config-props endpoint accepts ?app_id= so the schema can reflect app-level constraints; the config form validates patterns client-side.
• The Dockerfile copies the plugin source into the image (/app/plugins) without installing it, so downstream images can opt in while the source stays single-homed in this repo.
• Misc dev QoL improvements: configurable root LOG_LEVEL; a sync-app-groups make target that loads .env.

Plugin (examples/plugins/app_group_lifecycle_google/)

• Built up Cloud-Identity-first: package scaffold + docs → config/status schema, validation, email helpers → Cloud Identity Groups API wrappers → Okta push-mapping + link discovery → the idempotent reconcile core → lifecycle hooks (group_created/group_updated/group_deleted) and the sync_all_groups sweep.

Web UI Screenshots

App Config

Group Config & Status
Creating a group (with validation):

Pending Okta re-pulling groups from Google:

Success:

With sync errors:

Notice grandfathering of bad-pattern email in backfill:

Failure to takeover an existing group:

Validation of Changes

• The app-group-lifecycle framework, Okta service, and group/app router suites pass, as does the full standalone plugin suite (60 tests). ruff check and ruff format --check are clean; the frontend tsc typecheck and the plugin config form's vitest pass.
• Coverage includes: the Okta push-mapping methods; ModifyGroupPluginData (config-change vs status-only, and via put_group); create/update validation including immutable-field rejection; and full plugin behavior (schema/validation, Cloud Identity wrappers, push-mapping/discovery, reconcile create/adopt/enforce/grandfather/pending/error branches, and the lifecycle hooks including delete ordering and sweep isolation).
• Manual smoke testing the Okta and Google integrations and E2E flow
  • Link a "legacy" group out-of-band with unallowed email -> backfill to Access
  • Create a new group -> group created in Google and pending -> refresh Okta app groups -> reconcile -> group linked in Okta
  • Try to create a group with a bad email -> blocked
  • Modify group name and description with preexisting unallowed email -> change propagated to Google
  • Delete a group -> group and link deleted

Guidance for Reviewers

History is clean and deliberately logically grouped — review commit-by-commit. It is two halves: the core-Access enablers (api/, src/) precede the plugin (examples/); the tail is two formatting-only commits and a final Dockerfile commit that ships (but doesn't install) the plugin source.

I've reviewed and exercised the code both manually and with the Claude code-review skill. Consider overall functionality--does the behavior match what you'd expect/want this plugin to do?

🤖 Generated with Claude Code

[barborico]

bugbot run

[cursor]

Skipping Bugbot: Bugbot is disabled for this repository. Visit the Bugbot dashboard to update your settings.

[Jeff-Rowell]

This compares the raw incoming patch against the old config, but the patch can be partial (that's the point of ModifyGroupPluginData's merge). A client that PUTs {configuration: {display_name: ...}} and omits the immutable email trips this: email goes from set to None, reads as a change, and 400s even though the user never touched it. The UI hides it by resubmitting the read-only field, but partial API updates break.

Fix: only treat a field as edited when it's actually present in the patch. An omission isn't a change; an explicit value (even null) still is. The grandfathering else branch is unaffected, and a present-and-different value is still rejected.

Suggested change

	if old_configuration.get(name) != configuration.get(name):
	if name in configuration and old_configuration.get(name) != configuration.get(name):

[Jeff-Rowell]

I think this makes it impossible to clear a description. If a user empties the Access description and Google still has one, access_desc is "" so the enforce branch won't push the clear, and then this backfills Google's value right back (and pushes it to Okta)

[Jeff-Rowell]

ModifyGroupDetails fires group_updated on a name/description change, and this fires it again on a config change. A PUT that changes both name and plugin config in one request runs a full reconcile twice (Google + Okta round-trips)

Proposed fix: fire group_updated exactly once in put_group after both operations apply, and suppress the per-operation fires.

1. ModifyGroupDetails — add an opt-out (default preserves behavior for its other callers):

def __init__(self, *, group, name=None, description=None, current_user_id=None,
             validate_app_group_prefix=True, fire_lifecycle_hook=True):
    ...
    self.fire_lifecycle_hook = fire_lifecycle_hook

# in execute():
if self.fire_lifecycle_hook and (old_name != self.group.name or old_description != self.group.description):
    ...  # existing group_updated fire

2. ModifyGroupPluginData — same fire_lifecycle_hook=True opt-out, so put_group can suppress its internal fire (the merge still runs; only the hook call is gated).

3. put_group — capture old values before ModifyGroupDetails, suppress both, fire once at the end:

old_name = group.name
old_description = group.description or ""
plugin_id = get_app_group_lifecycle_plugin_to_invoke(group)
...
ModifyGroupDetails(..., fire_lifecycle_hook=False).execute()
...
old_plugin_data_for_audit = copy.deepcopy(group.plugin_data) if group.plugin_data else {}
if new_plugin_data is not None:
    ModifyGroupPluginData(group=group, plugin_data=new_plugin_data, fire_lifecycle_hook=False).execute()
else:
    db.commit()

name_or_desc_changed = group.name != old_name or (group.description or "") != old_description
config_changed = (
    new_plugin_data is not None
    and plugin_id is not None
    and is_plugin_config_changed(old_plugin_data_for_audit, group.plugin_data or {}, plugin_id)
)
if plugin_id is not None and (name_or_desc_changed or config_changed):
    try:
        get_app_group_lifecycle_hook().group_updated(
            session=db, group=group, old_name=old_name,
            old_description=old_description, plugin_id=plugin_id,
        )
        db.commit()
    except Exception:
        logging.getLogger("api").exception(
            f"Failed to invoke group_updated hook for group {group.id} with plugin '{plugin_id}'"
        )
        db.rollback()

[Jeff-Rowell]

This dispatches both the new and deprecated hook names. The docstring says implement only one, but nothing enforces it, so a plugin implementing both (e.g. mid-migration) gets every group reconciled twice. Suggestion below guards against it by raising if any plugin implements both:

Suggested change

	hook = get_app_group_lifecycle_hook()
	hook.sync_all_groups(session=session, app=app, plugin_id=plugin_id)
	hook.sync_all_group_membership(session=session, app=app, plugin_id=plugin_id)
	hook = get_app_group_lifecycle_hook()
	current_impls = {impl.plugin for impl in hook.sync_all_groups.get_hookimpls()}
	deprecated_impls = {impl.plugin for impl in hook.sync_all_group_membership.get_hookimpls()}
	both = current_impls & deprecated_impls
	if both:
	names = ", ".join(getattr(p, "__name__", repr(p)) for p in both)
	raise ValueError(
	f"Plugin(s) {names} implement both sync_all_groups and the deprecated "
	"sync_all_group_membership; implement exactly one."
	)
	hook.sync_all_groups(session=session, app=app, plugin_id=plugin_id)
	hook.sync_all_group_membership(session=session, app=app, plugin_id=plugin_id)

[somethingnew2-0]

I've rebased the PR after quite a few changes: #480 #481 #507 #511

The rebased version of the PR is in draft at #532 so as not to completely overwrite this one. PTAL!