# Role-Based Access Control (RBAC)

> [!NOTE]
>
> **Available in lakeFS Team and lakeFS Enterprise. [Start a free trial](<https://lakefs.io/try/>) or [contact us](<https://lakefs.io/book-a-demo/>).**

## RBAC Model

Access to resources is managed very much like [AWS IAM](<https://docs.aws.amazon.com/IAM/latest/UserGuide/intro-structure.html>).

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:

```json
{
  "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:**

```json
{
  "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:**

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

**Example - Deny access from IPs NOT in allowed ranges:**

```json
{
  "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:**

The address that `SourceIp` evaluates is the client IP lakeFS resolves for the request, which is configured under [Client IP resolution](<https://docs.lakefs.io/reference/enterprise-configuration/index.md#client-ip-resolution>).

> [!WARNING]
>
> Over AWS PrivateLink the consumer's address may be replaced before the request reaches lakeFS, in which case no lakeFS configuration can recover it and a `SourceIp` condition cannot express the intended restriction. Verify what `source_ip` records in your [audit logs](<https://docs.lakefs.io/admin/auditing/index.md>) before relying on `SourceIp` for a PrivateLink path.

#### 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

> [!NOTE]
>
> **Available in lakeFS Team and lakeFS Enterprise. [Start a free trial](<https://lakefs.io/try/>) or [contact us](<https://lakefs.io/book-a-demo/>).**

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:

```bash
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:

```bash
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:**

```bash
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

```text
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`

```json
{
  "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.

```json
{
  "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):

```json
{
  "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`.

## Attribute-Based Access Control for Objects

lakeFS also supports **attribute-based access control (ABAC) for objects**: policy conditions that gate access based on user-defined metadata attached to the object itself, rather than the repository as a whole. This lets you scope access more precisely than a repository-wide tag allows — for example, matching objects tagged `classification=public` while leaving the rest of the same repository untouched.

Object-level ABAC applies to **read operations only** — `fs:ReadObject` on `GetObject`, `HeadObject`, `StatObject`, and `GetUnderlyingProperties`, as well as the read side of object copy operations. It does not apply to writes or deletes, and `fs:ListObjects` does not filter listing results by object metadata (see the behavior notes below for how presigned listings interact with per-object conditions).

### Setting object metadata

Object metadata is set at upload time using `x-lakefs-meta-*` request headers; each header becomes one metadata key on the object (keys are lower-cased):

```bash
curl -X POST "https://<lakefs-host>/api/v1/repositories/<repo>/branches/<branch>/objects?path=<path>" \
  -H "x-lakefs-meta-classification: public" \
  -H "x-lakefs-meta-owner: data-platform" \
  -u ${LAKECTL_CREDENTIALS_ACCESS_KEY_ID}:${LAKECTL_CREDENTIALS_SECRET_ACCESS_KEY} \
  --data-binary @localfile
```

Metadata set this way is returned in the `metadata` field of `StatObject` and `GetObject` responses, and in `ListObjects` results unless the request sets `user_metadata=false`. The S3 gateway uses the standard `x-amz-meta-*` header convention instead of `x-lakefs-meta-*`, returned the same way on `GetObject`/`HeadObject` responses. Note that S3-gateway metadata keys are stored with the `X-Amz-Meta-` prefix and a lower-cased key part (e.g. `X-Amz-Meta-classification`), so the matching condition key is `lakefs:ObjectMetadata/X-Amz-Meta-classification` — not the bare key you get from the REST API convention above.

### Condition key format

```text
lakefs:ObjectMetadata/<metadata-key>
```

The `<metadata-key>` maps directly to a key in the object's metadata. Matching is case-sensitive — `lakefs:ObjectMetadata/classification` matches only the metadata key `classification`.

Object metadata conditions accept the same [condition operators](<#supported-condition-operators>) as any other policy condition — `StringEquals`, `StringNotEquals`, `StringLike`, and `StringNotLike`.

Metadata keys that lakeFS manages internally (mtime tracking, symlink targets, POSIX permissions, shallow-copy provenance) are never exposed through `lakefs:ObjectMetadata/`, even though they live in the same metadata map as your own tags — only metadata you set yourself is available to conditions.

### Examples

#### Allow read access only to objects tagged `classification=public`

```json
{
  "statement": [
    {
      "action": ["fs:ReadObject"],
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/myrepo/object/*",
      "condition": {
        "StringEquals": {
          "lakefs:ObjectMetadata/classification": ["public"]
        }
      }
    }
  ]
}
```

#### Deny read access to objects tagged `contains_pii=true`, combined with a broad allow

```json
{
  "statement": [
    {
      "action": ["fs:ReadObject"],
      "effect": "deny",
      "resource": "arn:lakefs:fs:::repository/myrepo/object/*",
      "condition": {
        "StringEquals": {
          "lakefs:ObjectMetadata/contains_pii": ["true"]
        }
      }
    }
  ]
}
```

Attach this policy alongside a broader read policy: the user can read every object in `myrepo` except those tagged `contains_pii=true`. Note that this shape lets a caller distinguish a tagged object from one that does not exist; see the [behavior notes](<#behavior-notes>) below.

#### Combine repository and object metadata conditions

Repository-level and object-level ABAC conditions can be used together in the same statement — all specified keys must match:

```json
{
  "statement": [
    {
      "action": ["fs:ReadObject"],
      "effect": "allow",
      "resource": "arn:lakefs:fs:::repository/*/object/*",
      "condition": {
        "StringEquals": {
          "lakefs:RepositoryMetadata/env": ["staging"],
          "lakefs:ObjectMetadata/classification": ["public"]
        }
      }
    }
  ]
}
```

### Behavior notes

- Object-level ABAC is scoped to reads. `fs:ListObjects` does not evaluate object-metadata conditions — a listing returns every object the caller has repository-level access to, regardless of any per-object condition. Listing with `presign=true` is the exception: each result's presigned URL is minted under `fs:ReadObject`, so a condition-denied object still appears in the listing but receives no presigned URL.
- If an object has no metadata, or the requested key is absent, the condition evaluates to `false` and the statement does not apply. A key that exists with an empty string value is different: it's an ordinary match target, so `"StringEquals": {"lakefs:ObjectMetadata/tag": [""]}` matches an object where `tag` is set to an empty value.
- Whether a denial reveals that an object exists depends on the policy shape. Under a conditioned **allow**, a missing object has no metadata to satisfy the condition, so it is denied exactly like an object the caller may not read. Under a broad allow paired with a conditioned **deny**, the deny cannot match an object that does not exist, so a missing path returns not-found (`404`, or `NoSuchKey` on the S3 gateway) while a denied one returns access-denied, revealing both that the object exists and that it carries the denied value. Use a conditioned allow where existence must not be disclosed.
- Condition keys are case-sensitive: `lakefs:ObjectMetadata/CLASSIFICATION` does not match the metadata key `classification`.
- Object-level ABAC is designed for read actions; conditioning a write action (e.g. `fs:WriteObject`) on `lakefs:ObjectMetadata/*` is not a supported combination. On the S3 gateway's copy path (a `PUT` carrying `x-amz-copy-source`), the destination-write and source-read permissions are checked together against one set of attributes, so a write-side object-metadata condition used there would be evaluated against the copy source's metadata, not the destination's.
- On the S3 gateway copy path, **repository** attributes come from the destination repository. If the copy source is in a different repository, a `lakefs:RepositoryMetadata/*` condition is checked against the destination repository's metadata, not the source's. To block copying out of a repository, use a resource ARN instead of a repository-metadata condition.

## Resource naming - ARNs

lakeFS uses [ARN identifier](<https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-arns>) - 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:

| ARN | Meaning |
| --- | --- |
| `arn:lakefs:auth:::user/jane.doe` | A specific user |
| `arn:lakefs:auth:::user/*` | All users |
| `arn:lakefs:fs:::repository/myrepo/*` | All resources under `myrepo` |
| `arn:lakefs:fs:::repository/myrepo/object/foo/bar/baz` | A single object ARN |
| `arn:lakefs:fs:::repository/myrepo/object/*` | All objects in `myrepo` |
| `arn:lakefs:fs:::repository/*` | All repositories |
| `arn:lakefs:fs:::*` | All resources under the fs ARN prefix |
| `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | An Iceberg namespace |
| `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` | An Iceberg table |
| `arn:lakefs:catalog:::view/{repositoryId}/{namespace}/{view}` | An Iceberg view |
| `arn:lakefs:audit:::log` | The lakeFS audit log |

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.

### Scoping a policy to a tenant

The fifth colon-separated field of an ARN is the account segment, which is empty in all of the examples above. On `fs:` ARNs that segment carries the name of a [tenant](<https://docs.lakefs.io/security/tenants/index.md>), so a policy can be pinned to one tenant's data. It behaves as follows:

| ARN | Meaning |
| --- | --- |
| `arn:lakefs:fs:::repository/myrepo` | `myrepo` in every tenant, because the segment is omitted |
| `arn:lakefs:fs::*:repository/myrepo` | `myrepo` in every tenant, stated explicitly |
| `arn:lakefs:fs::team-a:repository/myrepo` | `myrepo` in the tenant `team-a` only |
| `arn:lakefs:fs::root:repository/myrepo` | `myrepo` in the reserved `root` tenant only |

An omitted segment means every tenant rather than the root tenant, which is what keeps policies written before tenants were in use working exactly as they did. Write `root` in the segment only when you specifically want a grant that applies to the root tenant and to no other. Keep in mind that pinning a policy to a tenant narrows a grant but does not confer access on its own, since reaching a tenant's data also requires membership of that tenant.

The account segment carries tenant meaning for `fs:` ARNs only. Tenants themselves are `auth:` resources whose ARNs identify a tenant through the resource path, as in `arn:lakefs:auth:::tenant/team-a`, and the account segment stays empty there.

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:

| Action name | required action | Resource | API endpoint | S3 gateway operation |
| --- | --- | --- | --- | --- |
| List Repositories | `fs:ListRepositories` | `*` | GET `/repositories` | ListBuckets |
| Get Repository | `fs:ReadRepository` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repositoryId}` | HeadBucket |
| Run Metadata Search Query | `fs:ReadRepository` | `arn:lakefs:fs:::repository/{repositoryId}` (every repository the query references) | POST `/mds/query` | \- |
| Get Commit | `fs:ReadCommit` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repositoryId}/commits/{commitId}` | \- |
| Create Commit | `fs:CreateCommit` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` | POST `/repositories/{repositoryId}/branches/{branchId}/commits` | \- |
| Get Commit log | `fs:ReadBranch` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` | GET `/repositories/{repositoryId}/branches/{branchId}/commits` | \- |
| Create Repository | `fs:CreateRepository` | `arn:lakefs:fs:::repository/{repositoryId}` | POST `/repositories` | \- |
| Namespace Attach to Repository | `fs:AttachStorageNamespace` | `arn:lakefs:fs:::namespace/{storageNamespace}` | POST `/repositories` | \- |
| Import From Source | `fs:ImportFromStorage` | `arn:lakefs:fs:::namespace/{storageNamespace}` | POST `/repositories/{repositoryId}/branches/{branchId}/import` | \- |
| Cancel Import | `fs:ImportCancel` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` | DELETE `/repositories/{repositoryId}/branches/{branchId}/import` | \- |
| Delete Repository | `fs:DeleteRepository` | `arn:lakefs:fs:::repository/{repositoryId}` | DELETE `/repositories/{repositoryId}` | \- |
| List Branches | `fs:ListBranches` | `arn:lakefs:fs:::repository/{repositoryId}` or `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` ([details](<#per-branch-scoping-for-listbranches>)) | GET `/repositories/{repositoryId}/branches` | ListObjects/ListObjectsV2 (with delimiter = `/` and empty\` prefix) |
| Get Branch | `fs:ReadBranch` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` | GET `/repositories/{repositoryId}/branches/{branchId}` | \- |
| Create Branch | `fs:CreateBranch` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` | POST `/repositories/{repositoryId}/branches` | \- |
| Delete Branch | `fs:DeleteBranch` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` | DELETE `/repositories/{repositoryId}/branches/{branchId}` | \- |
| Merge branches | `fs:CreateCommit` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{destinationBranchId}` | POST `/repositories/{repositoryId}/refs/{sourceBranchId}/merge/{destinationBranchId}` | \- |
| Diff branch uncommitted changes | `fs:ListObjects` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repositoryId}/branches/{branchId}/diff` | \- |
| Diff refs | `fs:ListObjects` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repositoryId}/refs/{leftRef}/diff/{rightRef}` | \- |
| Stat object | `fs:ReadObject` | `arn:lakefs:fs:::repository/{repositoryId}/object/{objectKey}` | GET `/repositories/{repositoryId}/refs/{ref}/objects/stat` | HeadObject |
| Get Object | `fs:ReadObject` | `arn:lakefs:fs:::repository/{repositoryId}/object/{objectKey}` | GET `/repositories/{repositoryId}/refs/{ref}/objects` | GetObject |
| List Objects | `fs:ListObjects` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repositoryId}/refs/{ref}/objects/ls` | ListObjects, ListObjectsV2 (no delimiter, or "/" + non-empty\` prefix) |
| Upload Object | `fs:WriteObject` | `arn:lakefs:fs:::repository/{repositoryId}/object/{objectKey}` | POST `/repositories/{repositoryId}/branches/{branchId}/objects` | PutObject, CreateMultipartUpload, UploadPart\`, CompleteMultipartUpload |
| Stage Object | `fs:WriteObject`, and `fs:ImportFromStorage` for an address outside the repository's storage namespace | `arn:lakefs:fs:::repository/{repositoryId}/object/{objectKey}` and `arn:lakefs:fs:::namespace/{physicalAddress}` | PUT `/repositories/{repositoryId}/branches/{branchId}/objects` | \- |
| Get Physical Address | `fs:WriteObject` | `arn:lakefs:fs:::repository/{repositoryId}/object/{objectKey}` | GET `/repositories/{repositoryId}/branches/{branchId}/staging/backing` | \- |
| Link Physical Address | `fs:WriteObject`, and `fs:ImportFromStorage` for an address outside the repository's data prefix | `arn:lakefs:fs:::repository/{repositoryId}/object/{objectKey}` and `arn:lakefs:fs:::namespace/{physicalAddress}` | PUT `/repositories/{repositoryId}/branches/{branchId}/staging/backing` | \- |
| Delete Object | `fs:DeleteObject` | `arn:lakefs:fs:::repository/{repositoryId}/object/{objectKey}` | DELETE `/repositories/{repositoryId}/branches/{branchId}/objects` | DeleteObject, DeleteObjects\`, AbortMultipartUpload |
| Revert Branch | `fs:RevertBranch` | `arn:lakefs:fs:::repository/{repositoryId}/branch/{branchId}` | PUT `/repositories/{repositoryId}/branches/{branchId}` | \- |
| Get Branch Protection Rules | `branches:GetBranchProtectionRules` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/branch_protection` | \- |
| Set Branch Protection Rules | `branches:SetBranchProtectionRules` | `arn:lakefs:fs:::repository/{repositoryId}` | POST `/repositories/{repository}/branch_protection` | \- |
| Delete Branch Protection Rules | `branches:SetBranchProtectionRules` | `arn:lakefs:fs:::repository/{repositoryId}` | DELETE `/repositories/{repository}/branch_protection` | \- |
| Create User | `auth:CreateUser` | `arn:lakefs:auth:::user/{userId}` | POST `/auth/users` | \- |
| List Users | `auth:ListUsers` | `*` | GET `/auth/users` | \- |
| Get User | `auth:ReadUser` | `arn:lakefs:auth:::user/{userId}` | GET `/auth/users/{userId}` | \- |
| Delete User | `auth:DeleteUser` | `arn:lakefs:auth:::user/{userId}` | DELETE `/auth/users/{userId}` | \- |
| Get Group | `auth:ReadGroup` | `arn:lakefs:auth:::group/{groupId}` | GET `/auth/groups/{groupId}` | \- |
| List Groups | `auth:ListGroups` | `*` | GET `/auth/groups` | \- |
| Create Group | `auth:CreateGroup` | `arn:lakefs:auth:::group/{groupId}` | POST `/auth/groups` | \- |
| Delete Group | `auth:DeleteGroup` | `arn:lakefs:auth:::group/{groupId}` | DELETE `/auth/groups/{groupId}` | \- |
| List Policies | `auth:ListPolicies` | `*` | GET `/auth/policies` | \- |
| Create Policy | `auth:CreatePolicy` | `arn:lakefs:auth:::policy/{policyId}` | POST `/auth/policies` | \- |
| Update Policy | `auth:UpdatePolicy` | `arn:lakefs:auth:::policy/{policyId}` | POST `/auth/policies` | \- |
| Delete Policy | `auth:DeletePolicy` | `arn:lakefs:auth:::policy/{policyId}` | DELETE `/auth/policies/{policyId}` | \- |
| Get Policy | `auth:ReadPolicy` | `arn:lakefs:auth:::policy/{policyId}` | GET `/auth/policies/{policyId}` | \- |
| List Group Members | `auth:ReadGroup` | `arn:lakefs:auth:::group/{groupId}` | GET `/auth/groups/{groupId}/members` | \- |
| Add Group Member | `auth:AddGroupMember` | `arn:lakefs:auth:::group/{groupId}` | PUT `/auth/groups/{groupId}/members/{userId}` | \- |
| Remove Group Member | `auth:RemoveGroupMember` | `arn:lakefs:auth:::group/{groupId}` | DELETE `/auth/groups/{groupId}/members/{userId}` | \- |
| List User Credentials | `auth:ListCredentials` | `arn:lakefs:auth:::user/{userId}` | GET `/auth/users/{userId}/credentials` | \- |
| Create User Credentials | `auth:CreateCredentials` | `arn:lakefs:auth:::user/{userId}` | POST `/auth/users/{userId}/credentials` | \- |
| Delete User Credentials | `auth:DeleteCredentials` | `arn:lakefs:auth:::user/{userId}` | DELETE `/auth/users/{userId}/credentials/{accessKeyId}` | \- |
| Get User Credentials | `auth:ReadCredentials` | `arn:lakefs:auth:::user/{userId}` | GET `/auth/users/{userId}/credentials/{accessKeyId}` | \- |
| List User Groups | `auth:ReadUser` | `arn:lakefs:auth:::user/{userId}` | GET `/auth/users/{userId}/groups` | \- |
| List User Policies | `auth:ReadUser` | `arn:lakefs:auth:::user/{userId}` | GET `/auth/users/{userId}/policies` | \- |
| Attach Policy To User | `auth:AttachPolicy` | `arn:lakefs:auth:::user/{userId}` | PUT `/auth/users/{userId}/policies/{policyId}` | \- |
| Detach Policy From User | `auth:DetachPolicy` | `arn:lakefs:auth:::user/{userId}` | DELETE `/auth/users/{userId}/policies/{policyId}` | \- |
| List Group Policies | `auth:ReadGroup` | `arn:lakefs:auth:::group/{groupId}` | GET `/auth/groups/{groupId}/policies` | \- |
| Attach Policy To Group | `auth:AttachPolicy` | `arn:lakefs:auth:::group/{groupId}` | PUT `/auth/groups/{groupId}/policies/{policyId}` | \- |
| Detach Policy From Group | `auth:DetachPolicy` | `arn:lakefs:auth:::group/{groupId}` | DELETE `/auth/groups/{groupId}/policies/{policyId}` | \- |
| Attach External Principal to a User | `auth:CreateUserExternalPrincipal` | `arn:lakefs:auth:::user/{userId}` | POST `/auth/users/{userId}/external/principals` | \- |
| Delete External Principal Attachment from a User | `auth:DeleteUserExternalPrincipal` | `arn:lakefs:auth:::user/{userId}` | DELETE `/auth/users/{userId}/external/principals` | \- |
| Get the User attached to an External Principal | `auth:ReadExternalPrincipal` | `arn:lakefs:auth:::externalPrincipal/{principalId}` | GET `/auth/external/principals` | \- |
| List Tenants | `auth:ListTenants` | `arn:lakefs:auth:::tenant/{tenantName}` (admitted per record) | GET `/auth/tenants` | \- |
| Get Tenant | `auth:ReadTenant` | `arn:lakefs:auth:::tenant/{tenantName}` | GET `/auth/tenants/{tenantName}` | \- |
| Create Tenant | `auth:CreateTenant` | `arn:lakefs:auth:::tenant/{tenantName}` | POST `/auth/tenants` | \- |
| Update Tenant | `auth:UpdateTenant` | `arn:lakefs:auth:::tenant/{tenantName}` | PATCH `/auth/tenants/{tenantName}` | \- |
| Delete Tenant | `auth:DeleteTenant` | `arn:lakefs:auth:::tenant/{tenantName}` | DELETE `/auth/tenants/{tenantName}` | \- |
| List Tenant Users | `auth:ReadTenant` | `arn:lakefs:auth:::tenant/{tenantName}` | GET `/auth/tenants/{tenantName}/users` | \- |
| List Tenant Groups | `auth:ReadTenant` | `arn:lakefs:auth:::tenant/{tenantName}` | GET `/auth/tenants/{tenantName}/groups` | \- |
| Attach User To Tenant | `auth:AttachTenantUser` | `arn:lakefs:auth:::tenant/{tenantName}` | PUT `/auth/tenants/{tenantName}/users/{userId}` | \- |
| Detach User From Tenant | `auth:DetachTenantUser` | `arn:lakefs:auth:::tenant/{tenantName}` | DELETE `/auth/tenants/{tenantName}/users/{userId}` | \- |
| Attach Group To Tenant | `auth:AttachTenantGroup` | `arn:lakefs:auth:::tenant/{tenantName}` | PUT `/auth/tenants/{tenantName}/groups/{groupId}` | \- |
| Detach Group From Tenant | `auth:DetachTenantGroup` | `arn:lakefs:auth:::tenant/{tenantName}` | DELETE `/auth/tenants/{tenantName}/groups/{groupId}` | \- |
| Read Storage Config | `fs:ReadConfig` | `*` | GET `/config/storage` | \- |
| Get Garbage Collection Rules | `retention:GetGarbageCollectionRules` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repositoryId}/gc/rules` | \- |
| Set Garbage Collection Rules | `retention:SetGarbageCollectionRules` | `arn:lakefs:fs:::repository/{repositoryId}` | POST `/repositories/{repositoryId}/gc/rules` | \- |
| Prepare Garbage Collection Commits | `retention:PrepareGarbageCollectionCommits` | `arn:lakefs:fs:::repository/{repositoryId}` | POST `/repositories/{repositoryId}/gc/prepare_commits` | \- |
| Get Object Lifecycle Rules | `retention:GetObjectLifecycleRules` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/settings/object_lifecycle` | \- |
| Set Object Lifecycle Rules | `retention:SetObjectLifecycleRules` | `arn:lakefs:fs:::repository/{repositoryId}` | PUT, DELETE `/repositories/{repository}/settings/object_lifecycle` | \- |
| Get Branch Lifecycle Policies | `branches:GetBranchLifecyclePolicies` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/settings/branch_lifecycle/policies` | \- |
| Set Branch Lifecycle Policies | `branches:SetBranchLifecyclePolicies` | `arn:lakefs:fs:::repository/{repositoryId}` | PUT, DELETE `/repositories/{repository}/settings/branch_lifecycle/policies` | \- |
| List Repository Action Runs | `ci:ReadAction` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/actions/runs` | \- |
| Get Action Run | `ci:ReadAction` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/actions/runs/{run_id}` | \- |
| List Action Run Hooks | `ci:ReadAction` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/actions/runs/{run_id}/hooks` | \- |
| Get Action Run Hook Output | `ci:ReadAction` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/actions/runs/{run_id}/hooks/{hook_run_id}/output` | \- |
| Get Pull Request | `pr:ReadPullRequest` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/pulls/{pull_request}` | \- |
| Create Pull Request | `pr:WritePullRequest` | `arn:lakefs:fs:::repository/{repositoryId}` | POST `/repositories/{repository}/pulls` | \- |
| Update Pull Request | `pr:WritePullRequest` | `arn:lakefs:fs:::repository/{repositoryId}` | PATCH `/repositories/{repository}/pulls/{pull_request}` | \- |
| Merge Pull Request | `pr:WritePullRequest` + Merge Branches | `arn:lakefs:fs:::repository/{repositoryId}` | PUT `/repositories/{repository}/pulls/{pull_request}/merge` | \- |
| List Pull Requests | `pr:ListPullRequests` | `arn:lakefs:fs:::repository/{repositoryId}` | GET `/repositories/{repository}/pulls` | \- |
| List Namespaces | `catalog:ListNamespaces` | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | GET `/iceberg/api/v1/{prefix}/namespaces` | \- |
| Get Namespace | `catalog:GetNamespace` | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | GET `/iceberg/api/v1/{prefix}/namespaces/{namespace}` | \- |
| Create Namespace | `catalog:CreateNamespace` | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | POST `/iceberg/api/v1/{prefix}/namespaces` | \- |
| Update Namespace | `catalog:UpdateNamespace` | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | POST `/iceberg/api/v1/{prefix}/namespaces/{namespace}/properties` | \- |
| Delete Namespace | `catalog:DeleteNamespace` | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | DELETE `/iceberg/api/v1/{prefix}/namespaces/{namespace}` | \- |
| List Tables | `catalog:ListTables` | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | GET `/iceberg/api/v1/{prefix}/namespaces/{namespace}/tables` | \- |
| Create Table | `catalog:CreateTable` | `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` | POST `/iceberg/api/v1/{prefix}/namespaces/{namespace}/tables` | \- |
| Read Table | `catalog:ReadTable` | `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` | GET `/iceberg/api/v1/{prefix}/namespaces/{namespace}/tables/{table}` | \- |
| Update Table | `catalog:UpdateTable` | `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` | POST `/iceberg/api/v1/{prefix}/namespaces/{namespace}/tables/{table}` | \- |
| Delete Table | `catalog:DeleteTable` | `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` | DELETE `/iceberg/api/v1/{prefix}/namespaces/{namespace}/tables/{table}` | \- |
| Vend Read Table Data | `catalog:ReadTableData` | `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` | GET `/iceberg/api/v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials` (also vended inline via `X-Iceberg-Access-Delegation`, see [Credentials Vending](<https://docs.lakefs.io/iceberg/index.md#credentials-vending>)) | \- |
| Vend Write Table Data | `catalog:WriteTableData` | `arn:lakefs:catalog:::table/{repositoryId}/{namespace}/{table}` | GET `/iceberg/api/v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials` (also vended inline via `X-Iceberg-Access-Delegation`, see [Credentials Vending](<https://docs.lakefs.io/iceberg/index.md#credentials-vending>)) | \- |
| List Views | `catalog:ListViews` | `arn:lakefs:catalog:::namespace/{repositoryId}/{namespace}` | GET `/iceberg/api/v1/{prefix}/namespaces/{namespace}/views` | \- |
| Create View | `catalog:CreateView` | `arn:lakefs:catalog:::view/{repositoryId}/{namespace}/{view}` | POST `/iceberg/api/v1/{prefix}/namespaces/{namespace}/views` | \- |
| Read View | `catalog:ReadView` | `arn:lakefs:catalog:::view/{repositoryId}/{namespace}/{view}` | GET `/iceberg/api/v1/{prefix}/namespaces/{namespace}/views/{view}` | \- |
| Update View | `catalog:UpdateView` | `arn:lakefs:catalog:::view/{repositoryId}/{namespace}/{view}` | POST `/iceberg/api/v1/{prefix}/namespaces/{namespace}/views/{view}` | \- |
| Delete View | `catalog:DeleteView` | `arn:lakefs:catalog:::view/{repositoryId}/{namespace}/{view}` | DELETE `/iceberg/api/v1/{prefix}/namespaces/{namespace}/views/{view}` | \- |
| Read Audit Log | `audit:ReadAuditLog` | `arn:lakefs:audit:::log` | Iceberg catalog read operations targeting the `lakefssystem` repository | \- |
| Write Audit Log | `audit:WriteAuditLog` | `arn:lakefs:audit:::log` | Iceberg catalog write operations targeting the `lakefssystem` repository | \- |
| Login as Organization Admin *(Cloud only)* | `admin:Login` | `*` | POST `/admin/login` *(part of lakefs cloud, not lakefs endpoint)* | \- |
| List Datasets | `dataset:ListDatasets` | `arn:lakefs:dataset:::dataset/{datasetId}` | GET `/datasets` | \- |
| Read Dataset | `dataset:ReadDataset` | `arn:lakefs:dataset:::dataset/{datasetId}` | GET `/datasets/{dataset}` | \- |
| Create Dataset | `dataset:CreateDataset` | `arn:lakefs:dataset:::dataset/{datasetId}` | POST `/datasets` | \- |
| Update Dataset | `dataset:UpdateDataset` | `arn:lakefs:dataset:::dataset/{datasetId}` | PUT `/datasets/{dataset}` | \- |
| Delete Dataset | `dataset:DeleteDataset` | `arn:lakefs:dataset:::dataset/{datasetId}` | DELETE `/datasets/{dataset}` | \- |
| List Dataset Metadata Keys | `dataset:ListMetadataKeys` | `arn:lakefs:dataset:::dataset/{datasetId}` | GET `/datasets/metadata` | \- |
| Read Dataset Metadata Key | `dataset:ReadMetadataKey` | `arn:lakefs:dataset:::dataset/*` | GET `/datasets/metadata/{key}` | \- |
| Create Dataset Metadata Key | `dataset:CreateMetadataKey` | `arn:lakefs:dataset:::dataset/*` | POST `/datasets/metadata` | \- |
| Update Dataset Metadata Key | `dataset:UpdateMetadataKey` | `arn:lakefs:dataset:::dataset/*` | PUT `/datasets/metadata/{key}` | \- |
| Delete Dataset Metadata Key | `dataset:DeleteMetadataKey` | `arn:lakefs:dataset:::dataset/*` | DELETE `/datasets/metadata/{key}` | \- |

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.

> [!WARNING]
>
> **`fs:ImportFromStorage` grants read access to a storage location**
>
> A user who holds `fs:ImportFromStorage` on a storage location can make lakeFS serve any object under it: import creates entries for the objects it finds there, and `stageObject` and `linkPhysicalAddress` accept any physical address under it. Without that permission, `stageObject` accepts only addresses inside the repository's own storage namespace, and `linkPhysicalAddress` only addresses under the repository's data prefix that `getPhysicalAddress` issued for the path being written. Granting the action on storage that other repositories use therefore exposes their objects regardless of path-scoped `fs:ReadObject` statements or object-level ABAC conditions, so scope its resource ARN to the locations users are meant to import from.

## 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.

| Policy shape | Result |
| --- | --- |
| `Allow` on repo ARN | every branch admitted |
| `Allow` on branch ARN matching `X` | branch `X` admitted, others hidden |
| `Allow` on repo ARN + `Deny` on branch ARN matching `X` | branch `X` hidden, the rest admitted |
| No `Allow` scoped to this repository (none at all, or only on a different one) | request returns `401` (REST) / `403 AccessDenied` (S3) |

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:

```json
{
  "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):

```json
[
  {
    "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.

> [!WARNING]
>
> **Listing visibility is not access control**
>
> Scoping `fs:ListBranches` controls only which branches appear in listings — it does **not** restrict reading or writing them. Access is governed independently by the per-branch and per-object actions (`fs:ReadBranch`, `fs:ReadObject`, `fs:WriteObject`, …): a user who cannot *list* a branch can still read or commit to it if they hold those actions. Use `fs:ListBranches` for discoverability; to confine access, scope the per-branch actions too.

## Preconfigured Policies

The following `Policies` are created during initial setup:

### FSFullAccess

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

### FSReadAll

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

### FSReadWriteAll

```json
{
    "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

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

### AuthManageOwnCredentials

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

### RepoManagementFullAccess

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

### RepoManagementReadAll

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

### AdminFullAccess (lakeFS Cloud only)

```json
{
  "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.

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

### DatasetsFullAccess

Grants full access to all dataset operations. See [Datasets](<https://docs.lakefs.io/datasets/index.md>).

```json
{
  "statement": [
    {
      "action": [
        "dataset:*"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:dataset:::dataset/*"
    }
  ]
}
```

### DatasetsReadWriteAll

Grants list, read, create, update, and delete access to datasets, plus read access to metadata keys.

```json
{
  "statement": [
    {
      "action": [
        "dataset:ListDatasets",
        "dataset:ReadDataset",
        "dataset:CreateDataset",
        "dataset:UpdateDataset",
        "dataset:DeleteDataset",
        "dataset:ListMetadataKeys",
        "dataset:ReadMetadataKey"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:dataset:::dataset/*"
    }
  ]
}
```

### DatasetsReadAll

Grants read-only access to datasets and metadata keys.

```json
{
  "statement": [
    {
      "action": [
        "dataset:ListDatasets",
        "dataset:ReadDataset",
        "dataset:ListMetadataKeys",
        "dataset:ReadMetadataKey"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:dataset:::dataset/*"
    }
  ]
}
```

### DatasetsManageMetadataKeys

Grants full CRUD on dataset metadata key definitions.

```json
{
  "statement": [
    {
      "action": [
        "dataset:ListMetadataKeys",
        "dataset:ReadMetadataKey",
        "dataset:CreateMetadataKey",
        "dataset:UpdateMetadataKey",
        "dataset:DeleteMetadataKey"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:dataset:::dataset/*"
    }
  ]
}
```

## Tenant Administration Policies

Managing [tenants](<https://docs.lakefs.io/security/tenants/index.md>) is governed by the `auth:*Tenant*` actions on tenant ARNs, and the two policies below are recipes that put them to use. Unlike the policies listed above, neither one is created during setup, so you author whichever of them you need: a per-tenant grant has to name the tenant it applies to, and there is no placeholder that stands for "the tenant this user administers" the way `${user}` stands for the current user, so per-tenant delegation is one policy per tenant.

Note that these policies govern tenant *administration* only. Reaching a tenant's repositories additionally requires membership of that tenant, so an administrator who also works with the data has to be attached to the tenant like any other user.

### TenantsAdmin

Grants management of every tenant in the installation, including creating and deleting them. The default administrator's `AuthFullAccess` already covers all of this, so reach for `TenantsAdmin` when you want to hand installation-wide tenant management to someone without also handing over the rest of `auth:*`:

```json
{
  "statement": [
    {
      "action": [
        "auth:*Tenant*"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:auth:::tenant/*"
    }
  ]
}
```

Granting every tenant is also the only way to grant an attachment that covers all of them at once, which is how an installation-wide identity such as the one used by [standalone garbage collection](<https://docs.lakefs.io/admin/garbage-collection/standalone-gc/index.md>) reaches every tenant including tenants created later.

### TenantAdmin-{tenant}

Grants administration of a single tenant, which is the policy to attach to a team's group so the team runs its own tenant. It deliberately omits `auth:CreateTenant` and `auth:DeleteTenant`, leaving the tenant lifecycle with the installation administrator, and it names the tenant in the resource so a separate copy exists per tenant. The name is a convention that keeps a long policy list readable rather than something lakeFS parses:

```json
{
  "statement": [
    {
      "action": [
        "auth:ReadTenant",
        "auth:ListTenants",
        "auth:UpdateTenant",
        "auth:AttachTenantUser",
        "auth:DetachTenantUser",
        "auth:AttachTenantGroup",
        "auth:DetachTenantGroup"
      ],
      "effect": "allow",
      "resource": "arn:lakefs:auth:::tenant/team-a"
    }
  ]
}
```

Attaching that policy to a group completes the delegation, and the resulting administrator can manage their own tenant's membership and description.

Listing tenants admits each record separately, so the listing contains only the tenants their policies allow, and any tenant outside that set answers as though it did not exist rather than reporting that access was denied.

A delegated administrator therefore cannot use the API to find out which other tenants the installation holds.

## Additional Policies

You can create additional policies to further limit user access. Use the web UI or the [lakectl auth](<https://docs.lakefs.io/reference/cli/enterprise/index.md#lakectl-auth-policies-create>) command to create policies.

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

```json
{
    "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.

```json
{
    "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:

```python
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:

| Policy | Admins | SuperUsers | Developers | Viewers |
| --- | --- | --- | --- | --- |
| [`FSFullAccess`](<#fsfullaccess>) | ✅ | ✅ |  |  |
| [`AuthFullAccess`](<#authfullaccess>) | ✅ |  |  |  |
| [`RepoManagementFullAccess`](<#repomanagementfullaccess>) | ✅ |  |  |  |
| [`AuthManageOwnCredentials`](<#authmanageowncredentials>) |  | ✅ | ✅ | ✅ |
| [`RepoManagementReadAll`](<#repomanagementreadall>) |  | ✅ | ✅ |  |
| [`FSReadWriteAll`](<#fsreadwriteall>) |  |  | ✅ |  |
| [`FSReadAll`](<#fsreadall>) |  |  |  | ✅ |
| [`AuditLogRead`](<#auditlogread>) | ✅ |  |  |  |
| [`AdminFullAccess` (*Cloud only)*](<#adminfullaccess-lakefs-cloud-only>) | ✅ |  |  |  |
