User Management

The Manager provides comprehensive user management with role-based access control at project, tenant, and application levels.

Overview

Users in the Productify Framework are managed through Pocket ID. The Manager integrates with Pocket ID to handle authentication and user information.

User Roles

The Manager implements hierarchical role-based access control (RBAC):

System Roles

Each user record carries a system-wide role field with three values: normal, audit, and administrator.

The system role is stored but never enforced

Nothing in the Manager reads this field — it grants no access and restricts none. audit confers no auditing rights and administrator confers no administrative rights. All effective access comes from the project, tenant, and application roles below. See Known Issues.

Project Roles

• owner - Full control over the project, including user management
• maintainer - Can manage most project resources
• developer - Can modify resources
• tester - Elevated read access for testing
• readonly - Read-only access to project resources

Tenant Roles

• owner - Full control over the tenant, including user management
• maintainer - Can manage most tenant resources
• developer - Can modify resources
• tester - Elevated read access for testing
• normal - Standard access
• readonly - Read-only access to tenant resources

Application Roles

• normal - Standard access to the application
• readonly - Read-only access to the application

Not enforced

Role assignment checks only that the caller is a maintainer or owner — the role being granted is never compared against the caller's own role, so a maintainer can grant owner. See Known Issues.

Managing Users

Adding Users to Projects

1. Navigate to Projects in the sidebar
2. Select the project
3. Find the user management section on the project detail page
4. Click Add User
5. Search for the user by name
6. Select the appropriate role
7. Click Add

Via API:

mutation {
  addUserToProject(
    projectID: "project-uuid"
    userID: "user-uuid"
    role: owner
  ) {
    id
    role
    user {
      externalUsername
      externalEmail
    }
  }
}

Adding Users to Tenants

1. Navigate to the project's Tenants page
2. Select the tenant
3. Find the user management section on the tenant detail page
4. Click Add User
5. Select user and role
6. Click Add

Via API:

mutation {
  addUserToTenant(
    tenantID: "tenant-uuid"
    userID: "user-uuid"
    role: developer
  ) {
    id
    role
  }
}

Adding Users to Applications

1. Navigate to the tenant's Applications page
2. Select the application
3. Find the user management section on the application detail page
4. Click Add User
5. Select user and role
6. Click Add

Via API:

mutation {
  addUserToApplication(
    applicationID: "app-uuid"
    userID: "user-uuid"
    role: readonly
  ) {
    id
    role
  }
}

Updating User Roles

Changing Project Roles

1. Navigate to the project detail page's user list
2. Find the user in the list
3. Click the role dropdown
4. Select the new role
5. Save the change

Via API:

mutation {
  updateUserProjectRole(id: "user-project-relation-uuid", role: developer) {
    id
    role
  }
}

Changing Tenant/Application Roles

Follow the same process as projects, using the user list on the respective resource's detail page (updateUserTenantRole / updateUserApplicationRole via the API).

Removing Users

Removing from Projects

1. Navigate to the project detail page's user list
2. Find the user
3. Click the Remove button
4. Confirm the removal

Via API:

mutation {
  removeUserFromProject(id: "user-project-relation-uuid")
}

WARNING

Removing a user from a project also removes their access to all child tenants and applications within that project.

User Search

Provider User Search

The Manager can search for users in Pocket ID:

query {
  userProviderSearch(name: "john") {
    id
    username
    email
    displayName
    disabled
  }
}

This is useful when adding new users who haven't yet accessed the Manager.

Current User Information

Get information about the authenticated user:

query {
  me {
    id
    externalName
    externalUsername
    externalEmail
    role
  }
}

Access Control

Hierarchical Permissions

Access control follows a hierarchical model:

• Project access grants access to all tenants and applications within the project
• Tenant access grants access to all applications within the tenant
• Application access grants access only to that specific application

Permission Inheritance

Membership at a higher level grants access to the resources below it; the effective role considers both project and tenant membership.

Example:

• User has the owner project role → Can access all tenants and applications in the project
• User has the developer tenant role → Can work within that tenant and its applications, but not other tenants
• User has the readonly application role → Can only view that specific application

Best Practices

Role Assignment

• Grant the minimum required role for users to perform their tasks
• Use the project owner role sparingly
• Prefer tenant/application roles for focused responsibilities
• Use the readonly role for auditors and observers (the system audit role is not enforced and grants nothing — see Known Issues)

User Lifecycle

• Onboarding - Add users to appropriate projects/tenants when they join
• Role Changes - Update roles as responsibilities change
• Offboarding - Remove access when users leave or change teams

Security

• Regular Audits - Review user access periodically
• Principle of Least Privilege - Grant minimal necessary permissions
• Segregation of Duties - Separate administrative and operational roles
• Disable Unused Accounts - Remove inactive users

Organization

• Document Roles - Maintain documentation of role responsibilities
• Naming Conventions - Use consistent naming for users
• Group Management - Consider organizing users by team/function

Audit Logging

User management operations are intended to be recorded in the audit log. They are not: nothing writes AuditLog rows today, so this query returns empty — see Known Issues.

query {
  auditLogs(
    projectID: "project-uuid"
    filters: [{ field: "entityType", value: "User2Project" }]
    order: { field: "created_at", direction: DESC }
    pagination: { limit: 50, offset: 0 }
  ) {
    id
    action
    description
    user {
      externalUsername
    }
    createdAt
  }
}

See Audit Logs for more details.

Troubleshooting

User Not Found

Issue: User cannot be found when searching

Solutions:

• Verify user exists in Pocket ID
• Check Pocket ID connection
• Ensure user has logged in at least once
• Verify spelling of username/email

Access Denied

Issue: User cannot access resources

Solutions:

• Verify user has appropriate role at correct level
• Check role permissions match required action
• Confirm user is not disabled in Pocket ID
• Review audit logs for permission changes

Cannot Add User

Issue: Unable to add user to project/tenant/application

Solutions:

• Verify you have a sufficient role at that level (e.g. owner or maintainer)
• Check user is not already added
• Ensure user exists in system (may need to login first)
• Verify Pocket ID is accessible

Integration with Pocket ID

The Manager integrates with Pocket ID for user management:

Configuration

Pocket ID API connection is configured in the Manager's config file:

pocket_id:
  host: http://pocketid:1411
  api_key: your-api-key

User Authentication

User login via OAuth/OIDC is handled by the Proxy component. See Proxy Configuration for OIDC client setup.

See Configuration for details.

API Reference

Complete user management API documentation:

• Add User to Project
• Update User Role
• Remove User
• User Search

See the full API Reference for all user management operations.