ACL server implementation documentation by Annaseli · Pull Request #8886 · treeverse/lakeFS

Annaseli · 2025-03-27T13:58:48Z

Closes https://github.com/treeverse/product/issues/684

Change Description

Added documentation for ACL server implementation. The documentation includes the following:

A step-by-step guide for implementing the ACL server, available in: docs/security/ACL-server-implementation.md.
Descriptions for all APIs and schemas in the api/authorization.yml file, provided under the description fields within the YAML.
A Swagger-style UI to visualize the authorization.yml file.:

To support this, the following files were added:
- docs/security/authorization-yaml.md
- docs/_includes/authorization.html
- docs/assets/js/swagger-ui-authorization.js
- docs/assets/js/authorization.yml

github-actions · 2025-03-27T14:00:18Z

♻️ PR Preview 210ee41 has been successfully destroyed since this PR has been closed.

_{🤖 By surge-preview}

github-actions · 2025-03-27T14:07:17Z

E2E Test Results - Quickstart

github-actions · 2025-03-27T14:07:24Z

E2E Test Results - DynamoDB Local - Local Block Adapter

N-o-Z · 2025-03-27T16:08:51Z

@Annaseli Is this ready for review?
If so can you remove it from draft please

Annaseli · 2025-03-27T18:30:02Z

@Annaseli Is this ready for review? If so can you remove it from draft please

@N-o-Z
Guy asked me to keep it in draft for now, as he wants to make sure it’s fully ready for review.

nopcoder

added some comments - partial review will do it in parts

nopcoder · 2025-03-30T07:01:35Z

+
  parameters:
    PaginationPrefix:
+      description: Indicates the prefix that all returned items must start with. lakeFS uses this value to filter


Relevant to the complete file - remove the use of lakeFS in the description as it makes the spec focus on lakeFS service while it is important to describe the use-case without specifying the component name.

@nopcoder
I removed all mentions of lakeFS except for this one:

- in: query description: Used only in lakeFS Enterprise; not applicable in the lakeFS OSS version. name: external_id schema: type: string

Should I replace "Used only in lakeFS Enterprise; not applicable in the lakeFS OSS version." with "For internal use only"?

nopcoder · 2025-03-30T07:09:23Z

          type: integer
          minimum: 0
-          description: Maximal number of entries per page
+          description: Maximum number of entries per page. Not currently used, so it can be set to 0.


Maximum number of entries per page. Set to zero when not in use.

@nopcoder
I wanted to note that while we expect this Pagination schema in the response, we don’t actually use the max_per_page parameter. Should I update the description to:
“Maximum number of entries per page. Not used internally.”?

nopcoder · 2025-03-30T07:23:04Z

+          description: Can be empty.
        external_id:
          type: string
+          description: For internal usage. Can be empty.


The field is not required so no need to add the description for this one or the other that it can be empty - unless empty value "" have a meaning.

@nopcoder
Should I write: "description: For internal use only."
or would it be better to remove the description completely?

general description at the level of the operation/api will explain that the data should be loaded/stored. on the field itself if we want to specify what the field does we can - in this case we use the field for external system association.

Annaseli · 2025-03-30T16:53:05Z

@nopcoder
Should I push the fixes I made based on your comments now, or wait until you've finished the full review to avoid disrupting the review process?

nopcoder · 2025-03-30T17:31:00Z

feel free to push updates, I'll restart tomorrow

…ile with Swagger colors.

…le of contents and notes and updated the links for the authorization.yml file to show up in a page.

…thorization.yml

nopcoder · 2025-04-02T14:07:48Z

+      description: Specifies the number of items the server should return. It is used to determine how many results to 
+        display on the current page.


without the "display" and "current page" - we describe API and not the usage

nopcoder · 2025-04-02T19:10:43Z

          type: string
+          description: User source. Based on implementation.
        encryptedPassword:
+          deprecated: true


this is new? we no longer use this field?
defer to a different PR

nopcoder · 2025-04-02T22:29:21Z

        - in: query
+          deprecated: true
          name: id
          allowEmptyValue: true
          schema:
            type: integer
            format: int64
        - in: query
+          deprecated: true


If the deprecation is new I suggest to do it in a non documentation PR

nopcoder · 2025-04-02T22:30:10Z

          schema:
            type: string
        - in: query
+          description: Used only in lakeFS Enterprise; not applicable in the lakeFS OSS version.


Used by the implementor to link external system

nopcoder · 2025-04-03T09:10:33Z

+- `PUT /auth/policies/{policyId}`
+- `DELETE /auth/policies/{policyId}`
+
+### 2. LakeFS Configuration


Suggested change

### 2. LakeFS Configuration

### 2. lakeFS Configuration

nopcoder · 2025-04-03T09:11:51Z

+    rbac: internal
+  api:
+    endpoint: {ENDPOINT_TO_YOUR_RBAC_SERVER} # e.g., http://localhost:9006/api/v1
+    token:


sample of how token looks like or comment

nopcoder · 2025-04-03T09:12:50Z

+> The `auth.api.token` parameter is optional. If unspecified, lakeFS uses the `auth.encrypt.secret_key` as 
+> the token. If specified, provide a JWT token directly or via the environment variable `LAKEFS_AUTH_API_TOKEN`.


secret_key is not used as token as it doesn't leave the local environment.
explain the process of how the request get token when no explicit token is specified.

nopcoder · 2025-04-03T09:15:51Z

