Authentication Overview

Understanding FlagFlow's authentication system and permission model

Authentication Model

FlagFlow implements a role-based authentication system with granular permissions. The system is designed with security in mind while maintaining ease of use for feature flag management.

Key Principle: Flag values are readable without authentication, but all modifications require proper authentication and permissions.

FlagFlow allows unauthenticated access to flag values for reading purposes. This design enables applications to fetch feature flags without requiring authentication credentials, simplifying integration while maintaining security for administrative operations.

What's Publicly Accessible

Flag values - Current state of feature flags
Flag schemas - Structure and metadata (read-only)
Environment data - Available environments and their configurations

Protected Operations

All administrative and modification operations require authentication and appropriate permissions:

Operation	Required Permission	Description
Flag Creation/Deletion	flag-create	Create new flags or delete existing ones
Schema Modification	flag-schema	Modify flag schemas, types, and structure
Value Updates	flag-value	Update flag values and states
User Management	users	Add, modify, or remove users and manage sessions
Data Migration	migration	Execute migrations and restore backups See Migration, Export & Backup, and Restore

Authentication Methods

FlagFlow supports flexible authentication configurations based on environment variables:

Authentication Configuration Matrix

The behavior of FlagFlow's authentication system depends on the combination of SESSION_USERS_ENABLED and KEYCLOAK_HOST settings:

SESSION_USERS_ENABLED	KEYCLOAK_HOST	Behavior	Login Display
`false`	`not set`	Auto-login No authentication required, direct access to admin interface	No login screen
`true`	`not set`	Session-based only Built-in user management with username/password	Standard login form
`false`	`set`	Keycloak only OAuth 2.0/OpenID Connect authentication	Keycloak redirect
`true`	`set`	Dual authentication Users can choose between session-based or Keycloak authentication	Login with options to switch between methods

Built-in User Management

Simple session-based authentication for small to medium deployments

Session-based authentication
Default user creation at startup
Configurable session timeout
Built-in user interface

Keycloak Integration

Enterprise-grade authentication with external identity provider

OAuth 2.0 / OpenID Connect
Single Sign-On (SSO)
Advanced role management
Integration with existing identity systems

Security Considerations

Important Security Notes

Network Security: While flag values are publicly readable, ensure FlagFlow is deployed in a secure network environment
Administrative Access: Restrict administrative interface access to trusted networks or VPNs
Session Management: Configure appropriate session timeouts based on your security requirements
Audit Logging: Enable comprehensive logging for all administrative operations

Authentication Configuration

Configure authentication through environment variables:

Environment Variables

# Built-in User Management
SESSION_USERS_ENABLED=true
SESSION_DEFAULT_USERNAME=admin
SESSION_DEFAULT_PASSWORD=secure-password
SESSION_TIMEOUT_SEC=1800

# Keycloak Integration (Enterprise)
KEYCLOAK_HOST=https://auth.yourcompany.com
KEYCLOAK_REALM=flagflow
KEYCLOAK_CLIENT=flagflow-frontend

See the Environment Variables documentation for complete configuration options.

On this page