Membership Service Deep Dive

📋Learning Objectives

• Understand Neo4j graph database concepts and why it's ideal for identity relationships
• Learn about Identity, Role, Group, and Resource entities
• Explore relationship hierarchies and inheritance patterns
• Create and query role assignments with location scoping
• Understand delegations and access reviews
• Use semantic/vector search for identity discovery
• Learn how Membership integrates with PDP as a Policy Information Point (PIP)

🎯Membership Service Overview

The Membership Service is the identity fabric of EmpowerNow — managing the complex web of relationships between users, roles, groups, resources, and organizational locations.

Core Capabilities

• Identity Management: Users, accounts, groups, and their attributes
• Role Management: Hierarchical roles with inheritance
• Location-Scoped Assignments: Role assignments bounded to organizational units
• Delegations: Time-bounded privilege delegation between users
• Access Reviews: Periodic certification of access rights
• Semantic Search: Vector-based identity and role discovery
• Policy Information Point: Provides user context to PDP for authorization decisions

🏛️Entity Model

The membership service manages these core entities:

Entity Types

• User: Individual identity (from IdP)
• Role: Permission container (Admin, Editor, Viewer)
• Group: Collection of users and/or other groups
• Location: Organizational unit (Department, Team, Project)

🔗Relationship Types

• HAS_ROLE: User has a role (direct assignment)
• MEMBER_OF: User or Group belongs to a Group
• INHERITS: Role inherits from parent role
• BELONGS_TO: Entity belongs to a location
• SCOPED_AT: Role assignment scoped to location

Location-Scoped Roles

A user can have different roles at different locations:

# Alice is Admin at Engineering, but Viewer at Marketing
(alice:User)-[:HAS_ROLE {location: "engineering"}]->(admin:Role)
(alice:User)-[:HAS_ROLE {location: "marketing"}]->(viewer:Role)

🔬Exercise 1: Access Neo4j Browser

1. Open http://localhost:7474
2. Connect with default credentials (neo4j/neo4j or as configured)
3. Explore the database schema

View Schema

// Show all node labels
CALL db.labels()

// Show all relationship types
CALL db.relationshipTypes()

// Visualize schema
CALL db.schema.visualization()

🔍Exercise 2: Query Users and Roles

// Find all users
MATCH (u:User) RETURN u.id, u.email, u.name LIMIT 10

// Find user's direct roles
MATCH (u:User {id: 'user-123'})-[:HAS_ROLE]->(r:Role)
RETURN r.name, r.description

// Find all roles (including inherited)
MATCH (u:User {id: 'user-123'})-[:HAS_ROLE|MEMBER_OF*]->(r:Role)
RETURN DISTINCT r.name

// Find users with specific role
MATCH (u:User)-[:HAS_ROLE]->(r:Role {name: 'admin'})
RETURN u.email, u.name

➕Exercise 3: Create Role Assignment via API

# Assign role to user
curl -k -X POST https://membership.self.empowernow.ai/api/v1/assignments \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "user_id": "user-123",
    "role_id": "editor",
    "location_id": "engineering",
    "expires_at": "2025-12-31T23:59:59Z"
  }'

Query User Roles via API

# Get user's effective roles
curl -k https://membership.self.empowernow.ai/api/v1/roles/user-123 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

🔄How PDP Uses Membership (PIP Integration)

When PDP evaluates a policy, it queries Membership for user context via the Policy Information Point (PIP) endpoint:

1. PDP receives authorization request with user ID
2. MembershipPIP queries Membership service at /api/v1/pip/membership/subject-enrichment
3. Membership returns effective roles, groups, delegations, and attributes
4. PDP evaluates policy with enriched subject context

PIP Endpoint Example

# Get enriched subject for PDP policy evaluation
curl -k "https://membership.self.empowernow.ai/api/v1/pip/membership/subject-enrichment?subject_id=user-123" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

🚀The Identity Graph Journey

Role Resolution Steps

1. Cache Check: Redis is checked first for the user's cached roles
2. Graph Traversal: On cache miss, Cypher query traverses HAS_ROLE and MEMBER_OF edges
3. Inheritance Resolution: Roles inherited through role hierarchy are collected
4. Delegation Merge: Active delegations are added to effective permissions
5. Location Scoping: Roles are filtered by the requested location context
6. Response + Cache: Results are cached and returned

🤝Delegations

Delegations allow users to temporarily grant their permissions to others — essential for vacation coverage, temporary assignments, and approval workflows.

Create a Delegation via API

# Create delegation
curl -k -X POST https://membership.self.empowernow.ai/api/v1/delegations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "delegator_id": "alice-uuid",
    "delegate_id": "bob-uuid",
    "permission": "approve_expense",
    "starts_at": "2026-01-15T00:00:00Z",
    "expires_at": "2026-02-01T00:00:00Z",
    "reason": "Vacation coverage"
  }'

🤖AI Agent Authorization

