From ec5ff12a29cf1fa944b3fd80977f82ad857426f9 Mon Sep 17 00:00:00 2001
From: ravindk89 <ravind@min.io>
Date: Mon, 22 Nov 2021 17:00:01 -0500
Subject: [PATCH] Minor Fix: Clarify readonly and writeonly built-in policies

---
 .../policy-based-access-control.rst           | 25 +++++++++++++++----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/source/security/minio-identity-management/policy-based-access-control.rst b/source/security/minio-identity-management/policy-based-access-control.rst
index c544a376..c17bf4cb 100644
--- a/source/security/minio-identity-management/policy-based-access-control.rst
+++ b/source/security/minio-identity-management/policy-based-access-control.rst
@@ -40,7 +40,7 @@ MinIO provides the following built-in policies for assigning to
 .. userpolicy:: consoleAdmin
 
    Grants complete access to all S3 and administrative API operations against
-   all resources on the MinIO server. Equivalent to the following set of
+   all resources on the MinIO deployment. Equivalent to the following set of
    actions:
 
    - :policy-action:`s3:*`
@@ -48,12 +48,25 @@ MinIO provides the following built-in policies for assigning to
 
 .. userpolicy:: readonly
 
-   Grants read-only permissions for all buckets and objects on the MinIO server.
+   Grants read-only permissions on any object on the MinIO deployment. The GET
+   action *must* apply to a specific object without requiring any listing.
    Equivalent to the following set of actions:
 
    - :policy-action:`s3:GetBucketLocation`
    - :policy-action:`s3:GetObject`
 
+   For example, this policy specifically supports GET operations on objects at a
+   specific path (e.g. ``GET play/mybucket/object.file``), such as:
+
+   - :mc-cmd:`mc cp`
+   - :mc-cmd:`mc stat`
+   - :mc-cmd:`mc head`
+   - :mc-cmd:`mc cat`
+
+   The exclusion of listing permissions is intentional, as typical use cases
+   do not intend for a "read-only" role to have complete discoverability
+   (listing all buckets and objects) on the object storage resource.
+
 .. userpolicy:: readwrite
 
    Grants read and write permissions for all buckets and objects on the
@@ -61,7 +74,7 @@ MinIO provides the following built-in policies for assigning to
 
 .. userpolicy:: diagnostics
 
-   Grants permission to perform diagnostic actions on the MinIO server. 
+   Grants permission to perform diagnostic actions on the MinIO deployment. 
    Specifically includes the following actions:
 
    - :policy-action:`admin:ServerTrace`
@@ -75,8 +88,10 @@ MinIO provides the following built-in policies for assigning to
 
 .. userpolicy:: writeonly
 
-   Grants write-only permissions for all buckets and objects on the MinIO 
-   server. Equivalent to the :policy-action:`s3:PutObject` action.
+   Grants write-only permissions to any namespace (bucket and path to object)
+   the MinIO deployment. The PUT action *must* apply to a specific object
+   location without requiring any listing. 
+   Equivalent to the :policy-action:`s3:PutObject` action.
 
 Use :mc-cmd:`mc admin policy set` to associate a policy to a 
 user or group on a MinIO deployment.