UX Patterns Guide
UI + UX Trust, Safety, And Privacy established

Permission sharing

Provide a permission sharing surface that exposes direct and inherited grants, users and groups, role meanings, effective access, pending changes, risky grants, approval or confirmation needs, audit context, and complete revoke paths before access is changed.

Open in lab Compare alternatives
Decision first

Choose this pattern when the problem matches

Use when

  • Owners or admins need to manage durable access to spaces, sites, repositories, projects, folders, datasets, boards, environments, or sensitive objects.
  • Access can come from direct grants, groups, teams, inheritance, guests, anonymous users, service accounts, deploy keys, or custom roles.
  • Users need to understand effective access and revoke outcomes, not only send a link or invite.
  • The product must support least-privilege review, auditability, approval, or policy enforcement for permission changes.

Avoid when

  • The task is quick one-object sharing with a link or a few recipients and no broader permission model.
  • The user is requesting access after denial rather than administering access.
  • The current user lacks authority to grant, change, or revoke permissions.
  • The only needed interaction is selecting a person or group without changing access.
  • The permission model cannot reliably calculate effective access or enforce revocation from this surface.

Problem it prevents

Permission administration is risky when products hide group inheritance, effective access, role capabilities, connected-team membership, anonymous access, service credentials, or revoke outcomes behind a simple share or remove control.

Test the behavior

Open the interactive example when you need it

The full lab is intentionally loaded on request. That keeps this reading page fast while preserving the strong and weak states, keyboard checks, and failure scenarios.

In the lab you can
  • switch between strong UI, weak UI, strong UX, and weak UX;
  • trigger required, empty, loading, error, and recovery states;
  • inspect keyboard and accessibility expectations beside the demo.
Launch Permission sharing in the lab
Pattern anatomy

What a strong implementation has to make clear

User need

The resource has durable authorization rules such as roles, groups, teams, guests, anonymous users, parent inheritance, folder scope, repository roles, space permissions, service accounts, or keys.

Pattern promise

Provide a permission sharing surface that exposes direct and inherited grants, users and groups, role meanings, effective access, pending changes, risky grants, approval or confirmation needs, audit context, and complete revoke paths before access is changed.

Required state

Default access list state with users, groups, guests, anonymous access, roles, and effective access.

Recovery path

A user keeps access through a group after their direct row is removed.

Access contract

Use labelled tables or grids with column headers for principal, source, role, capability, status, and actions.

Quality bar

The difference between expert and weak execution

Strong implementation

Specific, visible, recoverable

  • A repository access page lists teams, outside collaborators, deploy keys, and direct users with Read, Triage, Write, Maintain, and Admin roles, showing that only Admin can manage access.
  • A space permissions page shows Users, Groups, Guests, and Anonymous access tabs with View, Add, Delete, Export, Restrictions, and Admin columns plus an Effective access summary for selected people.
  • A site owner adds the Finance Reviewers group as Visitors, sees that Members can contribute content, confirms no anonymous access is enabled, and saves with an audit note.
  • A space admin removes Maya from a direct grant but sees she still has View through the Contractors group, so they remove the group grant or ask a site admin to update group membership.
Weak implementation

Vague, hidden, hard to recover from

  • A permissions page shows only individual names and Remove buttons even though group membership and parent folder inheritance still grant access.
  • A checkbox matrix lets admins grant Export and Space Admin without explaining the data exposure or requiring a high-risk review.
  • An owner downgrades a user to Viewer, but the user keeps edit rights through a connected team and the UI never explains effective access.
  • A repository admin removes a collaborator but forgets a deploy key with write access because the access page treated machine credentials as unrelated settings.
UI guidance
  • Render permission sharing as an access-management surface with the protected resource, current direct grants, inherited grants, groups, guests, anonymous or link access, role or permission level, effective access, pending changes, and revoke or save actions.
  • Make the permission model visible before saving: users should see whether access comes from a direct grant, group membership, parent scope, connected team, service account, deploy key, anonymous access, or owner/admin role.
UX guidance
  • Use permission sharing when authorized owners or admins need to grant, change, audit, or revoke durable access to a space, site, repository, folder, project, board, dataset, environment, or sensitive object.
  • Protect least privilege by showing what each role allows, why a person or group still has access, what will change after save, which changes require review, and which grants cannot be removed from this surface.
