jojochuang commented on code in PR #295: URL: https://github.com/apache/ozone-site/pull/295#discussion_r2730660419
########## docs/07-system-internals/05-security/03-tokens.md: ########## @@ -4,6 +4,56 @@ sidebar_label: Tokens # Token Based Authentication Within Ozone -**TODO:** File a subtask under [HDDS-9862](https://issues.apache.org/jira/browse/HDDS-9862) and complete this page or section. +Ozone uses token-based authentication to secure access to data stored in containers and blocks. +Tokens are short-lived credentials that authorize specific operations without requiring clients to repeatedly +authenticate with the central authority. -Document how Ozone generates and uses container and block tokens, and why they are used. +Ozone implements two types of tokens: **Block Tokens** for fine-grained data access and **Container Tokens** for container-level administrative operations. + +## Block Token + +- **Granularity:** `Block-level`. A Block Token grants access to a single, specific block within a container. +- **Issuer:** `Ozone Manager (OM)`. The OM generates Block Tokens when a client requests to write or read a block. This is because the OM is responsible for managing the block namespace within the object store. +- **Usage Context:** A Block Token is used when a client needs to perform a data-plane operation (read/write) on a specific block. For example: + + 1. A client wants to write data for key1. + 2. It contacts the OM, which allocates a new block (e.g., block123) for key1. + 3. The OM returns the location of block123 (which includes the Datanodes) and a unique Block Token for `block123`. + 4. The client then uses this specific Block Token to write data for block123 to the Datanodes. + +- **Information Carried (`BlockTokenIdentifier`):** The token identifier contains: Review Comment: ```suggestion - **Information Carried (`OzoneBlockTokenIdentifier`):** The token identifier contains: ``` ########## docs/07-system-internals/05-security/03-tokens.md: ########## @@ -4,6 +4,56 @@ sidebar_label: Tokens # Token Based Authentication Within Ozone -**TODO:** File a subtask under [HDDS-9862](https://issues.apache.org/jira/browse/HDDS-9862) and complete this page or section. +Ozone uses token-based authentication to secure access to data stored in containers and blocks. +Tokens are short-lived credentials that authorize specific operations without requiring clients to repeatedly +authenticate with the central authority. -Document how Ozone generates and uses container and block tokens, and why they are used. +Ozone implements two types of tokens: **Block Tokens** for fine-grained data access and **Container Tokens** for container-level administrative operations. + +## Block Token + +- **Granularity:** `Block-level`. A Block Token grants access to a single, specific block within a container. +- **Issuer:** `Ozone Manager (OM)`. The OM generates Block Tokens when a client requests to write or read a block. This is because the OM is responsible for managing the block namespace within the object store. +- **Usage Context:** A Block Token is used when a client needs to perform a data-plane operation (read/write) on a specific block. For example: + + 1. A client wants to write data for key1. + 2. It contacts the OM, which allocates a new block (e.g., block123) for key1. + 3. The OM returns the location of block123 (which includes the Datanodes) and a unique Block Token for `block123`. + 4. The client then uses this specific Block Token to write data for block123 to the Datanodes. + +- **Information Carried (`BlockTokenIdentifier`):** The token identifier contains: + + - The user/owner ID. + - The BlockID it authorizes. + - The access modes it permits (e.g., READ, WRITE, DELETE). Review Comment: ```suggestion - The access modes it permits (e.g., READ, WRITE, DELETE). - expiration time. ``` ########## docs/07-system-internals/05-security/03-tokens.md: ########## @@ -4,6 +4,56 @@ sidebar_label: Tokens # Token Based Authentication Within Ozone -**TODO:** File a subtask under [HDDS-9862](https://issues.apache.org/jira/browse/HDDS-9862) and complete this page or section. +Ozone uses token-based authentication to secure access to data stored in containers and blocks. +Tokens are short-lived credentials that authorize specific operations without requiring clients to repeatedly +authenticate with the central authority. -Document how Ozone generates and uses container and block tokens, and why they are used. +Ozone implements two types of tokens: **Block Tokens** for fine-grained data access and **Container Tokens** for container-level administrative operations. + +## Block Token + +- **Granularity:** `Block-level`. A Block Token grants access to a single, specific block within a container. +- **Issuer:** `Ozone Manager (OM)`. The OM generates Block Tokens when a client requests to write or read a block. This is because the OM is responsible for managing the block namespace within the object store. +- **Usage Context:** A Block Token is used when a client needs to perform a data-plane operation (read/write) on a specific block. For example: + + 1. A client wants to write data for key1. + 2. It contacts the OM, which allocates a new block (e.g., block123) for key1. + 3. The OM returns the location of block123 (which includes the Datanodes) and a unique Block Token for `block123`. + 4. The client then uses this specific Block Token to write data for block123 to the Datanodes. + +- **Information Carried (`BlockTokenIdentifier`):** The token identifier contains: + + - The user/owner ID. + - The BlockID it authorizes. + - The access modes it permits (e.g., READ, WRITE, DELETE). + +## Container Token + +- **Granularity:** `Container-level`. A Container Token grants access to an entire container, which can contain many blocks. +- **Issuer:** `Storage Container Manager (SCM)`. The SCM generates Container Tokens. This is logical because the SCM is responsible for managing containers and their placement across Datanodes, but it is unaware of the individual blocks inside them. +- **Usage Context:** A Container Token is used for operations that concern the container as a whole, often for administrative or maintenance tasks that bypass the Ozone Manager. For example: + + 1. An administrator uses the `ozone debug replicas verify` command to check the integrity of replicas for a container. + 2. The admin tool contacts the SCM to get a Container Token for the specified ContainerID. + 3. The tool then uses this token to communicate directly with Datanodes to perform the verification. + 4. Another example is when the SCM itself issues commands to Datanodes (e.g., to close a container). It generates a Container Token to authorize its own command. + +- **Information Carried (`ContainerTokenIdentifier`):** The token identifier contains: + + - The user/owner ID. + - The ContainerID it authorizes. Review Comment: ```suggestion - The ContainerID it authorizes. - expiration time. ``` -- 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] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