Why AI Agent Authorization Matters

• Identity Binding: Ensure an agent is truly acting for a specific user/service pair
• Delegation Clarity: Explicitly constrain what an agent can do (capabilities) and for how long
• Data Scope: Enforce tenant/row/column restrictions for safe RAG (Retrieval-Augmented Generation)
• Cost Control: Attach budget_usd and max_steps to bound spend and chain length
• Identity Chaining: Express eligibility for downstream provider tokens

The DELEGATES_TO Relationship

When a user delegates to an AI agent, the relationship carries rich metadata:

// User-to-Agent delegation in Neo4j
(user:User)-[:DELEGATES_TO {
    id: "delegation:user1-to-agent1",
    status: "active",              // active|paused|revoked|expired
    capabilities: ["mcp:flights:search", "mcp:flights:book"],
    budget_usd: 25.0,              // Max spend for this delegation
    max_steps: 5,                  // Max tool invocations
    valid_from: datetime(),
    expires_at: datetime("2026-02-01"),
    jkt: "sha256:abc123..."        // DPoP key thumbprint
}]->(agent:AIAgent)

PIP Endpoints for AI Authorization

{
  "aria_extensions": {
    "budget": { "unit": "usd", "amount": 25.0 },
    "max_steps": 5,
    "schema_pins": { "tool:flights": { "schema_hash": "sha256:..." } }
  }
}

📋Access Reviews

Access Review Workflow

1. Campaign Creation: Admin creates a review campaign targeting specific roles, groups, or all access
2. Reviewer Assignment: System assigns reviewers (typically managers) based on organizational hierarchy
3. Certification: Reviewers approve, revoke, or flag access for each assignment
4. Remediation: Revoked access is automatically removed; flagged items escalate
5. Audit: Complete audit trail of all decisions with timestamps and justifications

Access Review API

# Create an access review campaign
curl -X POST https://membership.self.empowernow.ai/api/v1/access-reviews \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "name": "Q1 2026 Engineering Access Review",
    "scope": {
      "location_id": "engineering",
      "role_types": ["admin", "editor"]
    },
    "due_date": "2026-02-15T23:59:59Z",
    "reviewer_assignment": "manager"
  }'

# Certify an access item
curl -X POST https://membership.self.empowernow.ai/api/v1/access-reviews/{id}/certify \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "item_id": "assignment-123",
    "decision": "approve",
    "justification": "User still needs Editor role for current project"
  }'

🔍Semantic Search

The Membership service includes vector-based semantic search — find identities, roles, and resources using natural language queries.

Unified Search Endpoint

# Search for identities matching a description
curl -k "https://membership.self.empowernow.ai/api/search/unified?query=engineers%20who%20can%20approve%20deployments&limit=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Identity Node Search

# Search by node type and filters
curl "https://membership.self.empowernow.ai/api/v1/identity_nodes/search?\
node_type=Person&search=John&system=active_directory&limit=10&skip=0"

# Search with metadata (includes total count, has_more flag)
curl "https://membership.self.empowernow.ai/api/v1/identity_nodes/search/with-metadata?\
node_type=Person&search=engineer&use_fulltext=true"

Full-Text Search Indexes

The Membership service maintains full-text indexes across identity properties:

• Labels indexed: Identity, Person, AIAgent, Group, Account
• Properties indexed: name, display_name, email, job_title, country, telephone
• Search modes: Substring (case-insensitive), Full-text with relevance scoring

📖Cypher Query Cookbook

Capability Check (User → Agent)

// What can this agent do for this user?
MATCH (u:User {id: $user_id})-[:DELEGATES_TO {status: 'active'}]->
      (d:Delegation)-[:BINDS]->(:AIAgent {id: $agent_id})
MATCH (d)-[:HAS_CAPABILITY]->(c:Capability)
WHERE d.expires_at IS NULL OR d.expires_at > datetime()
RETURN collect(DISTINCT c.id) AS capabilities

Data Scope (Tenant Resolution)

// What tenants can this user access?
MATCH (u:User {id: $subject_id})-[:BELONGS_TO]->(t:Tenant)
OPTIONAL MATCH (u)-[:ASSIGNED_TO]->(:Project)-[:OWNED_BY]->(tp:Tenant)
WITH collect(DISTINCT t.id) + collect(DISTINCT tp.id) AS tids
RETURN {
  tenant_ids: [x IN tids WHERE x IS NOT NULL],
  row_filter_sql: CASE WHEN size(tids) > 0
    THEN 'tenant_id IN (\'' + apoc.text.join(tids, '\',\'') + '\')'
    ELSE '1=0' 
  END
} AS scope

Chain Eligibility (For Identity Chaining)

// What downstream tokens can be obtained for this tool?
MATCH (u:User {id: $user_id})-[:DELEGATES_TO {status: 'active'}]->
      (:Delegation)-[:BINDS]->(:AIAgent {id: $agent_id})
      -[:HAS_CAPABILITY]->(:Capability)-[:CAN_INVOKE]->(tool:Tool {id: $tool_id})
