Authorization

Flipt v2 introduces an enhanced authorization system that provides environment-aware, hierarchical access control. This system builds upon v1’s foundation while adding support for multi-environment deployments. Flipt supports the ability to secure its core API routes by setting the required field to true on the authorization configuration object.

config.yaml

authorization:
  required: true

When authorization is set to required, the API will ensure valid credentials are present on all management API requests.

Once authorization has been set to required: true all management API routes will require a valid authentication session as well.The UI will require a session-compatible authentication method (e.g. OIDC) to be enabled.

Backends

Flipt uses Open Policy Agent (OPA) to enforce authorization policies. OPA is a general-purpose policy engine that can be used to enforce policies across the stack. Flipt supports sourcing policies and external data from various backends. Currently, Flipt supports the following backends:

Local

Local

Flipt supports loading policy and external data from the local filesystem.

Policies

For configuring policies, the files must be valid Rego files. You can specify the path to the policy file in the policy object in the authorization configuration object.

authorization:
  required: true
  local:
    policy:
      path: "policy.rego"

The policy must have the following package declaration:

policy.rego

package flipt.authz.v2

Flipt v2 uses package flipt.authz.v2 instead of v1’s package flipt.authz.v1. This is a breaking change that reflects the enhanced authorization model.

Polling Interval

Flipt will poll the policy file for changes at a regular interval. By default, Flipt will poll the policy file every 5 minutes. You can adjust this interval by setting the poll_interval field in the policy object.

authorization:
  required: true
  local:
    policy:
      path: "policy.rego"
      poll_interval: "1m"

External Data

In addition to policies that can be used to enforce authorization rules, Flipt also provides a way to pass external data to the policy evaluation from the local filesystem. These data objects must be valid JSON objects. This can be done by setting the data object in the authorization configuration object.

authorization:
  required: true
  local:
    policy:
      path: "policy.rego"
    data:
      path: "data.json"

Polling Interval

Like policies, Flipt will poll data files for changes at a regular interval. By default, Flipt will poll the data file every 30 seconds. You can adjust this interval by setting the poll_interval field in the data object.

authorization:
  required: true
  local:
    data:
      path: "data.json"
      poll_interval: "1m"

Key Differences from v1

Flipt v2 authorization introduces several important changes:

1. Environment-Aware Authorization

Unlike v1, which operates at the namespace level, v2 introduces a hierarchical model with environments:

Global scope: Full access to all environments and namespaces
Environment scope: Manage namespaces within specific environments
Namespace scope: Manage resources (flags, segments, etc.) within specific namespaces

2. Optional Policy Queries for UI Filtering

v2 policies can optionally implement two special queries to enable UI filtering. When implemented, these queries allow the Flipt UI to show only the environments and namespaces that users have access to:

# Returns list of environments the user can access
viewable_environments := ["production", "staging"] # or ["*"] for all

# Returns list of namespaces in an environment the user can access
viewable_namespaces(env) := ["frontend", "backend"] # or ["*"] for all

These queries are optional. If not implemented, the UI will show all environments and namespaces, but authorization will still be enforced when users attempt to access them.Implementing these queries improves the user experience by filtering out inaccessible resources in the UI.

3. Simplified Request Structure

v2 uses a simplified request structure with scope field:

{
  "request": {
    "scope": "namespace", // or "environment"
    "environment": "production",
    "namespace": "frontend",
    "action": "update"
  }
}

Example Policies

Basic RBAC Policy

Here’s a complete example of a v2 RBAC policy:

policy.rego

package flipt.authz.v2

import rego.v1

# Default deny
default allow := false
default viewable_environments := []

# Helper to get user/group identifiers
subject_ids contains id if {
    user := input.authentication.metadata["io.flipt.auth.user"]
    id := sprintf("user:%s", [user])
}

subject_ids contains id if {
    groups := input.authentication.metadata["io.flipt.auth.groups"]
    id := sprintf("group:%s", [groups[_]])
}

# Check for global admin access
has_global_access if {
    some binding in data.role_bindings
    binding.scope.type == "global"
    some subject in binding.subjects
    some id in subject_ids
    subject == id
}

