yuqi1129 commented on code in PR #12954:
URL: https://github.com/apache/gravitino/pull/12954#discussion_r3986466873
##########
docs/lance-rest-service.md:
##########
@@ -260,9 +267,118 @@ URL encoded: lance_catalog%24schema%24table01
- Supports only **two levels of namespaces** before tables
- Tables **cannot** be nested deeper than schema level
- Parent catalog must be created in Gravitino before using Lance REST API
-- Namespace deletion is recursive and irreversible
+- Namespace deletion defaults to `restrict`; use `cascade` to remove child
metadata
:::
+## Authentication and authorization
+
+### Authentication and deployment modes
+
+Lance REST uses Gravitino's `gravitino.authenticators` configuration for
incoming requests in
+both auxiliary and standalone mode. See
[Authentication](./security/how-to-authenticate.md) for
+configuring the authenticators and their credentials. Health check endpoints
bypass authentication.
+Authentication errors use the Lance JSON error format; unsupported credentials
return HTTP `401`.
+In standalone mode, backend authentication and authorization failures retain
HTTP `401` and `403`
+respectively. Authentication/authorization failures do not include internal
stack traces in `detail`.
+Unexpected failures return HTTP `500` with a generic message; the server logs
retain the exception
+for diagnosis.
+
+| Mode | Identity used for Gravitino metadata
operations
| Metadata authorization
|
+| ---------------------------------- |
-------------------------------------------------------------------------------------------------------------------------------------------------------------
|
--------------------------------------------------------------------------------------------------------------------------------------
|
+| Auxiliary (running with Gravitino) | Authenticated caller, including active
roles; anonymous requests fall back to
`gravitino.lance-rest.gravitino-simple.user-name` (default `lance-rest-server`)
| Enabled by `gravitino.authorization.enable=true` with a configured metalake
|
+| Standalone | Configured service credentials
(`gravitino.lance-rest.gravitino-auth-type` and its simple/OAuth2 settings)
| No Lance REST per-user
metadata authorization; the remote Gravitino server checks the service identity
if its authorization is enabled |
+
+The auxiliary fallback applies only after authentication accepts an anonymous
request. It does
+not recover a rejected authentication attempt. Authenticated callers keep
their own privileges,
+active roles, ownership and audit identity; they do not inherit the service
user's privileges.
+The fallback service user itself needs the privileges required by the
requested operation.
+
+With `simple` authentication, a Basic header supplies a user name without
validating a password,
+and a request without credentials is accepted as anonymous. Some malformed
Basic credentials
+also resolve to anonymous. Use an authenticator that validates credentials
when caller identity
+must be verified; `simple` is not password authentication.
+
+Standalone authenticates incoming requests, but does not forward their
identities or active roles
+to its Gravitino backend. All callers use the configured backend service
identity. Standalone
+per-user authorization and scoped temporary credential vending are outside the
supported scope. The
+backend service identity needs privileges for all underlying Gravitino calls,
including existence
+checks performed before mutations (for example, catalog access before creating
a namespace).
+
+### Enable auxiliary metadata authorization
+
+Configure `${GRAVITINO_HOME}/conf/gravitino.conf`:
+
+```properties
+gravitino.auxService.names = lance-rest
+gravitino.lance-rest.gravitino-metalake = my_metalake
+gravitino.authorization.enable = true
+gravitino.authorization.serviceAdmins = adminUser
+# Development example: simple accepts the supplied user name without password
validation.
+gravitino.authenticators = simple
+gravitino.lance-rest.gravitino-simple.user-name = lance-rest-server
Review Comment:
Removed this setting from the auxiliary authorization example in 286fd98227
and clarified that it is optional. In auxiliary mode, it only supplies the
fallback identity for requests accepted as anonymous; authenticated requests
retain the caller identity and active roles. The default is already
`lance-rest-server`, so setting it explicitly is only needed to override that
fallback. This does not recover rejected authentication attempts.
Documentation-only change; `spotlessApply` and `git diff --check` passed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