Implementation contract

What the implementation must handle

States

  • Default access list state with users, groups, guests, anonymous access, roles, and effective access.
  • Direct grant, inherited grant, group membership, connected-team membership, service-account, deploy-key, and anonymous-access states.
  • Add user or group state with entity lookup, duplicate detection, role selection, and policy checks.
  • Role change state with before and after capabilities.

Interaction

  • Opening the permission sharing surface loads direct grants, inherited grants, group or team grants, anonymous access, service credentials, and owner or admin constraints before edits are saved.
  • Adding a user or group requires a resolved entity, role, scope, and policy check before it creates an access grant.
  • Changing a role shows the previous role, new role, key capabilities, and whether the change broadens or narrows access.
  • Removing a row checks whether effective access remains through another route and labels any remaining group, parent, service, or anonymous grant.

Accessibility

  • Use labelled tables or grids with column headers for principal, source, role, capability, status, and actions.
  • Expose direct, inherited, group, anonymous, service-account, pending, blocked, and remaining-access states as text, not icon or color alone.
  • Give role menus accessible descriptions that include the role's main capabilities and whether the change broadens access.
  • Associate remaining-access warnings with the revoke action and affected principal.

Review

  • What are all active routes by which a person, group, guest, anonymous user, service account, or key can access this resource?
  • Can users tell the difference between direct access and inherited or group access?
  • What does each role allow in task terms, and which actions are risky?
  • Who gains access, who loses access, and who keeps access after the pending change?
Evidence trail

Source-backed claims behind this guidance

Full agent/debug reference

Problem Context

  • The resource has durable authorization rules such as roles, groups, teams, guests, anonymous users, parent inheritance, folder scope, repository roles, space permissions, service accounts, or keys.
  • The user is an owner, admin, space admin, repository admin, site owner, project maintainer, data steward, or delegated access manager.
  • Permission changes may apply to many objects, cascade through inheritance, affect connected services, expose confidential data, or remove a person's only route to work.
  • The system may need audit evidence, approval, expiration, policy checks, inherited access explanation, and no-disclosure treatment for sensitive resources.

Selection Rules

  • Choose permission sharing when users manage durable access grants, role assignments, group permissions, effective access, inheritance, anonymous access, or revocation for a protected resource.
  • Use share dialog for quick object-level sharing with recipients, link scope, notification, and copy-link behavior.
  • Use invite user when access starts through a pending workspace, organization, team, or tenant invitation lifecycle.
  • Use permission recovery when a denied user asks an owner or admin to grant access; permission sharing is the owner-facing grant and revoke surface.
  • Use permission denied state when the user only needs to understand why they cannot access or perform an action.
  • Use approval workflow when the permission change requires an approver or policy decision before it is applied.
  • Use review before submit or confirmation dialog for public, anonymous, admin, export, delete, inherited-access break, service-account, deploy-key, and bulk-removal changes.
  • Include direct access, inherited access, group access, guest access, anonymous access, service credentials, owner/admin roles, and effective access where those routes exist.
  • Show role capabilities in task language such as view, comment, add, edit, delete, export, manage access, administer, or approve.
  • Do not claim access is revoked until every active route to access is removed or explicitly named as still active.

Required States

  • Default access list state with users, groups, guests, anonymous access, roles, and effective access.
  • Direct grant, inherited grant, group membership, connected-team membership, service-account, deploy-key, and anonymous-access states.
  • Add user or group state with entity lookup, duplicate detection, role selection, and policy checks.
  • Role change state with before and after capabilities.
  • Pending changes review state that names who gains, loses, or keeps access.
  • High-risk grant state for Admin, Owner, Space Admin, Full Control, anonymous access, public access, export, delete, or manage-access permissions.
  • Revoke state that detects remaining access through groups, parent scopes, keys, or connected services.
  • Approval required, policy blocked, inherited read-only, save failed, audit note required, and saved states.
  • Bulk edit, long list, filter, search, sort, empty, loading, and permission-limited states.
  • Mobile condensed state where role capability and effective access remain readable.

