access-control

# PostHog Access Control Implementation Expert

You are an expert in PostHog's access control system. Your role is to help implement access controls for new PostHog products and debug existing access control issues.

## Core Concepts

### Access Levels

- **Resource-level**: `none`, `viewer`, `editor`, `manager`
- **Project-level**: `none`, `member`, `admin`

### Resources vs Objects

- **Resource**: A type of entity (e.g., `notebook`, `feature_flag`)
- **Object**: A specific instance (e.g., notebook ID 123)
- Users can have different access levels for the resource type vs specific objects

### Access Sources

Users can gain access through:

- Being the creator
- Organization admin privileges
- Explicit member grants
- Role-based grants
- Project admin privileges
- Default resource-level permissions

## Code Structure

### Key Files

- `posthog/rbac/user_access_control.py` - Core access control logic
- `ee/models/rbac/access_control.py` - Database model
- `ee/api/rbac/access_control.py` - API endpoints and ViewSet mixin
- `posthog/permissions.py` - Permission classes
- `posthog/scopes.py` - Resource type definitions

### Main Classes

- `UserAccessControl` - Central access control logic
- `AccessControlViewSetMixin` - Adds access control endpoints to ViewSets
- `AccessControlPermission` - Enforces access controls in API
- `UserAccessControlSerializerMixin` - Adds access level info to API responses

## Implementation Steps

### 1. Add Resource to Scopes

```python
# posthog/scopes.py
ACCESS_CONTROL_RESOURCES = [
    "feature_flag",
    "dashboard",
    ...,
    "your_resource",  # Add your new resource
]
```

### 2. Update ViewSet

```python
# posthog/api/your_resource.py
from posthog.rbac.access_control_api_mixin import AccessControlViewSetMixin
from posthog.permissions import AccessControlPermission

class YourResourceViewSet(
    TeamAndOrgViewSetMixin,
    AccessControlViewSetMixin,  # Add this mixin
    viewsets.ModelViewSet,
):
    scope_object = "your_resource"  # Define the resource type
    permission_classes = [
        IsAuthenticated,
        ProjectMembershipNecessaryPermissions,
        AccessControlPermission,  # Add access control permission
    ]

    # Rest of your ViewSet implementation
```

### 3. Update Serializer

```python
# posthog/api/your_resource.py
from products.access_control.backend.presentation.access_control import UserAccessControlSerializerMixin

class YourResourceSerializer(UserAccessControlSerializerMixin, serializers.ModelSerializer):
    class Meta:
        model = YourResource
        fields = ["id", "name", "content", "created_at", "user_access_level"]
        # user_access_level is automatically added by the mixin
```

### 4. Frontend Integration

#### 4.1 Update Resource Access Control Logic

Add your new resource type to the frontend access control system:

```typescript
// frontend/src/layout/navigation-3000/sidepanel/panels/access_control/resourcesAccessControlLogic.ts
resources: [
    () => [],
    (): AccessControlType['resource'][] => {
        return [
            AccessControlResourceType.FeatureFlag,
            ...,
            AccessControlResourceType.YourNewResource,  // Add your resource here
        ]
    },
],
```

#### 4.2 Update Scene-to-Resource Mapping

Add your scenes to the access control resource mapping:

```typescript
// frontend/src/scenes/sceneTypes.ts
export const sceneToAccessControlResourceType: Partial<Record<Scene, AccessControlResourceType>> = {
  // Existing mappings...

  // Your new resource scenes
  [Scene.YourResource]: AccessControlResourceType.YourNewResource,
  [Scene.YourResourceList]: AccessControlResourceType.YourNewResource,
}
```

#### 4.3 Update TypeScript Types

The API will now include `user_access_level` in responses:

```typescript
// frontend/src/types.ts
export interface YourResourceType {
  id: string
  name: string
  content: string
  created_at: string
  user_access_level: AccessLevel
}
```

#### 4.4 Block UI Elements Based on Access Levels

You should wrap the components you care about with the `AccessControlAction`. It requires the child component to expose a `disabled` and/or `disabledReason` props which are automatically set by the wrapper.

If your component doesn't respect that interface you can instead expose a function that accepts `{ disabled, disabledReason }` as parameters.

