[jira] [Created] (HDDS-14481) [Docs] System Internals -> Security -> Tokens

["Wei-Chiu Chuang (Jira)" <ji...@apache.org>]

Wei-Chiu Chuang created HDDS-14481:
--------------------------------------

             Summary: [Docs] System Internals -> Security -> Tokens
                 Key: HDDS-14481
                 URL: https://issues.apache.org/jira/browse/HDDS-14481
             Project: Apache Ozone
          Issue Type: Task
          Components: documentation
            Reporter: Wei-Chiu Chuang


System Internals -> Security -> Tokens
to add block token and container token description and comparision.

    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.
       * It does not specify individual blocks or fine-grained access modes like a Block Token does.

  Summary of Key Differences


  ┌──────────────────┬─────────────────────────────────────────────────┬───────────────────────────────────────────────────────────────────┐
  │ Feature          │ Block Token                                     │ Container Token                                                   │
  ├──────────────────┼─────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────┤
  │ Scope of Access  │ A single Block                                  │ An entire Container                                               │
  │ Generated By     │ Ozone Manager (OM)                              │ Storage Container Manager (SCM)                                   │
  │ Primary Use Case │ Authorizing client data operations (read/write) │ Authorizing administrative or management operations on containers │
  │ Typical User     │ End-client applications writing/reading keys    │ Ozone-internal processes (like SCM) or admin tools (ozone debug)  │
  └──────────────────┴─────────────────────────────────────────────────┴───────────────────────────────────────────────────────────────────┘


  In short, think of it like this:
   * A Block Token is your ticket to a specific seat in a movie theater, given to you by the box office (Ozone Manager).
   * A Container Token is a master key for the entire theater room, given to you by the building manager (SCM) for maintenance or inspection purposes.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)

---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@ozone.apache.org
For additional commands, e-mail: issues-help@ozone.apache.org