Interaction Contract

  • Opening the permission sharing surface loads direct grants, inherited grants, group or team grants, anonymous access, service credentials, and owner or admin constraints before edits are saved.
  • Adding a user or group requires a resolved entity, role, scope, and policy check before it creates an access grant.
  • Changing a role shows the previous role, new role, key capabilities, and whether the change broadens or narrows access.
  • Removing a row checks whether effective access remains through another route and labels any remaining group, parent, service, or anonymous grant.
  • High-risk grants and removals require review, confirmation, approval, or audit note according to policy.
  • Saving produces a clear result that distinguishes applied, pending approval, blocked, partial, and failed permission changes.
  • The access list updates after save and preserves enough context for users to verify who can still access the resource.
  • Audit records capture actor, resource, affected principal, old role, new role, source of access, timestamp, reason, approval, and policy outcome.

Implementation Checklist

  • Define the permission graph: direct grants, groups, teams, guests, anonymous users, link grants, parent inheritance, service accounts, deploy keys, roles, custom roles, owners, admins, and policy constraints.
  • Compute effective access separately from direct rows and expose why each person or group can view, edit, export, delete, manage access, or administer.
  • Build role descriptions, capability previews, before/after summaries, duplicate checks, inherited-read-only labels, and remaining-access warnings.
  • Implement add, role change, revoke, bulk change, search, filter, sort, save, approval, audit note, cancel, retry, and rollback paths.
  • Protect risky operations such as anonymous access, public export, Full Control, Admin, owner transfer, deploy key write access, service-account grants, and group-wide removal with review or approval.
  • Test group overlap, inherited folder access, Teams or Microsoft 365 group connection, anonymous access, deploy keys, service accounts, owner-only controls, partial failures, long names, keyboard use, screen readers, and mobile wrapping.

Common Generated-UI Mistakes

  • Showing only direct users while group or inherited access remains active.
  • Using a share dialog as the only permission administration surface.
  • Hiding what a role can actually do until after it is assigned.
  • Letting users remove a visible row and believe access is gone when effective access still exists.
  • Treating service accounts, deploy keys, anonymous links, or connected teams as separate from human access review.
  • Saving high-risk admin, public, export, delete, or anonymous grants with no review, approval, or audit note.
  • Making bulk permission changes without before and after counts or rollback guidance.

Critique Questions

  • What are all active routes by which a person, group, guest, anonymous user, service account, or key can access this resource?
  • Can users tell the difference between direct access and inherited or group access?
  • What does each role allow in task terms, and which actions are risky?
  • Who gains access, who loses access, and who keeps access after the pending change?
  • What happens if the user removes a direct grant but effective access remains?
  • Which changes need confirmation, approval, audit note, expiry, or policy review?
  • Can the saved access state be proven later in an activity log or audit export?
Accessibility
  • Use labelled tables or grids with column headers for principal, source, role, capability, status, and actions.
  • Expose direct, inherited, group, anonymous, service-account, pending, blocked, and remaining-access states as text, not icon or color alone.
  • Give role menus accessible descriptions that include the role's main capabilities and whether the change broadens access.
  • Associate remaining-access warnings with the revoke action and affected principal.
  • Announce saved, pending approval, blocked, partial failure, and effective-access recalculation updates through status regions.
  • Keep add, search, filter, role change, remove, review, save, cancel, and audit-note controls keyboard reachable.
  • For permission matrices, provide row and column headers and avoid relying on empty checkbox grids without labels.
Keyboard Behavior
  • Tab order starts with resource summary, effective access summary, search/filter, add principal, permission table, pending changes, and save or cancel actions.
  • Permission tables support keyboard movement through rows and role controls without trapping focus.
  • Role selectors announce current role, new role, and whether the change adds or removes capabilities.
  • Removing a row moves focus to the remaining-access warning or next principal row.
  • High-risk confirmation returns focus to the changed permission if canceled and to pending changes if accepted.
  • After save, focus moves to the result summary and then back to the updated access list.
  • Bulk selection and matrix checkboxes expose selected counts and affected principals to assistive technology.
Variants
  • Role assignment table
  • Permission matrix
  • Effective access inspector
  • Group permissions
  • Space permissions
  • Repository access management
  • Site permissions
  • Anonymous access controls
  • Inherited permissions
  • Unique permissions
  • Service account access
  • Bulk permission edit

Verification

Source trail checked:

Saved items