Role-Based Access Control (RBAC)¶

RBAC Model¶

Access to resources is managed very much like AWS IAM.

There are five basic components to the system:

1. Users - Representing entities that access and use the system. A user is given one or more Access Credentials for authentication.
2. Actions - Representing a logical action within the system - reading a file, creating a repository, etc.
3. Resources - A unique identifier representing a specific resource in the system - a repository, an object, a user, etc.
4. Policies - Representing a set of Actions, a Resource and an effect: whether or not these actions are allowed or denied for the given resource(s).
5. Groups - A named collection of users. Users can belong to multiple groups.

Controlling access is done by attaching Policies, either directly to Users, or to Groups they belong to.

Authorization process¶

Every action in the system - be it an API request, UI interaction, S3 Gateway call, or CLI command - requires a set of actions to be allowed for one or more resources.

When a user makes a request to perform that action, the following process takes place:

1. Authentication - the credentials passed in the request are evaluated and the user's identity is extracted.
2. Action permission resolution - lakeFS then calculates the set of allowed actions and resources that this request requires.
3. Effective policy resolution - the user's policies (either attached directly or through group memberships) are calculated.
4. Policy/Permission evaluation - lakeFS will compare the given user policies with the request actions and determine whether or not the request is allowed to continue.

Policy Precedence¶

Each policy attached to a user or a group has an Effect - either allow or deny. During evaluation of a request, deny would take precedence over any other allow policy.

This helps us compose policies together. For example, we could attach a very permissive policy to a user and use deny rules to then selectively restrict what that user can do.

Policy Conditions¶

lakeFS policies support optional conditions that provide additional control over when a policy statement is in effect.

Conditions are specified using condition operators that evaluate to true or false based on the request context. When a condition evaluates to false, the policy statement does not apply.

Condition Structure¶

Conditions are added to policy statements using the optional condition field:

