User Management, RBAC & Keycloak

User model, roles and permissions (RBAC), organization memberships and Keycloak integration in the Polycrate API, including the migration from 0.14.x to 0.15.0.

User Management, RBAC & Keycloak

Overview

Since 0.15.0 the Polycrate API is a fully user-based system with integrated Keycloak connectivity and a generic, role-based access control system (RBAC). Earlier versions still used the Contact model as the primary identity – since 0.15.0 User is the only authenticated identity; Contact exists exclusively as a CRM object.

Building block Purpose
User Authenticated identity, login, OIDC subject
Contact CRM record (contact person, billing contact) – no login
Organization Membership Assigns a user to an organization with a role
Roles & Permissions Define what a user may do in the UI and API
Keycloak Central IdP for login, OIDC flow and SSO

Roles & Permissions (RBAC)

Polycrate distinguishes two fundamental roles at the system level:

Admin (is_superuser=True)

  • Full access to all objects of all organizations
  • Sees administrative areas (Domain Registrar, System Config, Rollout Dashboard, Feature Flags, Default Data Import)
  • May manage users of other organizations
  • May create and delete workspaces and organizations

Customer User (is_superuser=False)

  • Access exclusively to objects of the organizations they are a member of
  • No administrative areas
  • Filtering and visibility are automatically org-scoped (ManagedObject.get_queryset_for_user())
  • Per-model permissions (Create/Edit/Delete/Archive) are checked consistently in the UI and the API

admin_only instead of staff_only

Fields and views that are available exclusively to administrators are consistently marked with admin_only=True (instead of the old staff_only). Examples: System Config, Default Data Import, Domain Registrar.

Organization Membership

A user can be a member of any number of organizations. Each membership has a role that controls access to the objects of that organization. Admins see all organizations; customer users only see organizations they are a member of.

Management: Administration → Users → open user → Memberships

Keycloak Integration

Login Flow

  1. User opens Polycrate
  2. Redirect to Keycloak (the organization's realm)
  3. Login via Keycloak (password, MFA, social IdP – depending on realm configuration)
  4. Keycloak redirects back with an OIDC token
  5. On first login, Polycrate automatically creates a SocialAccount and links User ↔ Keycloak subject

Automatic Keycloak User Provisioning

When a new user is created in Polycrate (via the admin UI, the API or automatically as part of the Contact→User migration), a corresponding Keycloak account is created automatically:

  • Username = Polycrate email
  • Attributes are synchronized (first_name, last_name, email)
  • Initial password: either via the "forgot password" flow or set explicitly, depending on System Config
  • The Keycloak subject is persisted directly on the Polycrate user as SocialAccount(provider='keycloak')

Keycloak Fields per Organization

In the organization settings, realm parameters can be overridden per organization (e.g. a dedicated Keycloak realm per tenant). By default, the default configuration stored in System Config applies.

User Administration

The Administration → Users view provides full user management outside the Django admin:

  • List of all users (filterable by organization, role, active/inactive)
  • Detail with memberships, login history, associated contacts and Keycloak link
  • Create / Edit / Archive / Delete – the permissions for these actions are controlled by the RBAC system
  • API endpoints (/api/v1/admin/users/) with an extended serializer for admin use cases

Best Practices

Recommendation Reason
Exactly one identity per person Avoids duplicate Keycloak accounts and audit problems
Service accounts separately as Agent tokens, not as users Clean separation between human users and M2M
Roles via memberships, not via the admin flag Customer users should never be superusers
Maintain organization assignments cleanly Filtering is based exclusively on active memberships
Keycloak as the sole source for credentials MFA, password policy and session management centralized

Migration 0.14.x → 0.15.0

If you are coming from an older Polycrate release:

  • Contact used to be the main identity – login worked via the contact email. With release 0.15.0 this is automatically moved to User by the migration (Contact remains as a CRM object)
  • Existing Keycloak accounts are linked to the new user via email; missing Keycloak accounts are created automatically, provided the Keycloak integration is configured
  • Migration details: Release 0.15.0

See Also