+When lakeFS starts for the first time, it initializes users, groups, and policies. Once initialized, 
+the authorization method cannot change. If lakeFS starts without an RBAC server and later tries connecting to one, 
+it will fail to authenticate. You must re-initialize lakeFS from scratch to connect to a new RBAC server.


unclear - if we must "re-initialize" it means we can initialize and we said that lakeFS done it automatically.

verify that lakeFS create something on startup without explicit command

if we instruct the user to "re-iinitialize" we need to explain how

nopcoder · 2025-04-03T09:17:44Z

+2. Run lakeFS with the updated configuration file:
+
+```shell
+./lakefs -c {PATH_TO_YOUR_CONFIG_FILE} run


Running a command similar to ./lakefs -c config.yaml run provides more detailed output.
Or note to remember to replace "config.yaml" with the actual path to your configuration file.

itaigilo · 2025-05-23T09:08:41Z

@Annaseli is this still relevant, or can be closed?

Annaseli · 2025-05-26T08:40:04Z

@Annaseli is this still relevant, or can be closed?

@itaigilo
Barak and Guy will update this PR to document the ACL instead of RBAC, so they’ll continue this PR.

* Document ACL implementation * updates * Updated ACL server implementation documentation * Update docs/security/ACL-server-implementation.md Co-authored-by: guy-har <[email protected]> --------- Co-authored-by: guy-har <[email protected]>

nopcoder · 2025-05-28T11:02:00Z

          type: string
+          description: User source. Based on implementation.
        encryptedPassword:
+          deprecated: true


defer the change to a different pr

nopcoder · 2025-05-31T16:29:47Z

@Annaseli merged the approved changes from a side branch and merging this PR.

Annaseli requested review from a team, guy-har and nopcoder March 27, 2025 13:58

Annaseli added docs Improvements or additions to documentation include-changelog PR description should be included in next release changelog labels Mar 27, 2025

nopcoder reviewed Mar 30, 2025

View reviewed changes

Annaseli marked this pull request as ready for review March 30, 2025 16:49

Annaseli added 7 commits March 31, 2025 18:24

Created documentation for implementing auth server

6552ba8

Added more documentatiin

96a4b3c

Added more documentatiin 2

2486739

Refined the docs and added a page that shows the authorization.yaml f…

404ed73

…ile with Swagger colors.

Removed the word "Depricated" from the title, updated the view of tab…

3106f0c

…le of contents and notes and updated the links for the authorization.yml file to show up in a page.

Added missing things from the doc.

05b766b

Edited the description in the yaml file as requested in the review.

ce2843e

Annaseli force-pushed the docs/document-RBAC-implementation-684 branch from 21ea119 to ce2843e Compare April 1, 2025 08:53

run make build to copy the api/authorization.yml to docs/assets/js/au…

a0bcfa2

…thorization.yml

Annaseli requested a review from nopcoder April 1, 2025 09:04

Fixed description.

21dc28c

nopcoder reviewed Apr 3, 2025

View reviewed changes

guy-har changed the title ~~RBAC server implementation documentation~~ ACL server implementation documentation May 27, 2025

Remove changes that might effect generated code

94e3c5e

guy-har force-pushed the docs/document-RBAC-implementation-684 branch from 924c833 to 94e3c5e Compare May 27, 2025 15:09

guy-har approved these changes May 27, 2025

View reviewed changes

guy-har added minor-change Used for PRs that don't require issue attached exclude-changelog PR description should not be included in next release changelog and removed include-changelog PR description should be included in next release changelog labels May 27, 2025

nopcoder reviewed May 28, 2025

View reviewed changes

nopcoder added 2 commits May 31, 2025 19:18

latest updates to the interface and documentation

7d4157d

revert required username in UserCreation

210ee41

nopcoder enabled auto-merge (squash) May 31, 2025 16:30

nopcoder merged commit 78b36ad into master May 31, 2025
42 of 43 checks passed

nopcoder deleted the docs/document-RBAC-implementation-684 branch May 31, 2025 16:46

		description: Specifies the number of items the server should return. It is used to determine how many results to
		display on the current page.

		> The `auth.api.token` parameter is optional. If unspecified, lakeFS uses the `auth.encrypt.secret_key` as
		> the token. If specified, provide a JWT token directly or via the environment variable `LAKEFS_AUTH_API_TOKEN`.

Conversation

Annaseli commented Mar 27, 2025 • edited by guy-har Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Change Description

Uh oh!

github-actions Bot commented Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Mar 27, 2025

E2E Test Results - Quickstart

Uh oh!

github-actions Bot commented Mar 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Test Results - DynamoDB Local - Local Block Adapter

Uh oh!

N-o-Z commented Mar 27, 2025

Uh oh!

Annaseli commented Mar 27, 2025

Uh oh!

nopcoder left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Annaseli Mar 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Annaseli commented Mar 30, 2025

Uh oh!

nopcoder commented Mar 30, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nopcoder Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

itaigilo commented May 23, 2025

Uh oh!

Annaseli commented May 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nopcoder commented May 31, 2025

Uh oh!

Uh oh!

Reviewers

Annaseli commented Mar 27, 2025 •

edited by guy-har

Loading

github-actions Bot commented Mar 27, 2025 •

edited

Loading

github-actions Bot commented Mar 27, 2025 •

edited

Loading

Annaseli Mar 30, 2025 •

edited

Loading

nopcoder Apr 2, 2025 •

edited

Loading