OpenCoreGovernance

Permissions Migration

View as Markdown

OpenCore is introducing permission grants on groups while retaining existing role and object-scope checks. Treat this as an additive migration with a mixed enforcement period, not as a completed role replacement.

Version status: The current source includes phase-one backend group grants, but the Groups UI labels the rollout Upcoming and does not expose permission toggles. Curator and Global Curator remain active and tested. Do not remove or demote those roles based on this page. Any future role retirement is a migration target only; verify the running release, UI, API, and endpoint coverage before cutover.

Version status matrix

AreaCurrent statusMigration implication
Group permission storageDirect grants and recomputed effective permissions exist in the backendGrants can be staged without assuming every endpoint consumes them.
Group administration APIAdmin-only read and update operations exist for toggleable permissionsAPI availability does not prove that the deployed UI exposes the controls.
Groups UIShows an upcoming-permissions notice and manages membership and shared resourcesAdmins need version-specific tooling before using group grants as an operational control.
Curator rolesCurator and Global Curator dependencies, scope checks, and tests remain activePreserve role assignments throughout the mixed-enforcement period.
Full permission migrationFuture target; no source-backed removal version is definedPlan the cutover only after the running release proves complete coverage.

Current authorization model

LayerCurrent behaviorBoundary to verify
Request permission guardPermission-aware endpoints require a named effective permission; personal access token scopes are checked as an additional restrictionTest both the user session and any token used for the same operation.
Group grantsA user’s effective permissions are recomputed from the union of direct grants on their groupsMembership or grant changes must be followed by effective-permission verification.
Implied permissionsBroader write permissions imply related read permissions at evaluation timeStore only direct grants and verify the effective result instead of duplicating implied grants.
Role and object scopeAdmin, Curator, Global Curator, ownership, and group-resource checks still protect legacy or scoped operationsA group grant does not automatically bypass an existing role or ownership check.

Basic access, administrative override, internal implied permissions, and protected service behavior are not toggleable group grants. The backend rejects attempts to grant non-toggleable permissions through the group permission API.

Current Groups workflow

1

Create and name the group

An Admin creates the group. The backend assigns basic access to a new group and recomputes member permissions when membership or grants change.

2

Manage members and shared resources

The current Groups UI can update the group name, members, connector or credential-pair scope, and shared Agent or document-set relationships when those features are available.

3

Preserve role scope

Curators continue to operate only within the group and object scopes allowed by their current role. Global Curators continue to use their current member-group scope.

4

Use permission APIs only with version evidence

The backend permission read and update routes require full Admin access and accept only toggleable permissions. Confirm that the running deployment includes those routes before using them outside a test environment.

The current UI does not provide a permission-toggle control. A successful group edit in that UI therefore verifies membership or resource sharing, not a permission grant.

Current role behavior

RoleCurrent authorityMigration rule
AdminDeployment-wide configuration and Admin-only group permission routesRetain an emergency Admin path throughout migration.
CuratorScoped management for groups for which the person is a curatorPreserve until every delegated operation has an equivalent tested permission path.
Global CuratorScoped management for member groups under the current role rulesPreserve until member-group behavior has an equivalent tested permission path.
UserBasic use plus resources and operations made available by existing shares and effective permissionsTest representative users instead of inferring access from group membership alone.

Curator removal is not a current capability or completed source change. Existing Curator flows and scope boundaries remain part of the running authorization contract.

Future migration target

The target below is a plan, not a statement of current availability. Do not schedule role retirement until the deployed product exposes the required group controls and the relevant endpoints consistently enforce the new permission model.

TargetCompletion evidence
Administrable group grantsAdmins can view and change supported grants through approved tooling in the running release.
Consistent endpoint enforcementEach migrated endpoint checks the intended permission, token scope, tenant, ownership, and object scope.
Delegation parityEvery required Curator workflow has a tested replacement without broadening resource access.
Observable rollbackGrant changes, effective permissions, denials, and retained role assignments can be audited and reversed.

Migration runbook

1

Inventory current authority

Export or record Admin, Curator, Global Curator, group membership, shared-resource, ownership, and token-scope assignments. Map each operational task to its current endpoint and object boundary.

2

Confirm the running version

Verify that the deployed backend provides the intended group permission routes and that approved administration tooling exposes the grants. Keep role assignments unchanged.

3

Stage additive grants

Add the minimum toggleable grants to controlled groups. Re-read each affected user’s effective permissions and record the expected implied permissions.

4

Test every path

Use representative users and personal access tokens to test allowed and denied operations, tenant boundaries, ownership rules, and group-resource scope. Include legacy Curator workflows in the regression set.

5

Cut over only after parity

Change a role assignment only after all required paths have equivalent tested coverage, operational owners approve the result, and rollback data is available. Make changes in small cohorts.

Verification matrix

ScenarioExpected result
Member with a staged direct grantThe intended operation succeeds and the related implied read permission is visible when applicable.
Member after grant revocationEffective permissions are recomputed and the protected operation is denied.
Token without the required scopeThe operation is denied even when the user’s session permissions would allow it.
User outside the tenant, group, ownership, or resource scopeThe operation remains denied despite an unrelated permission grant.
Existing Curator during mixed enforcementCurrent scoped workflows continue to work and do not expand beyond their tested group or ownership boundary.

Rollback

Keep the pre-migration role and membership inventory until every cohort is stable. If a grant path is missing, over-broad, or inconsistent, revoke the staged grant, recompute and verify effective permissions, restore any changed role assignment, and retest the legacy path. Do not use role deletion as a rollback mechanism.