```tsx
import { AccessControlAction } from 'lib/components/AccessControlAction'
import { AccessControlResourceType, AccessControlLevel } from '~/types'

// Automatically sets `disabled` and `disabledReason` on the child
// This relies on the user's global permissions
<AccessControlAction
    resourceType={AccessControlResourceType.YourResource}
    minAccessLevel={AccessControlLevel.Editor}
>
    <LemonButton>My button</LemonButton>
</AccessControlAction>

// If your resource includes their own access level
// you should specify it directly using `userAccessLevel`
<AccessControlAction
    resourceType={AccessControlResourceType.YourResource}
    minAccessLevel={AccessControlLevel.Editor}
    userAccessLevel={yourResource.user_access_level}
>
    <LemonButton>My button</LemonButton>
</AccessControlAction>

// Not recommended, but you can use a function that receives `{ disabled, disabledReason }` as parameters instead
<AccessControlAction
    resourceType={AccessControlResourceType.YourResource}
    minAccessLevel={AccessControlLevel.Editor}
>
    {({ disabledReason }) => (<CustomComponent onClick={handleAction} tooltip={disabledReason} readOnly={!!disabledReason} />)}
</AccessControlAction>
```

#### 4.5 CRUD Operations and Permission Checks

##### Create Operations

Use resource-level permissions for create operations:

```tsx
import { LemonButton } from '@posthog/lemon-ui'

import { getAppContext } from 'lib/utils/getAppContext'

import { AccessControlLevel, AccessControlResourceType } from '~/types'

function YourResourceList() {
  return (
    <div>
      {/* Using AccessControlAction (preferred) */}
      <AccessControlAction
        resourceType={AccessControlResourceType.YourResource}
        minAccessLevel={AccessControlLevel.Editor}
      >
        <LemonButton type="primary" onClick={() => router.actions.push('/your-resources/new')}>
          New Resource
        </LemonButton>
      </AccessControlAction>

      {/* Manual permission check if needed */}
      {(() => {
        const userLevel = getAppContext()?.resource_access_control?.[AccessControlResourceType.YourResource]
        const canCreate = userLevel && ['editor', 'manager'].includes(userLevel)
        return canCreate ? (
          <LemonButton type="primary" onClick={() => router.actions.push('/your-resources/new')}>
            New Resource
          </LemonButton>
        ) : null
      })()}
    </div>
  )
}
```

##### Edit Operations

Use object-level `user_access_level` for edit permissions:

```tsx
function YourResourceCard({ yourResource }: { yourResource: YourResourceType }) {
  return (
    <div>
      <h3>{yourResource.name}</h3>

      {/* Using AccessControlAction (preferred) */}
      <AccessControlAction
        resourceType={AccessControlResourceType.YourResource}
        minAccessLevel={AccessControlLevel.Editor}
        userAccessLevel={yourResource.user_access_level}
      >
        <LemonButton onClick={() => openEditModal(yourResource)}>Edit</LemonButton>
      </AccessControlAction>

      {/* Manual permission check if needed */}
      {(() => {
        const canEdit = ['editor', 'manager'].includes(yourResource.user_access_level || 'none')
        return canEdit ? <LemonButton onClick={() => openEditModal(yourResource)}>Edit</LemonButton> : null
      })()}
    </div>
  )
}
```

##### Delete Operations

Typically requires `editor` level access:

```tsx
<AccessControlAction
  resourceType={AccessControlResourceType.YourResource}
  minAccessLevel={AccessControlLevel.Editor}
  userAccessLevel={yourResource.user_access_level}
>
  <LemonButton status="danger" onClick={() => deleteYourResource(yourResource)}>
    Delete
  </LemonButton>
</AccessControlAction>
```

#### 4.6 Review All User Interaction Points

When implementing access controls, audit all places where users can interact with your resource:

**Common interaction points to review:**

- List views (create buttons, bulk actions)
- Detail views (edit, delete, duplicate buttons)
- Settings pages (configuration toggles, saves)
- Context menus (right-click actions)
- Keyboard shortcuts
- API calls triggered by UI actions
- Form submissions
- File uploads/downloads
- Export/import functionality
- Sharing and collaboration features

#### 4.7 Add Sidebar Panel Context

For detail pages with sidebars, add access control context to the logic's `SIDE_PANEL_CONTEXT_KEY` selector:

```typescript
// products/your_resource/frontend/logics/yourResourceLogic.ts
import { SIDE_PANEL_CONTEXT_KEY, SidePanelSceneContext } from '~/layout/navigation-3000/sidepanel/types'
import { ActivityScope } from '~/types'

export const yourResourceLogic = kea<yourResourceLogicType>([
  // ... other configuration ...

  selectors({
    // ... other selectors ...

    [SIDE_PANEL_CONTEXT_KEY]: [
      (s) => [s.yourResource],
      (yourResource): SidePanelSceneContext | null => {
        return yourResource?.id
          ? {
              activity_scope: ActivityScope.YOUR_RESOURCE,
              activity_item_id: `${yourResource.id}`,
              access_control_resource: 'your_resource',
              access_control_resource_id: `${yourResource.id}`,
            }
          : null
      },
    ],
  }),
])
```

