81 lines
4.3 KiB
Markdown
81 lines
4.3 KiB
Markdown
<!-- SPDX-License-Identifier: MPL-2.0 -->
|
|
|
|
# Organizations and scoped access
|
|
|
|
One `auth.User` may belong to many organizations without creating another
|
|
credential or browser session. Organizations own projects; projects own
|
|
environments; environments own application services. Teams are optional groups
|
|
of active organization members.
|
|
|
|
`organizations.Service` creates those resources and issues digest-backed,
|
|
expiring, single-use invitations. An invitation may carry one direct role and
|
|
up to sixteen reviewed team memberships. Acceptance verifies that the
|
|
authenticated user's normalized email matches and applies the membership,
|
|
role, teams, consumption marker, and audit event in one transaction.
|
|
Applications own invitation pages, email or out-of-band delivery, active-source
|
|
checks before archival, and account recovery.
|
|
|
|
Organizations and teams use optimistic revisions and reversible
|
|
`active`/`archived` states. Archived objects keep their history but contribute
|
|
no effective authority. Memberships may be suspended, reactivated, or removed;
|
|
team membership can be removed independently. Configure `OwnerRole` when
|
|
constructing the service before exposing membership-removal operations. The
|
|
SQLite adapter then refuses to suspend or remove the final active direct owner.
|
|
|
|
Fresh-authentication administration pages should use
|
|
`ChangeMembershipStatus` and `RemoveMembershipIfCurrent`, passing the exact
|
|
displayed state as `ExpectedStatus`. The SQLite adapter acquires its write lock
|
|
before checking that state, verifies the actor is still an active member of an
|
|
active organization, and commits the lifecycle effects and audit together.
|
|
Suspension removes team memberships; reactivation does not infer or restore
|
|
them. Removal also revokes current direct bindings. A repository without the
|
|
optimistic extension fails closed instead of falling back to a stale mutation.
|
|
|
|
For a reviewed access-administration page, use `organizations.Members` to list
|
|
bounded active and suspended memberships, and
|
|
`access.OrganizationUserBindings` to list only current direct,
|
|
organization-wide user roles. The latter intentionally excludes team grants
|
|
and project, environment, or service bindings. Replace a member's direct role
|
|
with `access.ReplaceOrganizationUserRole`, passing the exact displayed binding
|
|
IDs as `ExpectedBindingIDs`. The SQLite adapter serializes that replacement,
|
|
rejects stale state, writes the new binding and audit event atomically, and
|
|
will not demote the final active direct owner. The application must still
|
|
authorize the administrator and bind any required fresh passkey assertion to
|
|
the organization, target user, target role, and expected IDs.
|
|
|
|
`access.Service` evaluates a permission against a complete resource scope:
|
|
|
|
```go
|
|
decision, err := accessService.Authorize(ctx, principal.User.ID, access.Scope{
|
|
OrganizationID: organizationID,
|
|
ProjectID: projectID,
|
|
EnvironmentID: environmentID,
|
|
ServiceID: serviceID,
|
|
}, "telemetry.read")
|
|
```
|
|
|
|
A binding at organization scope covers its descendants. A narrower binding
|
|
covers only its matching branch. The repository resolves team membership; a
|
|
handler must never accept caller-supplied team identifiers as authority.
|
|
|
|
Platform roles in `auth.Principal` remain useful for installation health,
|
|
account administration, and other explicitly global operations. They do not
|
|
grant organization-data access. If an operator must inspect tenant data during
|
|
an incident, use a reasoned break-glass grant. It expires within one hour and
|
|
creates an append-only audit event in the same transaction.
|
|
|
|
An application that offers owner-assisted account recovery must not infer that
|
|
authority from a broad administration page. Use the dedicated
|
|
`authrecovery.IssueAssistedRecovery` boundary after an operation-bound passkey
|
|
assertion. The SQLite adapter requires a current active direct owner binding
|
|
and active target membership in the same transaction that invalidates the old
|
|
credentials and records the organization-visible recovery audit. Team,
|
|
break-glass, platform, and merely descriptive roles do not satisfy this owner
|
|
check.
|
|
|
|
The SQLite adapter namespaces all tables, enforces active organization and team
|
|
membership plus resource ancestry before accepting or evaluating a binding,
|
|
and keeps invitations and sessions as digests. Applications remain responsible
|
|
for database backup, filesystem ownership, retention, and presenting audit
|
|
history to organization owners.
|