Add Groups as Principals

[shangyian]

Summary

We should add support for groups as a principal type, so that they can be referenced alongside users and service accounts. This provides the foundation for team-based access control and organizational structure.

Currently, DJ supports two principal types:

• users for individual people
• service accounts for automated systems

This is insufficient for real-world scenarios where teams need shared ownership of nodes, and orgs may want to structure access by department or project. Adding groups also enables future access control features while remaining useful on its own for organizational purposes.

Proposed Solution

Add GROUP to PrincipalType (just like users and service accounts). A GROUP principal can:

• own nodes
• be assigned as node owners
• have members (users and service accounts)

Groups store basic metadata (e.g., name, email, description) in DJ's metadata database, but membership resolution is pluggable to support different deployment scenarios.

Why Pluggable Membership?

Different organizations organize membership in different ways: some rely on simple application-level tables, while others use cloud IAM groups or external identity providers like Okta. Making membership resolution pluggable allows DJ to work standalone with its own Postgres-backed membership provider, while also integrating cleanly with other custom enterprise identity implementations.

graph LR
    subgraph "OSS"
        A1[API Request]
        A2[GroupMembershipService]
        A3[(Postgres:<br/>GroupMembers)]
        
        A1 --> A2
        A2 --> A3
        A3 -->|Found in table| A2
        A2 --> A1
    end
    subgraph "Enterprise"
        B1[API Request]
        B2[GroupMembershipService]
        B3[(Postgres:<br/>GroupMembers<br/>NOT USED)]
        B4[(External:<br/>Custom)]
        
        B1 --> B2
        B2 -.->|Skip| B3
        B2 --> B4
        B4 -->|Found in IdP| B2
        B2 --> B1
        
        style B3 fill:#ffcdd2
    end

OSS ~~~ Enterprise
linkStyle 6 stroke:none

Loading

API Endpoints

Group Discovery

GET    /groups                     # List available groups
GET    /groups/{id}                # Get group details
POST   /groups/register            # Register a group

Membership Management (OSS provider only)

GET    /groups/{id}/members        # List members
POST   /groups/{id}/members        # Add member
DELETE /groups/{id}/members/{uid}  # Remove member
GET    /users/{id}/groups          # Get groups user belongs to

Important: Membership management endpoints (POST/DELETE /groups/{id}/members) only work with the OSS provider. For external providers, membership is managed in the external system.