{
  "statement": [
    {
      "action": ["fs:ReadObject"],
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/myrepo/object/*",
      "condition": {
        "IpAddress": {
          "SourceIp": ["203.0.113.0/24", "198.51.100.25/32"]
        }
      }
    }
  ]
}

Supported Condition Operators¶

IpAddress / NotIpAddress¶

The IpAddress condition operator matches the client's source IP address against one or more IP addresses or CIDR blocks. The NotIpAddress condition operator matches when the client's source IP address does NOT match any of the specified IP addresses or CIDR blocks (negation of IpAddress).

Supported Fields:

• SourceIp - The IP address of the client making the request

Value Format: - Single IP address: "203.0.113.5" - CIDR notation: "203.0.113.0/24" - Array of IPs and/or CIDRs: ["203.0.113.0/24", "198.51.100.25/32"]

Example - Allow access only from specific IP range:

{
  "statement": [
    {
      "action": ["fs:*"],
      "effect": "allow",
      "resource": "*",
      "condition": {
        "IpAddress": {
          "SourceIp": ["10.0.0.0/8", "172.16.0.0/12"]
        }
      }
    }
  ]
}

Example - Deny access from specific IPs:

{
  "statement": [
    {
      "action": ["fs:*"],
      "effect": "deny",
      "resource": "*",
      "condition": {
        "IpAddress": {
          "SourceIp": ["192.0.2.0/24"]
        }
      }
    }
  ]
}

Example - Deny access from IPs NOT in allowed ranges:

{
  "statement": [
    {
      "action": ["fs:*"],
      "effect": "deny",
      "resource": "*",
      "condition": {
        "NotIpAddress": {
          "SourceIp": ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
        }
      }
    }
  ]
}

IP Address Extraction:

lakeFS extracts the client IP address from the request using the following priority:

1. X-Forwarded-For header (first IP in the list) - for requests through proxies/load balancers
2. X-Real-IP header - as a fallback
3. Remote address from the TCP connection

This ensures that IP-based conditions work correctly even when lakeFS is deployed behind a load balancer or reverse proxy.

StringEquals / StringNotEquals¶

The StringEquals condition operator matches a context value against one or more exact strings. The StringNotEquals condition operator matches when the context value does NOT equal any of the specified strings (negation of StringEquals).

StringLike / StringNotLike¶

The StringLike condition operator matches a context value against one or more wildcard patterns. The StringNotLike condition operator matches when the context value does NOT match any of the specified patterns (negation of StringLike).

Wildcard characters: * matches zero or more characters, ? matches exactly one character.

Attribute-Based Access Control for Repositories¶

Beyond role-based access, lakeFS supports attribute-based access control (ABAC): policy conditions that gate access based on attributes of the repository being accessed. This lets you enforce data governance policies automatically — for example, restricting access to PII or production repositories — without managing a separate policy per repository.

ABAC conditions can use user-defined metadata on repositories to filter. You attach key-value tags to repositories (e.g. env=staging, team=data-platform, classification=pii) and then reference those tags in policy conditions.

Managing repository metadata¶

Set (merge) metadata on a repository using the lakeFS REST API. Keys not included in the request are preserved — this is a merge, not a replacement:

curl -X POST https://<lakefs-host>/api/v1/repositories/<repo>/metadata \
  -H "Content-Type: application/json" \
  -u ${LAKECTL_CREDENTIALS_ACCESS_KEY_ID}:${LAKECTL_CREDENTIALS_SECRET_ACCESS_KEY} \
  -d '{"metadata": {"env": "staging", "team": "data-platform", "classification": "pii"}}'

Read metadata back to verify what is set:

curl -X POST https://$LAKECTL_SERVER_ENDPOINT/api/v1/repositories/<repo>/metadata \
  -u ${LAKECTL_CREDENTIALS_ACCESS_KEY_ID}:${LAKECTL_CREDENTIALS_SECRET_ACCESS_KEY} \

Delete specific metadata keys:

curl -X DELETE https://<lakefs-host>/api/v1/repositories/<repo>/metadata \
  -H "Content-Type: application/json" \
  -u ${LAKECTL_CREDENTIALS_ACCESS_KEY_ID}:${LAKECTL_CREDENTIALS_SECRET_ACCESS_KEY} \
  -d '{"keys": ["classification"]}'

Condition key format¶

lakefs:RepositoryMetadata/<metadata-key>

The <metadata-key> maps directly to a key in the repository's metadata. Matching is case-sensitive — lakefs:RepositoryMetadata/env matches only the metadata key env.

Examples¶

Allow read access only to repositories tagged env=staging¶

{
  "statement": [
    {
      "action": ["fs:ReadObject", "fs:ListObjects", "fs:ReadRepository"],
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/*",
      "condition": {
        "StringLike": {
          "lakefs:RepositoryMetadata/env": ["staging"]
        }
      }
    }
  ]
}

Deny access to PII repositories, combined with a broad allow¶

The most common ABAC pattern is to grant a user a broad role (e.g. FSReadAll) and then attach an additional policy that denies access to sensitive repositories. Since deny takes precedence over allow, this ensures the restriction holds regardless of what other policies the user has.

{
  "statement": [
    {
      "action": ["fs:*"],
      "effect": "deny",
      "resource": "arn:lakefs:fs:::repository/*",
      "condition": {
        "StringLike": {
          "lakefs:RepositoryMetadata/classification": ["pii"]
        }
      }
    }
  ]
}

Attach this policy alongside FSReadAll (or any other broad policy): the user can access all repositories except those tagged classification=pii.

Combine multiple metadata keys¶

When a condition block contains multiple keys, all of them must match for the statement to apply. Multiple values within a single key are evaluated as OR (any match is sufficient):

{
  "statement": [
    {
      "action": ["fs:ReadObject", "fs:ListObjects"],
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/*",
      "condition": {
        "StringLike": {
          "lakefs:RepositoryMetadata/team": ["ml"],
          "lakefs:RepositoryMetadata/env": ["staging", "dev"],
          "lakefs:RepositoryMetadata/classification": ["public"]
        }
      }
    }
  ]
}

This grants access only to repositories where team=ml and (env=staging or env=dev) and classification=public.

Behavior notes¶

• If a repository has no metadata, or if the requested key is absent, the condition evaluates to false and the statement does not apply.
• Condition keys are case-sensitive: lakefs:RepositoryMetadata/ENV does not match the metadata key env.

Resource naming - ARNs¶

lakeFS uses ARN identifier - very similar in structure to those used by AWS. The resource segment of the ARN supports wildcards: use * to match 0 or more characters, or ? to match exactly one character.

Here are a some examples of valid ARNs within lakeFS and their meaning:

Note that Iceberg catalog ARNs are branch-agnostic, the branch is not part of the ARN. A policy granting access to a namespace, a table or a view applies to that resource on every branch in the repository.

Additionally, the current user's ID is interpolated in runtime into the ARN using the ${user} placeholder.

This allows us to create fine-grained policies affecting only a specific subset of resources.

See below for a full reference of ARNs and actions.

Actions and Permissions¶

For the full list of actions and their required permissions, see the following table:

Some APIs may require more than one action. For instance, to create a repository (POST /repositories), you need permission to fs:CreateRepository for the name of the repository and also fs:AttachStorageNamespace for the storage namespace used.

Per-branch scoping for ListBranches¶

fs:ListBranches accepts either a repo ARN (arn:lakefs:fs:::repository/{repositoryId}, admits every branch in the repository) or a per-branch ARN (arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}, admits only matching branches), so policies can scope listings to a subset of branches. Listing first requires authorization to list that repository, then filters the branches you may see: a Deny on the repo ARN (or no Allow scoped to the repository) is an operation-level rejection, while a Deny on a branch ARN only hides the matching branches.

Allows are additive — adding a narrower Allow alongside a broader one does not tighten the result set. To restrict what a user sees, either replace the broad Allow with the narrower one, or keep the broad Allow and add a Deny for the subset to hide.

Confine a user to one team's branches:

{
  "Effect":   "Allow",
  "Action":   ["fs:ListBranches", "fs:ReadBranch"],
  "Resource": "arn:lakefs:fs:::repository/myrepo/branch/team-a-*"
}

Allow every branch except a subset (broad allow on the repo, targeted deny on the pattern to hide):

[
  {
    "Effect":   "Allow",
    "Action":   ["fs:ListBranches"],
    "Resource": "arn:lakefs:fs:::repository/myrepo"
  },
  {
    "Effect":   "Deny",
    "Action":   ["fs:ListBranches"],
    "Resource": "arn:lakefs:fs:::repository/myrepo/branch/secret-*"
  }
]

Notes.

• A user authorized to list the repository whose filter admits no branch — for example an allow on …/branch/team-z-* with no matching branch — receives 200 OK with an empty list.
• The 401/403 response is the same whether or not the repository exists, so the listing cannot be used to discover repository names.
• A user whose only allows are per-branch ARNs that don't match the repo's default branch will not see the default branch in the listing (default_branch on GetRepository still reports its name).
• The S3 gateway's bucket-root listing (aws s3 ls s3://{repo}/) uses the same evaluation and does not require a separate fs:ListObjects permission for the branch-listing case.

Preconfigured Policies¶

The following Policies are created during initial setup:

FSFullAccess¶

{
  "statement": [
    {
      "action": [
        "fs:*"
      ],
      "effect": "allow",
      "resource": "*"
    }
  ]
}

FSReadAll¶

{
  "statement": [
    {
      "action": [
        "fs:List*",
        "fs:Read*"
      ],
      "effect": "allow",
      "resource": "*"
    }
  ]
}

FSReadWriteAll¶

{
    "statement": [
        {
            "action": [
                "fs:Read*",
                "fs:List*",
                "fs:WriteObject",
                "fs:DeleteObject",
                "fs:RevertBranch",
                "fs:CreateBranch",
                "fs:CreateTag",
                "fs:DeleteBranch",
                "fs:DeleteTag",
                "fs:CreateCommit"
            ],
            "effect": "allow",
            "resource": "*"
        }
    ]
}

AuthFullAccess¶

{
  "statement": [
    {
      "action": [
        "auth:*"
      ],
      "effect": "allow",
      "resource": "*"
    }
  ]
}

AuthManageOwnCredentials¶

{
  "statement": [
    {
      "action": [
        "auth:CreateCredentials",
        "auth:DeleteCredentials",
        "auth:ListCredentials",
        "auth:ReadCredentials"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:auth:::user/${user}"
    }
  ]
}

RepoManagementFullAccess¶

{
    "statement": [
        {
            "action": [
                "ci:*"
            ],
            "effect": "allow",
            "resource": "*"
        },
        {
            "action": [
                "retention:*"
            ],
            "effect": "allow",
            "resource": "*"
        }
    ]
}

RepoManagementReadAll¶

{
    "statement": [
        {
            "action": [
                "ci:Read*"
            ],
            "effect": "allow",
            "resource": "*"
        },
        {
            "action": [
                "retention:Get*"
            ],
            "effect": "allow",
            "resource": "*"
        }
    ]
}

AdminFullAccess (lakeFS Cloud only)¶

{
  "statement": [
    {
      "action": [
        "admin:*"
      ],
      "effect": "allow",
      "resource": "*"
    }
  ]
}

AuditLogRead¶

Grants read access to the lakeFS audit log. Attached to the Admins group by default. Attach it to other groups or users to delegate audit-log visibility.

{
    "statement": [
        {
            "action": [
                "audit:ReadAuditLog"
            ],
            "effect": "allow",
            "resource": "arn:lakefs:audit:::log"
        }
    ]
}

Additional Policies¶

You can create additional policies to further limit user access. Use the web UI or the lakectl auth command to create policies.

Here is an example to define read/write access for a specific repository:

{
    "statement": [
        {
            "action": [
                "fs:ReadRepository",
                "fs:ReadCommit",
                "fs:ListBranches",
                "fs:ListTags",
                "fs:ListObjects"
            ],
            "effect": "allow",
            "resource": "arn:lakefs:fs:::repository/<repository-name>"
        },
        {
            "action": [
                "fs:RevertBranch",
                "fs:ReadBranch",
                "fs:CreateBranch",
                "fs:DeleteBranch",
                "fs:CreateCommit"
            ],
            "effect": "allow",
            "resource": "arn:lakefs:fs:::repository/<repository-name>/branch/*"
        },
                {
            "action": [
                "fs:ListObjects",
                "fs:ReadObject",
                "fs:WriteObject",
                "fs:DeleteObject"
            ],
            "effect": "allow",
            "resource": "arn:lakefs:fs:::repository/<repository-name>/object/*"
        },
                {
            "action": [
                "fs:ReadTag",
                "fs:CreateTag",
                "fs:DeleteTag"
            ],
            "effect": "allow",
            "resource": "arn:lakefs:fs:::repository/<repository-name>/tag/*"
        },
        {
            "action": ["fs:ReadConfig"],
            "effect": "allow",
            "resource": "*"
        }
    ]
}

Multiple Resources Statements¶

lakeFS supports specifying multiple resources in a single RBAC statement. This is available on lakeFS Cloud, or on lakeFS Enterprise if starting at version lakeFS v1.54.0 and Fluffy v0.12.0 In addition to a single resource. The resource field can contain a string representing a JSON-encoded list of resources.

{
    "statement": [
        {
            "action": [
                "fs:Read*"
            ],
            "effect": "allow",
            "resource": "[\"arn:lakefs:fs:::repository/repo1\",\"arn:lakefs:fs:::repository/repo2\"]"
        }
    ]
}

The list must be properly encoded as a JSON string: quote each resource, and escape those quotes as shown. Otherwise, the policy cannot be parsed.

Multi-Resource Policy Creation Using Python SDK¶

Here is how you can leverage Python SDK to create a multiple resource policy:

import lakefs_sdk
from lakefs_sdk.client import LakeFSClient
from lakefs_sdk import models

configuration = lakefs_sdk.Configuration(
        host=lakefsEndPoint,
        username=lakefsAccessKey,
        password=lakefsSecretKey,
)
clt = LakeFSClient(configuration)

clt.auth_api.create_policy(
    policy=models.Policy(
        id='FSReadTwoRepos',
        statement=[models.Statement(
            effect="deny",
            resource=json.dumps(["arn:lakefs:fs:::repository/repo1","arn:lakefs:fs:::repository/repo2"]),
            action=["fs:ReadRepository"],
        ),
        ]
    )
)

Preconfigured Groups¶

lakeFS has four preconfigured groups:

• Admins
• SuperUsers
• Developers
• Viewers

They have the following policies granted to them:

Pluggable Authentication and Authorization¶

Authorization and authentication is pluggable in lakeFS.

If lakeFS is attached to a remote authentication server (or you are using lakeFS Cloud) then the role-based access control user interface can be used.

If you are using RBAC with your self-managed lakeFS then the lakeFS configuration element auth.ui_config.rbac should be set to external.

An enterprise (paid) solution of lakeFS should set auth.ui_config.rbac as internal.