authz

docs/src/python/python.md

@@ -48,6 +48,168 @@ are ordinary connections. Dropping a database requires it to be empty.
 ::: lancedb.catalog.DatabaseNames
 
 
+## Authorization
+
+Some catalogs support the authorization API. This is an API that can be used to
+bind access control lists (ACLs) to individual catalog objects.
+
+Each ACL contains a subject, an object, and privilege.
+
+### Subjects
+
+There are three kinds of subjects: principals, groups, and roles.
+
+A principal uniquely identifies each user accessing the system. Each LanceDB
+Enterprise API key corresponds to a unique principal, and each OpenID user has
+a unique principal.
+
+All principals have an immutable ID which never changes, and is safe to include
+in log files. For example, the API key
+`sk_AAAQEAYEAUDAOCAJBIFQYDIOB4IBCEQTCQKRMFYYDENBWHA5DYPQ====` maps to the
+principal ID `pk_aaaqeayeaudaocajbifqydiob4`. APIs such as `list_acls` will
+return the principal ID, never the API key.
+
+OpenID principals also typically have a human-readable name associated with
+them. For example, a principal might be named `bob@example.com` and might have
+a principal ID of `8a004400-9443-4fab-9997-b9372a7ca8fdCopy`. Whenever
+possible, APIs will return the principal name for convenience. However,
+principal names are mutable and can be changed by the identity provider.
+
+Here is an example of getting information about an API key:
+```python
+from lancedb.authz import Subject
+catalog = lancedb.connect_catalog("https://catalog.example.com", api_key=api_key)
+principal = catalog.authz.get_principal(Subject.principal_api_key(api_key))
+print(f"Found principal {principal.principal_id}")
+```
+
+OpenID principals can be members of groups. Like principals, groups also have
+IDs and human-readable names. It is not possible to modify group membership via
+this API; it is managed by the OpenID identity provider.
+
+Here is an example of getting information about a group based on its name:
+```python
+from lancedb.authz import Subject
+catalog = lancedb.connect_catalog("https://catalog.example.com", api_key=api_key)
+group = catalog.authz.get_group(Subject.group_name("Engineering"))
+print(f"Found group {group.group_id} with name {group.group_name}")
+```
+
+Roles can contain either principals or groups. Unlike groups, they are managed
+by the catalog, not the identity provider. Roles can also contain API key
+principals.
+
+Here is an example of managing the `reader` role:
+```python
+from lancedb.authz import Subject
+catalog = lancedb.connect_catalog("https://catalog.example.com", api_key=api_key)
+catalog.authz.add_role_binding(
+    subject=Subject.principal_name("Alice"),
+    role="reader"
+)
+```
+It may take a few milliseconds for changes to role bindings to become visible
+to all clients.
+
+More subject types may be added in the future.
+
+### Objects
+
+An object is any resource in the system that we can attach authorization rules to.
+The Python builders and Rust client share resource validation and wire encoding.
+Methods also accept literal strings such as `table:tenant/db:public$events`;
+malformed names for known resource types raise `ValueError` locally before a
+request is sent. Unknown resource types are preserved for compatibility with
+newer servers.
+
+Object types include:
+
+The System object, a singleton which represents the entire system. You can
+refer to it as `Object.system()`.
+
+Database objects which represents specific databases. For example,
+`Object.database("analytics")` represents the "analytics" database.
+
+Table objects which represent specific tables. For example,
+`Object.table(database="analytics", name="events")` represents the "events"
+table inside the "analytics" database. Tables are in the default namespace (which
+is named "public") unless a specific namespaces is given.
+
+Similarly, View objects represent specific views. For example,
+`Object.view(database="analytics", name="recent_events")` represents the
+"recent_events" view inside the "analytics" table. Views are in the default
+namespace (which is named "public") unless a specific namespaces is given.
+
+Secret objects identify named credentials, for example,
+`Object.secret(database="analytics", name="api-key")`. Function objects identify
+registered functions, for example,
+`Object.function(database="analytics", name="caption")`. Both default to the
+`public` namespace. Pass `namespace=["platform", "ml"]` to select a nested
+namespace. These objects identify resources for ACL operations; a secret object
+contains the credential's name, not its value.
+
+More object types may be added in the future.
+
+### Access control lists
+
+An access control list attaches a specific set of privileges to a specific
+(subject, object) pair. So, for example, we might have an access control list
+that gives `bob@example.com` the ability to read the foo table, that looks like
+this:
+
+```python
+from lancedb.authz import Object, Subject, Privilege
+
+catalog = lancedb.connect_catalog("https://catalog.example.com", api_key=api_key)
+catalog.authz.add_acl(
+    object=Object.table(database="analytics", name="foo"),
+    subject=Subject.principal_name("bob@example.com"),
+    privilege=Privilege.SELECT,
+)
+```
+
+Reading a table generally requires USAGE on its database and namespace, plus
+SELECT on the table. Each object has at most one owner.
+
+OWNERSHIP is a special privilege which grants all the other privileges. By
+default, the principal who created an object owns it. Only one subject can own
+an object; granting OWNERSHIP to a new subject removes it from the previous
+owner. OWNERSHIP cannot be deleted.
+
+To delegate secret or function creation, grant `CREATE_SECRET` or
+`CREATE_FUNCTION` on the containing namespace. This preserves namespace ownership:
+
+```python
+for privilege in [Privilege.CREATE_SECRET, Privilege.CREATE_FUNCTION]:
+    catalog.authz.add_acl(
+        object=Object.namespace(database="analytics", namespace=["public"]),
+        subject=Subject.role("developer"),
+        privilege=privilege,
+    )
+```
+
+Both privileges also accept their string names in synchronous and asynchronous
+ACL methods.
+
+By default, the `list_acls` function lists all the access control entries in
+the system. By adding a function parameter, the output is filtered to just ACLs
+matching that parameter. For example, this code lists all the ACLs for the
+"reader" role:
+
+```python
+from lancedb.authz import Subject
+catalog = lancedb.connect_catalog("https://catalog.example.com", api_key=api_key)
+for entry in catalog.authz.list_acls(subject=Subject.role("reader")):
+    print(entry)
+```
+
+Or, when using the async API:
+```python
+catalog = await lancedb.connect_catalog_async(endpoint, api_key=api_key)
+async for entry in catalog.authz.list_acls(subject=Subject.role("reader")):
+    print(entry)
+```
+
 ## Remote SQL
 
 Submit SQL against a remote LanceDB database through the connection.
@@ -359,6 +521,8 @@ still work. Queries return descriptors. Call
 
 ## Exceptions
 
+::: lancedb.remote.errors.HttpError
+
 ::: lancedb.exceptions.MissingValueError
 
 ::: lancedb.exceptions.MissingColumnError