feat: add access module boundary migrations
This commit is contained in:
157
docs/ACCESS_MODULE_BOUNDARY.md
Normal file
157
docs/ACCESS_MODULE_BOUNDARY.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# GovOPlaN Access Module Boundary
|
||||
|
||||
`govoplan-access` is the platform module that owns login identity and runtime
|
||||
authorization state. Core remains the kernel: it composes modules, mounts
|
||||
routes, owns process/database lifecycle, and exposes stable capability
|
||||
contracts.
|
||||
|
||||
## Access-Owned Capabilities
|
||||
|
||||
`govoplan-access` owns the canonical implementation for:
|
||||
|
||||
- accounts and global login identity
|
||||
- interactive authentication routes and session lifecycle
|
||||
- API-key creation, verification, revocation, and scope delegation
|
||||
- tenant-local users, memberships, groups, roles, and role assignments
|
||||
- identity-to-account projection used for explainability
|
||||
- organization-bound functions, function assignments, and delegation facts
|
||||
- principal resolution and request authentication dependencies
|
||||
- permission evaluation for access-owned scopes and legacy access aliases
|
||||
- access-decision explain output with identity/account/function/role/right
|
||||
provenance
|
||||
- access administration backend routes for users, groups, roles, system
|
||||
accounts, sessions, and API keys
|
||||
- access administration WebUI route contribution for `/admin`
|
||||
- tenant owner provisioning and default access bootstrap
|
||||
- materializing governance templates into access-owned groups and roles
|
||||
- access-owned SQLAlchemy metadata and migrations for `access_*` tables
|
||||
|
||||
The active access tables use the `access_*` namespace while the model classes
|
||||
live in this module: `access_accounts`, `access_users`, `access_groups`,
|
||||
`access_roles`, `access_system_role_assignments`,
|
||||
`access_user_group_memberships`, `access_user_role_assignments`,
|
||||
`access_group_role_assignments`, `access_api_keys`, and
|
||||
`access_auth_sessions`.
|
||||
|
||||
## Kernel-Owned Contracts
|
||||
|
||||
`govoplan-core` owns the stable contracts that let modules interact without
|
||||
importing access internals:
|
||||
|
||||
- `ModuleManifest`, route factories, migration specs, and registry validation
|
||||
- database engine/session lifecycle and migration orchestration
|
||||
- capability registry and capability names in `govoplan_core.core.access`
|
||||
- access DTO/protocol contracts such as `PrincipalRef`, `AccountRef`,
|
||||
`UserRef`, `GroupRef`, `RoleRef`, `IdentityRef`,
|
||||
`OrganizationUnitRef`, `FunctionRef`, `FunctionAssignmentRef`,
|
||||
`FunctionDelegationRef`, `AccessDecisionProvenance`,
|
||||
`PrincipalResolver`, `AccessDirectory`, `AccessSemanticDirectory`,
|
||||
`PermissionEvaluator`, `AccessExplanationService`,
|
||||
`TenantAccessProvisioner`, `AccessAdministration`, and
|
||||
`AccessGovernanceMaterializer`
|
||||
- health, platform metadata, and module startup ordering
|
||||
- generic security helpers that are not access-state semantics, such as
|
||||
secret encryption and UTC time helpers
|
||||
|
||||
Feature modules should depend on these kernel contracts or the published
|
||||
`govoplan_access.auth` request dependency API, not on access ORM models or
|
||||
`govoplan_access.backend.*` implementation internals.
|
||||
|
||||
## Principal Context Contract
|
||||
|
||||
The stable runtime principal is `govoplan_core.core.access.PrincipalRef`.
|
||||
Access resolves request credentials into that DTO and `ApiPrincipal` keeps the
|
||||
legacy ORM objects only for routers that have not yet moved to pure kernel
|
||||
contracts. New module code should pass around `PrincipalRef` or primitive IDs.
|
||||
|
||||
`PrincipalRef.to_dict()` is the canonical API/WebUI serialization shape:
|
||||
|
||||
- `account_id`, `membership_id`, and `tenant_id`
|
||||
- optional `identity_id`
|
||||
- sorted `scopes`, `group_ids`, `role_ids`, `function_assignment_ids`, and
|
||||
`delegation_ids`
|
||||
- `auth_method` plus optional `session_id`, `api_key_id`, or
|
||||
`service_account_id`
|
||||
- optional `acting_for_account_id` for acting-in-place flows
|
||||
- optional display fields `email` and `display_name`
|
||||
|
||||
`/api/v1/auth/me`, `/api/v1/auth/login`, profile refreshes, and tenant switches
|
||||
include this payload as `principal` alongside the existing compatibility
|
||||
fields. Modules that need current user context should prefer
|
||||
`auth.principal`/`AuthInfo.principal` in the WebUI and
|
||||
`principal.to_platform_principal()` in backend request handlers.
|
||||
|
||||
## Identity And Function Boundary
|
||||
|
||||
The full semantic model is documented in
|
||||
[IDENTITY_ACCOUNT_FUNCTION_MODEL.md](IDENTITY_ACCOUNT_FUNCTION_MODEL.md).
|
||||
In short:
|
||||
|
||||
- `govoplan-idm` imports and previews external identity and organization facts
|
||||
from IDM systems.
|
||||
- `govoplan-identity` owns canonical identities and identity/account links.
|
||||
- `govoplan-organizations` owns canonical organization units, functions, and
|
||||
account-held function assignments.
|
||||
- `govoplan-access` owns the authorization projection that maps organization
|
||||
and identity facts to roles, rights, delegation enforcement, and explainable
|
||||
permission decisions.
|
||||
|
||||
Function assignments are account-held and organization-scoped. They can apply
|
||||
only to the selected organization unit or to that unit and all subunits.
|
||||
Delegation and acting-in-place must remain explicit facts with audit
|
||||
provenance; modules must not infer either from plain group membership.
|
||||
|
||||
The backend foundation exposes these administration routes:
|
||||
|
||||
- `/api/v1/admin/identities`
|
||||
- `/api/v1/admin/organization-units`
|
||||
- `/api/v1/admin/functions`
|
||||
- `/api/v1/admin/function-assignments`
|
||||
- `/api/v1/admin/function-delegations`
|
||||
|
||||
Dedicated WebUI management panels and explicit acting-in-place context
|
||||
selection are still follow-up work on top of these routes.
|
||||
|
||||
## Removed Compatibility Paths
|
||||
|
||||
These legacy imports were removed from core. Use access-owned modules, the
|
||||
public `govoplan_access.auth` request dependency API, or kernel capabilities
|
||||
instead:
|
||||
|
||||
- `govoplan_core.security.api_keys`
|
||||
- `govoplan_core.security.sessions`
|
||||
- `govoplan_core.security.passwords`
|
||||
- `govoplan_core.api.v1.auth`
|
||||
- `govoplan_core.api.v1.admin`
|
||||
- `govoplan_core.api.v1.admin_schemas`
|
||||
- `govoplan_core.admin.service`
|
||||
- `govoplan_core.admin.governance`
|
||||
|
||||
HTTP route compatibility remains at the API layer: the access manifest
|
||||
contributes the same `/api/v1/auth/*` and `/api/v1/admin/*` paths through module
|
||||
route aggregation.
|
||||
|
||||
## Route Ownership
|
||||
|
||||
The access manifest contributes the `/api/v1/auth/*` interactive auth routes
|
||||
and the access-owned `/api/v1/admin/*` administration routes through its module
|
||||
route factory. Core default server configuration must not register auth or
|
||||
admin routers as base routers.
|
||||
|
||||
Governance-template metadata CRUD is not access-owned. It is contributed by
|
||||
`govoplan-admin`; access only materializes those templates into access-owned
|
||||
groups and roles through the `access.governanceMaterializer` capability.
|
||||
|
||||
## Verification References
|
||||
|
||||
Focused verification is run from `/mnt/DATA/git/govoplan-core`.
|
||||
|
||||
- `tests.test_module_system` verifies manifest discovery, access startup in
|
||||
module permutations, admin route ownership, governance-template route
|
||||
separation, and legacy compatibility imports.
|
||||
- `tests.test_api_smoke.ApiSmokeTests.test_cookie_session_requires_csrf_for_mutations`
|
||||
verifies the access-owned session/auth route behavior.
|
||||
- `tests.test_api_smoke.ApiSmokeTests.test_tenant_user_group_role_and_api_key_administration`
|
||||
verifies access-owned administration and API-key behavior.
|
||||
- `tests.test_api_smoke.ApiSmokeTests.test_profile_refresh_and_system_role_protection_model`
|
||||
verifies profile/session refresh and protected system role behavior.
|
||||
177
docs/IDENTITY_ACCOUNT_FUNCTION_MODEL.md
Normal file
177
docs/IDENTITY_ACCOUNT_FUNCTION_MODEL.md
Normal file
@@ -0,0 +1,177 @@
|
||||
# Identity, Account, Function, Role, And Right Model
|
||||
|
||||
GovOPlaN access distinguishes identity facts, organizational responsibility,
|
||||
and authorization decisions. This is groundwork for postboxes, workflows,
|
||||
service directories, portals, delegation, and audit review.
|
||||
|
||||
Directory services, identity providers, and IDM systems can authenticate people
|
||||
and provide external facts. GovOPlaN access owns the normalized runtime
|
||||
projection used for sessions, tenant memberships, groups, functions, roles,
|
||||
delegations, and permission decisions.
|
||||
|
||||
## Semantic Layers
|
||||
|
||||
- Identity: the real person, service, or external subject. An identity can have
|
||||
multiple accounts, for example a normal account and a privileged
|
||||
administration account.
|
||||
- Account: the login or technical account used to authenticate. Access
|
||||
decisions are account-based because the account is the acting credential.
|
||||
- Tenant membership: the account's participation in a tenant.
|
||||
- Organization unit: the administrative unit where responsibility applies.
|
||||
Organization units are hierarchical; access must know when a function applies
|
||||
only to one unit or to that unit and all subunits.
|
||||
- Function: a named responsibility held by an account in an organization unit,
|
||||
such as case clerk, intake desk, treasurer, dean's office assistant, or
|
||||
committee secretary. A function can map to one or more access roles.
|
||||
- Role: a permission bundle or workflow authority attached to a function,
|
||||
group, or explicit assignment.
|
||||
- Right: the concrete scope or action permission evaluated at runtime.
|
||||
|
||||
The UI and API must not collapse these layers into a generic group concept.
|
||||
Directory groups can feed mappings, but they must not silently become business
|
||||
authority without a governed mapping rule.
|
||||
|
||||
## Organizational Function Scope
|
||||
|
||||
A function is meaningful only with organizational scope. The stable contract
|
||||
therefore separates:
|
||||
|
||||
- `FunctionRef`: the organization-bound function definition, including tenant,
|
||||
organization unit, role mappings, and delegation policy flags.
|
||||
- `FunctionAssignmentRef`: the account-held assignment for that function,
|
||||
including identity provenance and whether the assignment applies to all
|
||||
subunits of the function's organization unit.
|
||||
|
||||
The assignment is the runtime authority. A role mapped to a function does not
|
||||
grant rights until an account has an active assignment for that function.
|
||||
|
||||
Example:
|
||||
|
||||
- Identity `Anna Becker` owns accounts `anna` and `anna-admin`.
|
||||
- Account `anna` has function `Registry Clerk` in organization unit
|
||||
`Student Registry`.
|
||||
- The assignment has `applies_to_subunits = true`, so the same function applies
|
||||
to subordinate registry offices unless policy narrows it.
|
||||
- The function maps to role `registry.case_editor`, which grants rights such as
|
||||
`cases:case:update`.
|
||||
|
||||
## Delegation And Acting In Place
|
||||
|
||||
Functions can be delegated only if the function policy permits it. GovOPlaN
|
||||
distinguishes two delegation modes:
|
||||
|
||||
- Delegation: the delegate acts as themself, with provenance showing the
|
||||
delegated function assignment.
|
||||
- Acting in place: the actor performs an action in another holder's function
|
||||
context. Audit and explain responses must show both the real actor account
|
||||
and the account being represented.
|
||||
|
||||
Both modes should be time-bound, revocable, auditable, and visible in access
|
||||
explain output. Module code must not infer delegation from ordinary group
|
||||
membership.
|
||||
|
||||
## IDM Boundary
|
||||
|
||||
`govoplan-idm` owns synchronization with external IDM systems: SCIM, LDAP,
|
||||
SAML/OIDC claims, directory attributes, preview, rollback, and mapping import.
|
||||
It does not own GovOPlaN's internal identity, organization, function, role, or
|
||||
permission evaluation tables.
|
||||
|
||||
`govoplan-identity` owns canonical identity records and identity/account links.
|
||||
`govoplan-organizations` owns canonical organization units, functions, and
|
||||
function assignments. During the transition, access keeps a security projection
|
||||
of those concepts for compatibility and authorization, but new integrations
|
||||
should target the identity and organization capabilities first.
|
||||
|
||||
`govoplan-access` owns the platform projection created from those mappings:
|
||||
|
||||
- accounts and tenant membership projection
|
||||
- identity-to-account links used for explainability
|
||||
- groups, roles, function assignments, and delegation facts
|
||||
- permission decisions and explain responses
|
||||
- access-owned identity and membership change events
|
||||
- mapping effects after an IDM import is accepted
|
||||
|
||||
Access does not own:
|
||||
|
||||
- mailboxes, calendars, files, cases, tasks, postboxes, or other module data
|
||||
- canonical organization structure once `govoplan-organizations` is enabled
|
||||
- canonical identity records once `govoplan-identity` is enabled
|
||||
- module-specific ACL records beyond stable principal/group/role references
|
||||
- external provider internals except where they mutate access-owned state
|
||||
|
||||
## Kernel Contracts
|
||||
|
||||
The stable DTO and protocol surface lives in
|
||||
`govoplan_core.core.access`. The current groundwork adds:
|
||||
|
||||
- `IdentityRef`
|
||||
- `OrganizationUnitRef`
|
||||
- `FunctionRef`
|
||||
- `FunctionAssignmentRef`
|
||||
- `FunctionDelegationRef`
|
||||
- `AccessDecisionProvenance`
|
||||
- `AccessSemanticDirectory`
|
||||
- `AccessExplanationService`
|
||||
|
||||
Feature modules should consume those contracts instead of importing access ORM
|
||||
models. Storage, migration, and admin UI work can evolve behind the contract
|
||||
without changing module integrations.
|
||||
|
||||
## Required Explainability
|
||||
|
||||
Access decisions must be explainable in concrete terms:
|
||||
|
||||
- actor identity and account
|
||||
- tenant membership
|
||||
- organization unit
|
||||
- function assignment or group membership
|
||||
- role source
|
||||
- permission or right checked
|
||||
- delegation or acting-in-place context
|
||||
- policy, lock, or maintenance state that changed the result
|
||||
|
||||
This shape is required for role-bound postboxes, workflow authorization,
|
||||
service directory personalization, delegated administration, and audit review.
|
||||
|
||||
## Consumer Expectations
|
||||
|
||||
- Postbox can grant access to a role-bound or function-bound postbox without
|
||||
tying the postbox to a specific login account.
|
||||
- Portal/service directory can show services relevant to a user's current
|
||||
organization functions and tenant membership.
|
||||
- Workflow can ask whether the current account can act in a function context
|
||||
for a given organization unit.
|
||||
- Audit can show who acted, with which account, under which function, and
|
||||
whether delegation or acting-in-place was involved.
|
||||
|
||||
## Implementation Sequence
|
||||
|
||||
Implemented backend foundation:
|
||||
|
||||
- Kernel DTOs/protocols are covered by focused contract tests.
|
||||
- Access-owned storage exists for identities, account links, organization
|
||||
units, functions, function-role mappings, function assignments, and function
|
||||
delegations.
|
||||
- Admin APIs exist under `/api/v1/admin/identities`,
|
||||
`/api/v1/admin/organization-units`, `/api/v1/admin/functions`,
|
||||
`/api/v1/admin/function-assignments`, and
|
||||
`/api/v1/admin/function-delegations`.
|
||||
- `PrincipalRef` population includes identity, role, function assignment, and
|
||||
delegation identifiers when those facts exist.
|
||||
- The access manifest registers `access.semanticDirectory` and
|
||||
`access.explanation` capabilities.
|
||||
|
||||
Remaining rollout:
|
||||
|
||||
1. Move canonical identity and organization reads to `identity.directory` and
|
||||
`organizations.directory`, keeping access-owned rows as a compatibility
|
||||
projection until migration is complete.
|
||||
2. Add dedicated WebUI management panels for identities, organization units,
|
||||
functions, assignments, and delegations.
|
||||
3. Add explicit acting-in-place context selection; `act_in_place` delegation
|
||||
facts are stored now but do not silently grant permissions without a selected
|
||||
acting context.
|
||||
4. Retrofit postbox, workflow, portal, and audit consumers to use identity,
|
||||
organization, and access explanation capabilities rather than local access
|
||||
assumptions.
|
||||
97
docs/OPENDESK_IDENTITY_BOUNDARY.md
Normal file
97
docs/OPENDESK_IDENTITY_BOUNDARY.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# OpenDesk Identity Integration Boundary
|
||||
|
||||
OpenDesk-style identity integrations should terminate in `govoplan-access` as
|
||||
canonical accounts, tenant memberships, groups, roles, sessions, and principal
|
||||
claims. Provider protocol details may live in access subpackages or dedicated
|
||||
connector modules, but other GovOPlaN modules must consume identity through
|
||||
access capabilities, typed DTOs, events, and published route dependencies.
|
||||
|
||||
## Boundary Decision
|
||||
|
||||
`govoplan-access` owns the identity projection and authorization effects:
|
||||
|
||||
- external identity links for accounts and memberships
|
||||
- authentication callback/session issuance for federated login
|
||||
- claim, group, and role mapping into access-owned roles and memberships
|
||||
- SCIM-style provisioning effects for accounts, users, groups, and group
|
||||
membership
|
||||
- account suspension/deactivation effects that influence sessions and API keys
|
||||
- audit-relevant identity events emitted through kernel event/audit contracts
|
||||
|
||||
Connector packages may own provider-specific transport and schema logic:
|
||||
|
||||
- LDAP and Active Directory bind/search/sync adapters
|
||||
- OIDC and SAML provider metadata, callback protocol handling, and claim
|
||||
normalization
|
||||
- SCIM client/server protocol specifics
|
||||
- Open-Xchange identity lookup or provisioning clients
|
||||
|
||||
Those connectors should call access capabilities or access-owned service APIs
|
||||
instead of writing access tables directly.
|
||||
|
||||
## Integration Types
|
||||
|
||||
### LDAP And Active Directory
|
||||
|
||||
LDAP/AD adapters may authenticate credentials, search directory entries, and
|
||||
sync group membership. Access owns the resulting account, membership, group,
|
||||
and role mapping. Directory groups should map to access groups or role
|
||||
assignments through explicit mapping rules; they should not grant feature
|
||||
module permissions directly.
|
||||
|
||||
### OIDC And SAML
|
||||
|
||||
OIDC/SAML adapters may handle provider metadata, assertions, tokens, and claim
|
||||
normalization. Access owns external subject linking, session creation, tenant
|
||||
selection, first-login behavior, and claim-to-role/group mapping. Feature
|
||||
modules should see only `PrincipalRef`, `UserRef`, scopes, group IDs, and
|
||||
tenant context.
|
||||
|
||||
### SCIM Provisioning
|
||||
|
||||
SCIM provisioning belongs at the access boundary because it mutates accounts,
|
||||
memberships, groups, and deactivation state. Tenant resolution remains a kernel
|
||||
or tenancy capability concern. SCIM must not provision mailboxes, calendars,
|
||||
campaign ownership, or file spaces directly; those modules may react to
|
||||
access-published identity events when needed.
|
||||
|
||||
### Open-Xchange Touchpoints
|
||||
|
||||
Open-Xchange identity/contact integration should split identity from
|
||||
collaboration data:
|
||||
|
||||
- Access owns external account IDs, email/display-name identity fields,
|
||||
membership state, group references, and auth/session effects.
|
||||
- Mail, calendar, contacts, or connector modules own mailboxes, address books,
|
||||
calendar resources, contact folders, and provider-specific collaboration
|
||||
objects.
|
||||
|
||||
Access may publish identity-change events and stable DTOs that those modules
|
||||
consume, but it should not import their internals or own their provider data.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
Access does not own:
|
||||
|
||||
- campaign ACLs, campaign ownership, delivery policy, or recipient contacts
|
||||
- file storage permissions beyond principal/group identity references
|
||||
- mail profile credentials, mailbox state, or reusable mail-server profiles
|
||||
- calendar availability, appointments, rooms, or contact address books
|
||||
- provider-specific UI panels for non-identity configuration
|
||||
|
||||
Those belong to their owning modules and should integrate through capabilities
|
||||
or events.
|
||||
|
||||
## Implementation Shape
|
||||
|
||||
Provider integration should be added in small slices:
|
||||
|
||||
1. Define an access-owned external identity link model and DTO surface.
|
||||
2. Add provider adapter contracts that normalize external subjects, groups,
|
||||
claims, and deactivation signals.
|
||||
3. Route OIDC/SAML login callbacks through access so sessions are issued by
|
||||
the access session service.
|
||||
4. Route LDAP/AD/SCIM provisioning through access administration services and
|
||||
tenant provisioning capabilities.
|
||||
5. Publish identity-change events for optional mail/calendar/contact/file
|
||||
reactions without adding module-to-module imports.
|
||||
Reference in New Issue
Block a user