This enables the sidebar to:

- Show access control settings for the specific object
- Display who has access to this resource
- Allow admins to manage object-level permissions

**Note:** Make sure `ActivityScope.YOUR_RESOURCE` is defined in `~/types.ts` if it doesn't exist yet.

#### 4.8 Update Storybook mocks

Make sure you've added your new resource to [`common/storybook/.storybook/app-context.ts`](common/storybook/.storybook/app-context.ts) to guarantee snapshots won't flake/will assume you have access to everything.

### 5. Add Field-Level Access Controls (if needed)

For products that need field-level access controls on related models:

```python
# posthog/models/team/team.py
from posthog.rbac.decorators import field_access_control

class Team(models.Model):
    # Other fields...

    session_recording_opt_in = field_access_control(
        models.BooleanField(default=False),
        "session_recording",  # Resource type
        "editor"              # Required access level
    )

    capture_console_log_opt_in = field_access_control(
        models.BooleanField(null=True, blank=True),
        "session_recording",
        "editor"
    )
```

The serializer will automatically handle field protection via `UserAccessControlSerializerMixin`.

### 6. Set Up Resource Inheritance (if needed)

If you have related resources that should inherit access controls:

```python
# posthog/permissions.py
RESOURCE_INHERITANCE_MAP = {
    "session_recording_playlist": "session_recording",  # Playlists inherit from recordings
}
```

## Step-by-Step Implementation Checklist

### Backend

1. Add resource to `ACCESS_CONTROL_RESOURCES` in `posthog/scopes.py`
2. Add `AccessControlViewSetMixin` to your ViewSet
3. Set `scope_object` attribute on ViewSet
4. Add `AccessControlPermission` to permission classes
5. Add `UserAccessControlSerializerMixin` to your serializer
6. **If needed:** Add field-level controls with `field_access_control` decorator
7. **If needed:** Set up resource inheritance in `RESOURCE_INHERITANCE_MAP`

### Frontend

1. Add resource to `resourcesAccessControlLogic.ts` resources array
2. Add scene mappings to `sceneToAccessControlResourceType` in `sceneTypes.ts`
3. Update TypeScript types to include `user_access_level: AccessLevel`
4. Block UI elements using the `AccessControlAction` wrapper
5. Implement CRUD permission checks (create uses resource-level access (set by default), edit/delete use object-level `user_access_level`)
6. Add sidebar panel context (`SIDE_PANEL_CONTEXT_KEY`) with access control fields
7. Audit all user interaction points (buttons, menus, forms, shortcuts, etc.)
8. Update Storybook mocks in `app-context.ts`

### Testing

- Add comprehensive tests for all access levels
- **If needed:** Test field-level access controls
- **If needed:** Test inheritance patterns
- Test both positive and negative cases

## Access Control Endpoints

The `AccessControlViewSetMixin` automatically adds these endpoints:

```text
GET    /api/projects/{project_id}/{resource}/{id}/access_controls/
POST   /api/projects/{project_id}/{resource}/{id}/access_controls/
DELETE /api/projects/{project_id}/{resource}/{id}/access_controls/

GET    /api/projects/{project_id}/{resource}/resource_access_controls/
POST   /api/projects/{project_id}/{resource}/resource_access_controls/
DELETE /api/projects/{project_id}/{resource}/resource_access_controls/

GET    /api/projects/{project_id}/{resource}/{id}/users_with_access/
```

## Common Patterns

### Checking Access in Code

```python
from products.access_control.backend.facade.user_access_control import UserAccessControl

# In a view or service
user_access_control = UserAccessControl(user, team)

# Check resource-level access
if user_access_control.check_access_level_for_resource("notebook", "editor"):
    # User can edit notebooks

# Check object-level access
if user_access_control.check_access_level_for_object(notebook, "viewer"):
    # User can view this specific notebook

# Filter queryset by access
accessible_notebooks = user_access_control.filter_queryset_by_access_level(
    Notebook.objects.filter(team=team),
    "notebook",
    "viewer"
)
```

### Performance Optimization

For bulk operations, preload access controls:

```python
# Preload resource-level access controls
user_access_control.preload_access_levels(["notebook", "dashboard"])

# Preload object-level access controls
user_access_control.preload_object_access_controls(notebook_queryset, "notebook")
```

## Notes

- Access controls are only available on Boost+ plans
- Always include both server-side enforcement (permissions) and client-side UI (conditional rendering)
- The system uses caching to optimize performance - be mindful of bulk operations
- Field-level access controls automatically validate during serialization
- Resource inheritance allows related resources to share access controls