Keycloak Integration

Keycloak integration provides enterprise-level authentication for FlagFlow, supporting single sign-on (SSO), advanced user management, and integration with existing identity infrastructure. This is the recommended solution for larger organizations with complex authentication requirements.

1. Install Keycloak

Install Keycloak using Docker or your preferred method:

# Using Docker Compose
version: '3.8'
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    environment:
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: admin-password
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak-db-password
    ports:
      - "8080:8080"
    command: start-dev
    depends_on:
      - postgres

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak-db-password
    volumes:
      - keycloak_db:/var/lib/postgresql/data

volumes:
  keycloak_db:

2. Access Keycloak Admin Console

1. Navigate to http://localhost:8080
2. Click on "Administration Console"
3. Login with the admin credentials configured above
4. Create a new realm for FlagFlow

1. Create FlagFlow Realm

1. In the Keycloak admin console, hover over the realm dropdown (top-left)
2. Click "Create Realm"
3. Enter realm name: flagflow
4. Enable the realm and click "Create"

2. Configure Realm Settings

Navigate to Realm Settings and configure:

• Login Tab: Configure login requirements, session timeouts
• Keys Tab: Ensure proper token signing keys are configured
• Tokens Tab: Set appropriate token lifespans
• Sessions Tab: Configure session behavior

1. Create FlagFlow Client

1. Navigate to "Clients" in the left sidebar
2. Click "Create client"
3. Set Client ID: flagflow-frontend
4. Set Client Type: OpenID Connect
5. Click "Next"

2. Configure Client Capabilities

• Enable Client authentication
• Enable Authorization
• Enable Standard flow (Authorization Code flow)
• Enable Direct access grants (if needed)

3. Configure Client Settings

In the client settings tab:

# Valid redirect URIs (include the callback path)
https://your-flagflow-domain.com/auth/keycloak/callback
https://your-flagflow-domain.com/*
http://localhost:3000/auth/keycloak/callback  # For development
http://localhost:3000/*                       # For development

# Web origins
https://your-flagflow-domain.com
http://localhost:3000    # For development

# Access Type: confidential
# Service Accounts: Enabled (if using service accounts)

1. Create Client Roles

Navigate to your client and create the following roles under the "Roles" tab:

2. Create Composite Roles

Create composite roles for common user types:

• flagflow-developer: Include flag-value role
• flagflow-admin: Include flag-create, flag-schema, flag-value roles
• flagflow-super-admin: Include all roles including users and migration

1. Create Users

1. Navigate to "Users" in the left sidebar
2. Click "Add user"
3. Fill in user details (username, email, first name, last name)
4. Enable the user and set email verification status
5. Click "Create"

2. Assign Roles to Users

1. Select the user from the users list
2. Go to the "Role mapping" tab
3. Click "Assign role"
4. Select appropriate client roles or composite roles
5. Click "Assign"

3. Set User Passwords

1. In the user details, go to the "Credentials" tab
2. Click "Set password"
3. Enter a temporary password
4. Leave "Temporary" enabled for first-time users
5. Click "Save"

Configure FlagFlow to use Keycloak authentication:

# Disable built-in user management
SESSION_USERS_ENABLED=false

# Keycloak configuration
KEYCLOAK_HOST=https://your-keycloak-domain.com
KEYCLOAK_REALM=flagflow
KEYCLOAK_CLIENT=flagflow-frontend

# Other standard configuration
LOGLEVEL=info
ENVIRONMENT=production
ETCD_SERVER=your-etcd-server:2379

1. Test Authentication Flow

1. Start FlagFlow with Keycloak configuration
2. Navigate to your FlagFlow instance
3. You should be redirected to Keycloak login page
4. Login with a test user
5. Verify successful redirect back to FlagFlow

2. Verify Permissions

• Test that users can only access features based on their assigned roles
• Verify that unauthorized operations are properly blocked
• Check that role changes in Keycloak are reflected in FlagFlow

Group-Based Permissions

For larger organizations, use groups to manage permissions more efficiently:

1. Create groups in Keycloak (e.g., "Developers", "Administrators")
2. Assign roles to groups instead of individual users
3. Add users to appropriate groups
4. Users inherit permissions from their group memberships

LDAP/Active Directory Integration

To integrate with existing directory services:

1. Navigate to "User Federation" in Keycloak
2. Add a new LDAP provider
3. Configure connection settings and user mapping
4. Test the connection and sync users
5. Map LDAP groups to Keycloak roles

To migrate from FlagFlow's built-in authentication to Keycloak:

1. Set up Keycloak and configure the FlagFlow client as described above
2. Create user accounts in Keycloak matching your existing FlagFlow users
3. Assign appropriate roles to each user based on their current permissions
4. Test the Keycloak integration in a development environment
5. Update production environment variables to enable Keycloak
6. Set SESSION_USERS_ENABLED=false to disable built-in authentication
7. Restart FlagFlow to apply the new authentication configuration