MATCH (tool)-[:REQUIRES]->(app:SaaSApp)
RETURN collect({
  audience: app.audience, 
  scopes: app.scopes
}) AS chain_eligibility

ReBAC Walk: Expense Approval

// Can John approve this expense in cost center CC-100?
MATCH (u:User {id: $user_id})-[:MEMBER_OF]->(:Group)
      -[:ASSIGNED_TO]->(br:BusinessRole {name: 'ExpenseApprover'})
MATCH (br)-[:SCOPED_TO]->(cc:CostCenter {id: $cost_center_id})
MATCH (r:ExpenseReport {id: $report_id})-[:BELONGS_TO]->(cc)
RETURN r.id AS report_id LIMIT 1

Find Orphan Nodes

// Find identities with no relationships (potential cleanup)
MATCH (n:Identity)
WHERE NOT (n)-[]-()
RETURN n.id, labels(n) AS type, n.name
LIMIT 50

Path Analysis

// Find shortest path between two identities
MATCH path = shortestPath(
  (a:Identity {id: $from_id})-[*..10]-(b:Identity {id: $to_id})
)
RETURN path, length(path) AS hops

📚Key API Endpoints Reference

Identity Management

Roles & Assignments

Delegations & AI Agents

PIP Endpoints (for PDP)

Governance & Compliance

Reports & Diagnostics

🔬Hands-on Labs

CALL db.schema.visualization()

MATCH (n) RETURN labels(n)[0] as type, count(*) as count ORDER BY count DESC

MATCH (u:User)-[r]->(n) RETURN u, r, n LIMIT 25

// Show role inheritance tree
MATCH path = (child:Role)-[:INHERITS*]->(parent:Role)
RETURN child.name as child_role, 
       [n in nodes(path) | n.name] as inheritance_path
ORDER BY length(path) DESC

// Get admin role and all it inherits
MATCH (r:Role {name: 'admin'})-[:INHERITS*0..]->(inherited:Role)
RETURN DISTINCT inherited.name as role, inherited.permissions as permissions

// Alice's roles: direct, via groups, via inheritance
MATCH (u:User {id: 'alice'})
OPTIONAL MATCH directPath = (u)-[:HAS_ROLE]->(directRole:Role)
OPTIONAL MATCH groupPath = (u)-[:MEMBER_OF*]->(g:Group)-[:HAS_ROLE]->(groupRole:Role)
OPTIONAL MATCH inheritPath = (directRole)-[:INHERITS*]->(inheritedRole:Role)
RETURN DISTINCT 
    COALESCE(directRole.name, groupRole.name, inheritedRole.name) as role,
    CASE 
        WHEN directRole IS NOT NULL THEN 'direct'
        WHEN groupRole IS NOT NULL THEN 'via group'
        ELSE 'inherited'
    END as source

ACCESS_TOKEN=$(curl -s -X POST https://idp.self.empowernow.ai/api/oidc/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=bff-client" \
  -d "client_secret=YOUR_SECRET" \
  -d "scope=openid membership.write" | jq -r '.access_token')

echo $ACCESS_TOKEN

curl -X POST https://membership.self.empowernow.ai/api/v1/delegations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "delegator_id": "bob",
    "delegate_id": "alice",
    "permission": "approve_expense",
    "starts_at": "2026-01-01T00:00:00Z",
    "expires_at": "2026-02-01T00:00:00Z",
    "reason": "Training lab exercise"
  }' | jq .

// Find active delegations
MATCH (delegator:User)-[d:DELEGATES_TO]->(delegate:User)
WHERE d.expires_at > datetime()
RETURN delegator.id, delegate.id, d.permission, d.expires_at

curl -s "https://membership.self.empowernow.ai/api/v1/pip/membership/subject-enrichment?subject_id=alice" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq '.delegations'

🔧Troubleshooting Membership Issues

// Check all assignments for a user
MATCH (u:User {id: 'alice'})-[r:HAS_ROLE]->(role:Role)
RETURN role.name, r.location, r.expires_at, r.assigned_at

// Find cycles in role inheritance
MATCH path = (r:Role)-[:INHERITS*]->(r)
RETURN path

// Find cycles in group membership
MATCH path = (g:Group)-[:MEMBER_OF*]->(g)
RETURN path

❓Knowledge Check

📝Day 10 Checkpoint

• Understand why Neo4j is ideal for identity relationships
• Know all core entity types: Identity, Role, Group, Resource, Location
• Can query Neo4j for users, roles, and hierarchies using Cypher
• Understand location-scoped role assignments
• Can create delegations and understand their lifecycle
• Understand access reviews and governance workflows
• Can use semantic search to find identities and roles
• Understand how PDP uses Membership as a Policy Information Point
• Completed Week 2 assessment