Spatie Permission Adapter for Cbox ID
Adopt Cbox ID for authentication, SSO, OAuth/OIDC and SCIM while an existing spatie/laravel-permission install stays the source of roles, permissions and token claims. Binds the platform's authorization contracts to Spatie, with a SCIM group-to-role bridge that never revokes a manually granted role.
An application that already runs spatie/laravel-permission does not have to give up its RBAC to adopt Cbox ID. This adapter keeps Spatie as the single source of roles and permissions, and lets the platform handle authentication, enterprise SSO, the OAuth/OIDC provider and SCIM on top of it. The roles you already manage are stamped straight into the tokens the platform mints.
Why an adapter, not a merge
Cbox ID ships its own hierarchy-aware RBAC, but it never resolves authorization directly: it depends on the AccessChecker and Roles contracts. This package implements those against Spatie and binds them under the platform's external access-control driver, which gates the built-in RBAC tables off entirely. Two RBACs never run side by side, and the roles/permissions table names never collide.
What It Provides
Authorization Reads
Permission checks and token claims resolve from Spatie's effective (direct plus role-derived) permissions and roles. An unknown permission or an unresolved subject denies rather than errors.
Token Claims
The OAuth/OIDC token issuer and the UserInfo endpoint read through the same contract, so your Spatie roles and permissions land in every token the platform issues.
Role Authoring
Defining roles, granting permissions and assigning or unassigning them drive into Spatie, so SCIM provisioning and access-governance campaigns write to the backend you already run.
SCIM Group Bridge
Map a directory group onto a role and the grant is kept in sync as membership changes, driven by the platform's directory membership event.
Safe Reconciliation
A ledger of the grants the bridge itself made means reconciliation only ever removes what it granted, so an administrator's hand-granted role survives a directory sync.
Organization Scoping
With Spatie's teams feature enabled each platform organization maps onto a team, so a role is scoped to the organization it was granted in. With teams off the backend is flat.
The problem the bridge had to solve
Spatie records that a role is held, but not why. A naive directory sync would therefore strip roles an administrator granted by hand the moment a user left a mapped group. The bridge keeps its own ledger of the grants it made, including a flag for a role the subject already held when a push landed, so revoking the push leaves the manual grant intact. Four cases are covered by tests: a pushed role is revoked when the subject leaves the group, a manual grant is kept, a manual grant later duplicated by a push is kept, and an administrator can still revoke their own grant.
That ledger also restores grant-source fidelity the backend cannot express on its own. Assignments are reported as pushed or manual rather than uniformly manual, which is what access-certification campaigns display when a reviewer decides whether to keep or revoke an access grant.
Adopting it
Set the platform's access-control driver to external, point the adapter at your authorizable model, and add one interface to the model that already uses Spatie's HasRoles trait. Nothing else changes: callers keep depending on the platform contracts, and this package is inert until the external driver is selected, so installing it cannot disturb an app running the built-in RBAC.
Honest scope
The host's authorizable model must be keyed by the same identifier the platform uses for a subject, since that id is how a check finds the Spatie user. The platform's ancestor-organization roll-down is a built-in-driver feature and is not modelled by a flat Spatie backend. Mapping priority orders listings but does not override: a role is granted whenever any mapped group matches.