Permissions System

Understanding FlagFlow's granular permission model and role-based access control

Permission Model Overview

FlagFlow uses a granular permission system that allows fine-tuned control over what users can do within the system. Each permission grants access to specific operations, enabling administrators to create roles that match their organization's security requirements.

Design Principle: Permissions are granular and specific, allowing you to grant only the minimum access required for each user role.

Core Permissions

FlagFlow defines the following core permissions that control access to different system operations:

Permission	Description	Grants Access To
`flag-create`	Can create, rename/move, and delete flags	Creating new feature flags Renaming existing flags Moving flags between folders/categories Deleting flags permanently
`flag-schema`	Can manage flag schemas	Modifying flag data types Adding/removing flag properties Changing validation rules Updating flag metadata
`flag-value`	Can manage flag values	Enabling/disabling feature flags Updating flag values Managing environment-specific values Setting percentage rollouts
`users`	Can add, modify, or remove users and manage sessions	Creating new user accounts Modifying user details Deleting user accounts Managing active sessions Assigning permissions to users
`migration`	Can restore backups or execute migrations	Importing data from other FlagFlow instances Executing database migrations Restoring from backup files System maintenance operations

Public Access (No Authentication Required)

Certain operations in FlagFlow are publicly accessible without authentication to enable seamless integration with applications:

Publicly Accessible Operations

Reading flag values - Applications can fetch current flag states
Viewing flag schemas - Applications can understand flag structure
Environment information - Basic environment metadata

This design allows applications to integrate with FlagFlow without requiring authentication credentials while keeping all administrative operations secure.

Common Role Examples

Here are typical user roles and their recommended permission combinations:

Developer

Can modify flag values during development and testing

flag-value

Typical use: Developers can enable/disable features and adjust flag values for testing purposes.

Senior Developer / Architect

Can modify flag schemas and values

flag-value flag-schema

Typical use: Senior developers can modify flag structure and data types in addition to values.

Product Manager

Can create and manage feature flags

flag-create flag-value

Typical use: Product managers can create new feature flags and control their rollout.

Team Lead

Full flag management capabilities

flag-create flag-schema flag-value

Typical use: Team leads have full control over feature flag lifecycle and management.

System Administrator

Complete system access including user management

users migration flag-create flag-schema flag-value

Typical use: System administrators manage the entire FlagFlow instance including users and system operations.

Assigning Permissions

Built-in User Management

When using FlagFlow's built-in user management, permissions are assigned through the web interface:

Navigate to the Users section
Select the user you want to modify
Click Edit Permissions
Check the permissions you want to grant
Save the changes

Keycloak Integration

When using Keycloak, permissions are managed through client roles that map to FlagFlow permissions:

Create client roles in Keycloak matching FlagFlow permission names
Assign roles to users or groups
FlagFlow automatically maps Keycloak roles to permissions

Keycloak Role Mapping

# Example: Creating roles in Keycloak client
flag-create     -> FlagFlow permission: flag-create
flag-schema     -> FlagFlow permission: flag-schema
flag-value      -> FlagFlow permission: flag-value
users           -> FlagFlow permission: users
migration       -> FlagFlow permission: migration

Permission Hierarchy and Dependencies

While FlagFlow permissions are generally independent, some operations may require multiple permissions or have logical dependencies:

Operation	Required Permissions	Notes
Create a new flag	`flag-create`	Includes setting initial schema and values
Modify existing flag structure	`flag-schema`	May require flag-value to set new defaults
Update flag values only	`flag-value`	Most common day-to-day operation
Delete a flag	`flag-create`	Deletion is part of flag lifecycle management
Manage user permissions	`users`	High-privilege operation

Security Best Practices

Principle of Least Privilege

Grant users only the minimum permissions required for their role
Regularly review and audit user permissions
Remove permissions when users change roles or leave the organization

Permission Separation

Development vs Production: Consider different permission sets for different environments
Operational Separation: Separate schema management from value management where possible
Administrative Separation: Limit users and migration permissions to trusted administrators

Monitoring and Auditing

Enable comprehensive logging of all administrative operations
Monitor flag changes and correlate with user permissions
Set up alerts for sensitive operations like user management or migrations
Regularly review access logs and permission usage

Troubleshooting Permissions

"Access Denied" Errors

Verify the user has the required permission for the operation
Check that the user is properly authenticated
Ensure permissions are correctly assigned (built-in users) or mapped (Keycloak)
Test with a user that has all permissions to isolate the issue

Permission Changes Not Taking Effect

For built-in users: Changes are immediate, try refreshing the page
For Keycloak: Token refresh may be required - have user logout and login again
Check browser cache and clear if necessary
Verify the permission assignment was saved correctly

Unexpected Permission Behavior

Check logs for permission verification errors
Verify permission names match exactly (case-sensitive)
For Keycloak: Ensure client role mapping is correct
Test with a fresh user account to rule out cached permission issues

On this page