This is an automated email from the ASF dual-hosted git repository.
sarvekshayr pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 41d0895f0 HDDS-14322. [Website v2] [Docs] [User Guide] Securing S3.
(#227)
41d0895f0 is described below
commit 41d0895f045cb8d7787bee9fd8ff2f32924dcc3d
Author: Wei-Chiu Chuang <[email protected]>
AuthorDate: Thu Jan 8 23:11:12 2026 -0800
HDDS-14322. [Website v2] [Docs] [User Guide] Securing S3. (#227)
---
.../03-namespace/01-volumes/01-overview.md | 2 +-
.../03-namespace/02-buckets/01-overview.md | 2 +-
.../{03-s3.md => 03-s3/01-s3-api.md} | 6 +-
.../01-client-interfaces/03-s3/02-securing-s3.md | 114 +++++++++++++++++++++
.../01-client-interfaces/03-s3/README.mdx | 7 ++
docs/04-user-guide/03-integrations/01-hive.md | 2 +-
6 files changed, 127 insertions(+), 6 deletions(-)
diff --git a/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
b/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
index 153c05d53..412eb325d 100644
--- a/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
+++ b/docs/03-core-concepts/03-namespace/01-volumes/01-overview.md
@@ -50,7 +50,7 @@ ACLs can be set and managed using the Ozone CLI. Refer to the
[Security ACLs doc
### S3 Gateway Integration (`/s3v` Volume)
For compatibility with the S3 API, Ozone uses a special volume, typically
`/s3v`. By default, all buckets accessed via the S3 interface are stored under
this volume. It's also possible to expose buckets from other Ozone volumes via
the S3 interface using "bucket linking."
-For more details, refer to the [S3 Protocol
documentation](../../../04-user-guide/01-client-interfaces/03-s3.md) and [S3
Multi-Tenancy
documentation](../../../05-administrator-guide/03-operations/07-s3-multi-tenancy.md).
+For more details, refer to the [S3 Protocol
documentation](../../../04-user-guide/01-client-interfaces/03-s3/01-s3-api.md)
and [S3 Multi-Tenancy
documentation](../../../05-administrator-guide/03-operations/07-s3-multi-tenancy.md).
### Datanode Physical Volumes vs. Ozone Manager Logical Volumes
diff --git a/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
b/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
index 422136d91..386298a42 100644
--- a/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
+++ b/docs/03-core-concepts/03-namespace/02-buckets/01-overview.md
@@ -54,7 +54,7 @@ For more details, refer to the [GDPR
documentation](https://ozone.apache.org/doc
### Bucket Linking
Bucket linking allows exposing a bucket from one volume (or even another
bucket) as if it were in a different location, particularly useful for S3
compatibility or cross-tenant access. This creates a symbolic link-like
behavior.
-For more information, see the [S3 Protocol
documentation](../../../04-user-guide/01-client-interfaces/03-s3.md) and [S3
Multi-Tenancy
documentation](../../../05-administrator-guide/03-operations/07-s3-multi-tenancy.md).
+For more information, see the [S3 Protocol
documentation](../../../04-user-guide/01-client-interfaces/03-s3/01-s3-api.md)
and [S3 Multi-Tenancy
documentation](../../../05-administrator-guide/03-operations/07-s3-multi-tenancy.md).
### Access Control Lists (ACLs)
diff --git a/docs/04-user-guide/01-client-interfaces/03-s3.md
b/docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md
similarity index 98%
rename from docs/04-user-guide/01-client-interfaces/03-s3.md
rename to docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md
index baa2dec55..8966fb4c5 100644
--- a/docs/04-user-guide/01-client-interfaces/03-s3.md
+++ b/docs/04-user-guide/01-client-interfaces/03-s3/01-s3-api.md
@@ -1,8 +1,8 @@
---
-sidebar_label: S3 API
+sidebar_label: Overview
---
-# S3 API
+# Overview
Ozone provides S3 compatible REST interface to use the object store data with
any S3 compatible tools.
S3 buckets are stored under the `/s3v` volume.
@@ -91,7 +91,7 @@ The Ozone S3 Gateway implements a substantial subset of the
Amazon S3 REST API.
- **Conditional Requests:** Support for conditional requests (e.g.,
`If-Match`, `If-None-Match`) is planned and tracked in
[HDDS-13117](https://issues.apache.org/jira/browse/HDDS-13117).
- **Lifecycle configuration, cross region replication, S3 event
notifications** are being implemented and in the roadmap.
- While Ozone S3 Gateway provides extensive support for common S3 operations,
users should be aware of the above non-compliant behaviors and limitations when
integrating with applications expecting full AWS S3 functionality.
-- While Ozone S3 Gateway does not support S3 Server-Side Encryption, it does
support encrypted buckets using Apache Ranger KMS. For more information, see
the [Transparent Data
Encryption](../../05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md)
documentation.
+- While Ozone S3 Gateway does not support S3 Server-Side Encryption, it does
support encrypted buckets using Apache Ranger KMS. For more information, see
the [Transparent Data
Encryption](../../../05-administrator-guide/02-configuration/03-security/05-encryption/02-transparent-data-encryption.md)
documentation.
:::
## Security
diff --git a/docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md
b/docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md
new file mode 100644
index 000000000..af321f525
--- /dev/null
+++ b/docs/04-user-guide/01-client-interfaces/03-s3/02-securing-s3.md
@@ -0,0 +1,114 @@
+---
+sidebar_label: Securing S3
+---
+
+# Securing S3
+
+To access an S3 bucket, users need AWS access key ID and AWS secret. Both of
+these are generated by going to AWS website. When you use Ozone's S3
+protocol, you need the same AWS access key and secret.
+
+Under Ozone, the clients can download the access key directly from Ozone.
+The user needs to `kinit` first and once they have authenticated via Kerberos
+they can download the S3 access key ID and AWS secret. Just like AWS S3,
+both of these are secrets that need to be protected by the client since it
+gives full access to the S3 buckets.
+
+## Obtain Secrets
+
+S3 clients can get the secret access ID and user secret from OzoneManager.
+
+### Using the command line
+
+For a regular user to get their own secret:
+
+```bash
+ozone s3 getsecret
+```
+
+An Ozone administrator can get a secret for a specific user by using the `-u`
flag:
+
+```bash
+ozone s3 getsecret -u <username>
+```
+
+### Using the REST API
+
+A user can get their own secret by making a `PUT` request to the `/secret`
endpoint:
+
+```bash
+curl -X PUT --negotiate -u : https://localhost:9879/secret
+```
+
+An Ozone administrator can get a secret for a specific user by appending the
username to the path:
+
+```bash
+curl -X PUT --negotiate -u : https://localhost:9879/secret/<username>
+```
+
+This command will talk to Ozone, validate the user via Kerberos and generate
+the AWS credentials. The values will be printed out on the screen. You can
+set these values up in your *.aws* file for automatic access while working
+against Ozone S3 buckets.
+
+:::caution
+Please note: These S3 credentials are like your Kerberos passwords
+that give complete access to your buckets.
+:::
+
+- Now you can proceed to setup these secrets in aws configs:
+
+```bash
+aws configure set default.s3.signature_version s3v4
+aws configure set aws_access_key_id ${accessId}
+aws configure set aws_secret_access_key ${secret}
+aws configure set region us-west-1
+```
+
+Please refer to AWS S3 documentation on how to use S3 via command line or via
+S3 API.
+
+## Revoking Secrets via REST API
+
+To invalidate/revoke the secret, use `ozone s3 revokesecret` command.
+Alternatively, you can use the REST API endpoint to revoke the secret.
+Ozone now provides a REST API endpoint that allows administrators to revoke S3
access secrets. This operation invalidates a secret, ensuring it can no longer
be used for authentication.
+
+### Endpoint Details
+
+- **URL:** `http://localhost:9879/secret`
+- **HTTP Method:** `DELETE`
+
+### Authentication
+
+The API leverages SPNEGO (Kerberos) authentication. The following curl options
are used:
+
+- `--negotiate` enables SPNEGO.
+- `-u :` uses the current Kerberos ticket (an empty username is provided).
+
+### Example 1: Revoke Secret for the Current User
+
+This command revokes the secret for the currently authenticated user:
+
+```bash
+curl -X DELETE --negotiate -u : -v http://localhost:9879/secret
+```
+
+### Example 2: Revoke Secret by Username
+
+This command revokes the secret for a specific user by appending the username
as a query parameter. Replace `testuser` with the desired username:
+
+```bash
+curl -X DELETE --negotiate -u : -v
"http://localhost:9879/secret?username=testuser";
+```
+
+### Response
+
+- **Success:** Returns HTTP `200 OK` along with a confirmation message in JSON
format.
+- **Failure:** Returns an appropriate HTTP error status and message if there
are issues (e.g., authentication failures).
+
+### Testing and Verification
+
+For a working example of these operations, refer to the [Secret Revoke Robot
Test](https://raw.githubusercontent.com/apache/ozone/refs/heads/master/hadoop-ozone/dist/src/main/smoketest/s3/secretrevoke.robot).
This test demonstrates both the default secret revocation and the revocation
by username.
+
+> **Note:** Ensure your Kerberos authentication is correctly configured, as
secret revocation is a privileged operation.
diff --git a/docs/04-user-guide/01-client-interfaces/03-s3/README.mdx
b/docs/04-user-guide/01-client-interfaces/03-s3/README.mdx
new file mode 100644
index 000000000..a8ce6af33
--- /dev/null
+++ b/docs/04-user-guide/01-client-interfaces/03-s3/README.mdx
@@ -0,0 +1,7 @@
+# S3 API
+
+import DocCardList from '@theme/DocCardList';
+
+This section documents Ozone's S3 compatible API support.
+
+<DocCardList/>
diff --git a/docs/04-user-guide/03-integrations/01-hive.md
b/docs/04-user-guide/03-integrations/01-hive.md
index 2e2f0d10e..13298360f 100644
--- a/docs/04-user-guide/03-integrations/01-hive.md
+++ b/docs/04-user-guide/03-integrations/01-hive.md
@@ -160,5 +160,5 @@ In addition to ofs, Hive can access Ozone using the S3
Gateway via the S3A file
For more information, consult:
-- The [S3 Protocol](../01-client-interfaces/03-s3.md)
+- The [S3 Protocol](../01-client-interfaces/03-s3/01-s3-api.md)
- The [Hadoop
S3A](https://hadoop.apache.org/docs/current/hadoop-aws/tools/hadoop-aws/index.html)
documentation.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