# Environment visibility
viewable_environments := ["*"] if {
    has_global_access
} else := envs if {
    envs := {env |
        some binding in data.role_bindings
        some subject in binding.subjects
        some id in subject_ids
        subject == id
        some b in binding.scope.bindings
        env := b.environment
    }
}

# Namespace visibility within an environment
viewable_namespaces(env) := ["*"] if {
    has_global_access
} else := ["*"] if {
    # Check for wildcard namespace access
    some binding in data.role_bindings
    some subject in binding.subjects
    some id in subject_ids
    subject == id
    some b in binding.scope.bindings
    b.environment == env
    "*" in b.namespaces
} else := namespaces if {
    # Return specific namespaces
    namespaces := {ns |
        some binding in data.role_bindings
        some subject in binding.subjects
        some id in subject_ids
        subject == id
        some b in binding.scope.bindings
        b.environment == env
        some ns in b.namespaces
        ns != "*"
    }
}

# Main authorization logic
allow if {
    has_global_access
}

allow if {
    scope := input.request.scope
    env := input.request.environment
    ns := input.request.namespace
    action := input.request.action

    # Check permissions based on scope
    some binding in data.role_bindings
    some subject in binding.subjects
    some id in subject_ids
    subject == id

    some b in binding.scope.bindings
    b.environment == env

    # Check namespace access
    ns in b.namespaces

    # Check action permission
    action in b.permissions
}

Example Data Structure

The accompanying data.json file defines role bindings:

data.json

{
  "role_bindings": [
    {
      "role": "admin",
      "subjects": ["user:[email protected]"],
      "scope": {
        "type": "global"
      }
    },
    {
      "role": "platform_team",
      "subjects": ["group:platform"],
      "scope": {
        "type": "environment",
        "bindings": [
          {
            "environment": "production",
            "namespaces": ["*"],
            "permissions": ["*"]
          },
          {
            "environment": "staging",
            "namespaces": ["*"],
            "permissions": ["read", "update"]
          }
        ]
      }
    },
    {
      "role": "developer",
      "subjects": ["user:[email protected]", "group:developers"],
      "scope": {
        "type": "namespace",
        "bindings": [
          {
            "environment": "development",
            "namespaces": ["frontend", "backend"],
            "permissions": ["*"]
          },
          {
            "environment": "staging",
            "namespaces": ["frontend"],
            "permissions": ["read"]
          }
        ]
      }
    }
  ]
}

This structure allows:

Global admins: Full access to everything
Platform team: Manage all namespaces in production, read/update in staging
Developers: Full access to specific namespaces in development, read-only in staging

Migration from v1

When migrating from v1 to v2:

Update package declaration from flipt.authz.v1 to flipt.authz.v2
Add environment context to your role bindings
Optionally implement the UI filtering queries: viewable_environments and viewable_namespaces(env) for better UX
Update request handling to use the new scope field instead of resource/subject
Remove bundle configurations as they’re not supported in v2 (yet)

Existing v1 policies will not work without modification. Plan your migration carefully and test thoroughly before deploying to production.

Getting Started

Pro Features

Configuration

Integration

CLI

Guides

Tooling

Authorization

Backends

Local

Policies

Polling Interval

External Data

Polling Interval

Key Differences from v1

1. Environment-Aware Authorization

2. Optional Policy Queries for UI Filtering

3. Simplified Request Structure

Example Policies

Basic RBAC Policy

Example Data Structure

Migration from v1

​Backends

​Local

​Policies

​Polling Interval

​External Data

​Polling Interval

​Key Differences from v1

​1. Environment-Aware Authorization

​2. Optional Policy Queries for UI Filtering

​3. Simplified Request Structure

​Example Policies

​Basic RBAC Policy

​Example Data Structure

​Migration from v1

Backends

Local

Policies

Polling Interval

External Data

Polling Interval

Key Differences from v1

1. Environment-Aware Authorization

2. Optional Policy Queries for UI Filtering

3. Simplified Request Structure

Example Policies

Basic RBAC Policy

Example Data Structure

Migration from v1