Copilot commented on code in PR #11281:
URL: https://github.com/apache/gravitino/pull/11281#discussion_r3316638222
##########
docs/how-to-use-built-in-idp.md:
##########
@@ -0,0 +1,249 @@
+---
+title: How to use built-in IDP (local authentication)
+slug: /how-to-use-built-in-idp
+license: "This software is licensed under the Apache License version 2."
+---
+
+## Introduction
+
+Apache Gravitino can store **built-in IDP** (identity provider) users and
groups in the relational
+metadata store through the `idp-basic` plugin. This gives you a self-contained
way to manage
+**global** login identities (usernames, password hashes, and group membership)
without an external
+OAuth server.
+
+Built-in IDP is aimed at POC, offline, and isolated deployments. It is **not**
a replacement for
+enterprise IDPs such as Okta, Azure AD, or Keycloak. Use it only where a
lightweight local identity
+store is acceptable; restrict management APIs to **service admins**, store
password hashes only,
+and prefer [HTTPS](./security/how-to-use-https.md) when credentials travel
over the network.
+
+This guide describes how to enable and operate the management APIs in
`plugins:idp-basic`. For
+design background, see
+[Design of local authentication
support](../design-docs/gravitino-local-authentication.md). For
Review Comment:
This guide lives under `docs/` and the design doc lives under `design-docs/`
at the repository root, so the relative link should be
`../design-docs/gravitino-local-authentication.md` only if the docs site
preserves that layout. Most other doc cross-links in this file use `./...`
within `docs/`. Please verify this relative path resolves on the rendered docs
site (e.g., Docusaurus typically only serves files under `docs/`), otherwise
this link will 404. The same concern applies to the duplicate reference on line
248.
##########
docs/how-to-use-built-in-idp.md:
##########
@@ -0,0 +1,249 @@
+---
+title: How to use built-in IDP (local authentication)
Review Comment:
The title and prose use `IDP` while the surrounding docs and design doc text
consistently refer to `IdP` / `built-in IdP` (e.g., `docs/index.md` line 214
says `Built-in IDP` but the design doc and module name use `idp-basic`). Pick a
single capitalization (`IdP` is the conventional form for Identity Provider)
and use it consistently across the new guide, the index entry, and the security
index to avoid reader confusion.
##########
design-docs/gravitino-local-authentication.md:
##########
@@ -279,75 +270,67 @@ preserving the requirement that local identity tables
remain global and metalake
## 6. Service Admin Initialization
To keep local authentication usable immediately after installation without
introducing a hard-coded
-default password, Gravitino should initialize service admin accounts from an
environment variable
-during startup when the `basic` authenticator is enabled.
+default password, Gravitino initializes service admin accounts from an
environment variable during
+startup.
### 6.1 Initialization Inputs
After Gravitino is installed, the operator should configure:
- `gravitino.authorization.serviceAdmins`, which remains the source of truth
for service admin
usernames
-- `GRAVITINO_INITIAL_ADMIN_PASSWORD`, a JSON array of `username:password`
strings used only when a
- configured service admin does not already have a password configured in the
gravitino
-
-Each username in `GRAVITINO_INITIAL_ADMIN_PASSWORD` should match a user
configured in
-`gravitino.authorization.serviceAdmins`.
+- `GRAVITINO_INITIAL_ADMIN_PASSWORD`, the initial password for service admins
that do not yet have a
+ row in `idp_user_meta`. Usernames come from
`gravitino.authorization.serviceAdmins`.
Review Comment:
The semantics of `GRAVITINO_INITIAL_ADMIN_PASSWORD` changed from a JSON
array of `username:password` entries to a single shared password applied to
every service admin. This is a meaningful behavioral change worth calling out
explicitly (e.g., 'the same password is applied to every uninitialized service
admin in `gravitino.authorization.serviceAdmins`'), since operators reading
only this section may assume per-admin passwords. Consider also documenting the
security tradeoff of sharing one initial password across multiple admin
accounts.
##########
docs/how-to-use-built-in-idp.md:
##########
@@ -0,0 +1,249 @@
+---
+title: How to use built-in IDP (local authentication)
+slug: /how-to-use-built-in-idp
+license: "This software is licensed under the Apache License version 2."
+---
+
+## Introduction
+
+Apache Gravitino can store **built-in IDP** (identity provider) users and
groups in the relational
+metadata store through the `idp-basic` plugin. This gives you a self-contained
way to manage
+**global** login identities (usernames, password hashes, and group membership)
without an external
+OAuth server.
+
+Built-in IDP is aimed at POC, offline, and isolated deployments. It is **not**
a replacement for
+enterprise IDPs such as Okta, Azure AD, or Keycloak. Use it only where a
lightweight local identity
+store is acceptable; restrict management APIs to **service admins**, store
password hashes only,
+and prefer [HTTPS](./security/how-to-use-https.md) when credentials travel
over the network.
+
+This guide describes how to enable and operate the management APIs in
`plugins:idp-basic`. For
+design background, see
+[Design of local authentication
support](../design-docs/gravitino-local-authentication.md). For
+request and response schemas, see the [Built-in IDP
OpenAPI](./open-api/idp/openapi.yaml).
+
+---
+
+## Prerequisites
+
+Before you call `/api/idp/*`, ensure the following:
+
+1. **IDP REST API registration** — In `gravitino.conf`, set:
+
+ ```properties
+ gravitino.server.rest.extensionPackages =
org.apache.gravitino.idp.web.rest.feature
+ ```
+
+2. **IDP database tables** — Run the appropriate upgrade script under
`${GRAVITINO_HOME}/scripts/`
+ so the relational store contains `idp_user_meta`, `idp_group_meta`, and
`idp_user_group_rel`
+ (for example `scripts/mysql/upgrade-1.2.0-to-1.3.0-mysql.sql`). See
+ [How to use relational backend
storage](./how-to-use-relational-backend-storage.md).
+
+3. **Service admin passwords** — Built-in IDP requires every username in
+ `gravitino.authorization.serviceAdmins` to have a password stored in
`idp_user_meta` before you
+ can call management APIs.
+
+ 1. Enable authorization and set service admin usernames in `gravitino.conf`
(see
+ [Access control](./security/access-control.md)):
+
+ ```properties
+ gravitino.authorization.enable = true
+ gravitino.authorization.serviceAdmins = admin
+ ```
+
+ 2. **Initialize service admin passwords at startup** — Before the first
start, set
+ `GRAVITINO_INITIAL_ADMIN_PASSWORD` to the initial password. Usernames
come from
+ `gravitino.authorization.serviceAdmins`. The value must satisfy the
+ [password rules](#password-and-username-rules) below.
+
+ ```shell
+ export GRAVITINO_INITIAL_ADMIN_PASSWORD='Passw0rd-Admin12'
+ ```
+
+ 3. **Start or restart Gravitino**.
+
+ 4. **Call management APIs** — Use HTTP Basic authentication with a service
admin username and
+ password (for example `admin` / `Passw0rd-Admin12`).
+
+---
+
+## Configuration
+
+Set authorization and service admins in `gravitino.conf` (see also
[Prerequisites](#prerequisites)):
+
+| Configuration item | Description
| Example |
+|-----------------------------------------|------------------------------------------|---------|
+| `gravitino.authorization.enable` | Enable Gravitino authorization
| `true` |
+| `gravitino.authorization.serviceAdmins` | Usernames allowed to manage
`/api/idp/*` | `admin` |
+
+Example:
+
+```properties
+gravitino.authorization.enable = true
+gravitino.server.rest.extensionPackages =
org.apache.gravitino.idp.web.rest.feature
+gravitino.authorization.serviceAdmins = admin
+```
+
+---
+
+## Operations
+
+The following sections show how to call built-in IDP management APIs with
`curl`. Replace
+`localhost:8090`, usernames, and passwords with values that match your
deployment. Examples use HTTP
+Basic with `admin` / `Passw0rd-Admin12` (from [Prerequisites](#prerequisites)).
+
+**Base URL** — `http://<host>:<port>/api/idp`
+
+**Common headers**
+
+| Header | Value |
+|----------------|----------------------------------------------|
+| `Accept` | `application/vnd.gravitino.v1+json` |
+| `Content-Type` | `application/json` (for POST and PUT bodies) |
+
+Example:
+
+```shell
+curl -s -H "Accept: application/vnd.gravitino.v1+json" \
+ -H "Authorization: Basic $(echo -n 'admin:Passw0rd-Admin12' | base64)" \
+ http://localhost:8090/api/idp/users/alice
+```
+
+### Password and username rules
+
+Password rules apply to add-user, change-password, and
`GRAVITINO_INITIAL_ADMIN_PASSWORD`:
+
+| Rule | Value |
+|-----------------|------------------------------------|
+| Username | Required; must **not** contain `:` |
+| Password length | 12–64 characters (inclusive) |
+
+Password reset is **admin-only** (request body has `password` only; no
`oldPassword`).
+
+### User operations
+
+#### Get a user
+
+`GET /api/idp/users/{user}`
+
+```shell
+curl -s -H "Accept: application/vnd.gravitino.v1+json" \
+ -H "Authorization: Basic $(echo -n 'admin:Passw0rd-Admin12' | base64)" \
+ http://localhost:8090/api/idp/users/alice
+```
+
+#### Add a user
+
+`POST /api/idp/users`
+
+The request body uses field `user` (not `name`):
+
+```shell
+curl -s -X POST -H "Accept: application/vnd.gravitino.v1+json" \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Basic $(echo -n 'admin:Passw0rd-Admin12' | base64)" \
+ -d '{"user":"alice","password":"Passw0rd-Alice"}' \
+ http://localhost:8090/api/idp/users
+```
+
+#### Change a user password
+
+`PUT /api/idp/users/{user}`
+
+Administrator reset only:
+
+```shell
+curl -s -X PUT -H "Accept: application/vnd.gravitino.v1+json" \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Basic $(echo -n 'admin:Passw0rd-Admin12' | base64)" \
+ -d '{"password":"Passw0rd-Alice-V2"}' \
+ http://localhost:8090/api/idp/users/alice
+```
+
+#### Remove a user
+
+`DELETE /api/idp/users/{user}`
+
+Soft-deletes the user (`deleted_at`). Physical removal is handled by the IDP
garbage collector.
Review Comment:
The 'IDP garbage collector' is mentioned here without any prior introduction
or link to its configuration/behavior in this guide or the design doc excerpts.
Either remove the reference or link to the section that explains the garbage
collection lifecycle so readers know what to expect (e.g., retention period,
how to trigger physical deletion).
##########
docs/how-to-use-built-in-idp.md:
##########
@@ -0,0 +1,249 @@
+---
+title: How to use built-in IDP (local authentication)
+slug: /how-to-use-built-in-idp
+license: "This software is licensed under the Apache License version 2."
+---
+
+## Introduction
+
+Apache Gravitino can store **built-in IDP** (identity provider) users and
groups in the relational
+metadata store through the `idp-basic` plugin. This gives you a self-contained
way to manage
+**global** login identities (usernames, password hashes, and group membership)
without an external
+OAuth server.
+
+Built-in IDP is aimed at POC, offline, and isolated deployments. It is **not**
a replacement for
+enterprise IDPs such as Okta, Azure AD, or Keycloak. Use it only where a
lightweight local identity
+store is acceptable; restrict management APIs to **service admins**, store
password hashes only,
+and prefer [HTTPS](./security/how-to-use-https.md) when credentials travel
over the network.
+
+This guide describes how to enable and operate the management APIs in
`plugins:idp-basic`. For
+design background, see
+[Design of local authentication
support](../design-docs/gravitino-local-authentication.md). For
+request and response schemas, see the [Built-in IDP
OpenAPI](./open-api/idp/openapi.yaml).
+
+---
+
+## Prerequisites
+
+Before you call `/api/idp/*`, ensure the following:
+
+1. **IDP REST API registration** — In `gravitino.conf`, set:
+
+ ```properties
+ gravitino.server.rest.extensionPackages =
org.apache.gravitino.idp.web.rest.feature
+ ```
+
+2. **IDP database tables** — Run the appropriate upgrade script under
`${GRAVITINO_HOME}/scripts/`
+ so the relational store contains `idp_user_meta`, `idp_group_meta`, and
`idp_user_group_rel`
+ (for example `scripts/mysql/upgrade-1.2.0-to-1.3.0-mysql.sql`). See
+ [How to use relational backend
storage](./how-to-use-relational-backend-storage.md).
+
+3. **Service admin passwords** — Built-in IDP requires every username in
+ `gravitino.authorization.serviceAdmins` to have a password stored in
`idp_user_meta` before you
+ can call management APIs.
+
+ 1. Enable authorization and set service admin usernames in `gravitino.conf`
(see
+ [Access control](./security/access-control.md)):
+
+ ```properties
+ gravitino.authorization.enable = true
+ gravitino.authorization.serviceAdmins = admin
+ ```
+
+ 2. **Initialize service admin passwords at startup** — Before the first
start, set
+ `GRAVITINO_INITIAL_ADMIN_PASSWORD` to the initial password. Usernames
come from
+ `gravitino.authorization.serviceAdmins`. The value must satisfy the
+ [password rules](#password-and-username-rules) below.
+
+ ```shell
+ export GRAVITINO_INITIAL_ADMIN_PASSWORD='Passw0rd-Admin12'
+ ```
+
+ 3. **Start or restart Gravitino**.
+
+ 4. **Call management APIs** — Use HTTP Basic authentication with a service
admin username and
+ password (for example `admin` / `Passw0rd-Admin12`).
+
+---
+
+## Configuration
+
+Set authorization and service admins in `gravitino.conf` (see also
[Prerequisites](#prerequisites)):
+
+| Configuration item | Description
| Example |
+|-----------------------------------------|------------------------------------------|---------|
+| `gravitino.authorization.enable` | Enable Gravitino authorization
| `true` |
+| `gravitino.authorization.serviceAdmins` | Usernames allowed to manage
`/api/idp/*` | `admin` |
+
+Example:
+
+```properties
+gravitino.authorization.enable = true
+gravitino.server.rest.extensionPackages =
org.apache.gravitino.idp.web.rest.feature
+gravitino.authorization.serviceAdmins = admin
+```
+
+---
+
+## Operations
+
+The following sections show how to call built-in IDP management APIs with
`curl`. Replace
+`localhost:8090`, usernames, and passwords with values that match your
deployment. Examples use HTTP
+Basic with `admin` / `Passw0rd-Admin12` (from [Prerequisites](#prerequisites)).
+
+**Base URL** — `http://<host>:<port>/api/idp`
+
+**Common headers**
+
+| Header | Value |
+|----------------|----------------------------------------------|
+| `Accept` | `application/vnd.gravitino.v1+json` |
+| `Content-Type` | `application/json` (for POST and PUT bodies) |
+
+Example:
+
+```shell
+curl -s -H "Accept: application/vnd.gravitino.v1+json" \
+ -H "Authorization: Basic $(echo -n 'admin:Passw0rd-Admin12' | base64)" \
Review Comment:
On many systems `base64` wraps output at 76 columns by default (notably GNU
coreutils), which would produce an invalid `Authorization` header containing an
embedded newline. Recommend using `base64 -w 0` (GNU) or piping through `tr -d
'\\n'` to make the examples reliable across environments. This applies to all
`curl` examples in this file.
##########
design-docs/gravitino-local-authentication.md:
##########
@@ -752,13 +531,13 @@ curl -X PUT -H "Accept:
application/vnd.gravitino.v1+json" \
| Area | Checklist |
|---|---|
-| Module wiring | The design, module name, and server wiring all consistently
use `plugins:idp-basic`, while the authenticator mode remains `basic`. |
-| Configuration | All examples use `gravitino.authenticators=basic`, and no
obsolete configuration keys remain in the document. |
+| Module wiring | The design, module name, and server wiring all consistently
use `plugins:idp-basic`. |
Review Comment:
Section 3.1 and section 8 no longer mention the `basic` authenticator name,
but the module is still called `idp-basic`. Consider adding a brief note
explaining where the `basic` suffix comes from (e.g., HTTP Basic auth) now that
`gravitino.authenticators=basic` has been removed, so future readers understand
the module naming.
--
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]
