Permissions
Lex App provides fine-grained access control through permission methods defined directly on your models. You can control which fields a user can view, edit, or export, which records they can see, and which actions they can perform — all integrated with Keycloak.
The UserContext Object
All permission methods receive a UserContext dataclass with clean user information:
@dataclass(frozen=True)
class UserContext:
user: Any # Django User object
email: str # User's email address
is_authenticated: bool # Is user logged in?
is_superuser: bool # Is user a superuser?
groups: Set[str] # Group names, e.g. {'admin', 'finance'}
keycloak_scopes: Set[str] # Keycloak permission scopesBasic Example
from lex.core.models.LexModel import LexModel, UserContext, PermissionResult
from django.db import models
class MyModel(LexModel):
name = models.CharField(max_length=100)
sensitive_field = models.CharField(max_length=100)
owner_email = models.EmailField()
def permission_read(self, user_context: UserContext) -> PermissionResult:
if user_context.is_superuser or 'admin' in user_context.groups:
return PermissionResult.allow_all()
return PermissionResult.allow_all_except({'sensitive_field'})
def permission_delete(self, user_context: UserContext) -> bool:
return user_context.is_superuser or self.owner_email == user_context.emailPermission Methods
Field-Level (return PermissionResult)
Method | Purpose |
|---|---|
| Which fields the user can view |
| Which fields the user can modify |
| Which fields the user can export |
Action-Level (return bool)
Method | Purpose |
|---|---|
| Can this user create new instances? |
| Can this user delete this instance? |
| Can this user list instances of this model? |
When
permission_createreturnsFalse, the API responds with 401 Unauthorized for unauthenticated requests and 403 Forbidden for authenticated-but-denied requests — not a generic 400. Frontends and API clients can use these status codes to redirect to login (401) or show a "permission denied" message (403).
PermissionResult Factory Methods
Method | Behavior |
|---|---|
| Allow access to all fields |
| Allow only specific fields |
| Allow all except specified fields |
| Deny access entirely |
| Deny access entirely with an optional reason string for logging |
Built-in Helpers
For common patterns, LexModel provides ready-made helpers you can call directly from a permission method instead of building a PermissionResult by hand:
Helper | What It Does |
|---|---|
| Grant full access when |
| Grant full access when the user is in any of the given groups |
| Grant a field subset when the user owns the record (configurable owner field) |
| Defer to a Keycloak scope check |
| Allow everything except a configured set of sensitive fields |
See LexModel Internals for the full signatures and parameter lists.
Real-World Examples
HR Salary Visibility
Only HR managers can see the salary field:
class EmployeeContract(LexModel):
name = models.CharField(max_length=100)
role = models.CharField(max_length=100)
salary = models.DecimalField(max_digits=10, decimal_places=2)
def permission_read(self, user_context: UserContext) -> PermissionResult:
if 'hr_manager' in user_context.groups or user_context.is_superuser:
return PermissionResult.allow_all()
return PermissionResult.allow_all_except({'salary'})Expense Reports — Record Ownership
Finance sees all reports, employees only see their own:
class ExpenseReport(LexModel):
employee_email = models.EmailField()
amount = models.DecimalField(max_digits=10, decimal_places=2)
def permission_read(self, user_context: UserContext) -> PermissionResult:
if 'finance_manager' in user_context.groups:
return PermissionResult.allow_all()
if self.employee_email == user_context.email:
return PermissionResult.allow_all()
return PermissionResult.allow_fields(set()) # row hiddenKeycloak Integration
By default, permission methods fall back to Keycloak scopes. After running lex Init, your project models are synced to Keycloak as Resources and your permission methods are registered as Scopes. Manage permissions at Excellence Cloud.
Only models defined in your project are synced — Django built-ins (auth, admin, etc.), Lex framework models, and any third-party package models are automatically excluded.
You can also use Keycloak scopes directly in your custom logic:
def permission_read(self, user_context: UserContext) -> PermissionResult:
if 'read' in user_context.keycloak_scopes:
return PermissionResult.allow_all()
return PermissionResult.deny("No read permission in Keycloak")Migrating from V1?
If you're coming fromModificationRestriction:
Aspect
V1 (Old)
Current
Approach
Separate
ModificationRestrictionclassPermission methods on your model
User info
Raw
userobject +violationslistClean
UserContextdataclassGranularity
Model-level only
Field-level and row-level
Keycloak
Manual integration
Built-in scope resolution
Remove
ModificationRestrictionclass definitions, removemodification_restriction = MyRestriction(), and addpermission_*methods directly to your model. Runlex Initto sync to Keycloak.
Authentication Architecture
Lex App uses Keycloak as its identity provider. Users authenticate once via OIDC (OpenID Connect), and the session is shared across the entire application — including embedded Streamlit dashboards.
The frontend authentication flow:
sequenceDiagram
participant User
participant App as Lex App Frontend
participant API as Lex App Backend
participant KC as Keycloak
User->>App: Opens application
App->>API: GET /api/user/
alt Not authenticated
API-->>App: 401 Unauthorized
App->>KC: Redirect to OIDC login
KC-->>App: Redirect back with session
App->>API: GET /api/user/ (with session)
end
API-->>App: User info + roles + scopes
App->>App: Render UI with permissions appliedThe SessionAuthGate component handles this transparently — including redirect-loop protection, automatic retries, and a clear unauthorized page for users without assigned roles.
For non-browser clients (for example scripts, integrations, or dashboards calling the API directly), you can authenticate with an Authorization: Bearer <token> header. Lex App will resolve roles and scopes from that token even when there is no browser session.
Access Scopes
Permissions are enforced across 6 scopes:
Scope | What It Controls |
|---|---|
read | Which fields a user can view |
edit | Which fields a user can modify |
export | Which fields appear in exports |
create | Whether a user can create new records |
delete | Whether a user can delete records |
list | Whether a user can view the model's table |
These scopes are synced to Keycloak when you run lex Init, enabling centralized policy management.
In the Frontend
Permissions are enforced at every layer:
- Grid cells — fields the user can't read are hidden; fields they can't edit are read-only
- Action buttons — the Create and Delete buttons are hidden if the user doesn't have those permissions
- Inline editing — attempting to edit a restricted field shows it as disabled
- Exports — restricted fields are excluded from exported files
See The Grid for how permissions appear in the user interface.
Was this helpful?
Your feedback shapes what we write next.
