docs: Add policy variables for resource and conditions (#10278)

Bonus fix adds LDAP policy variable and clarifies the usage of policy variables for temporary credentials. fixes #10197
2025-11-07 21:02:58 -05:00 · 2020-08-17 17:39:55 -07:00
parent e57c742674
commit ede86845e5
14 changed files with 176 additions and 14 deletions
--- a/docs/multi-user/README.md
+++ b/docs/multi-user/README.md
@@ -109,10 +109,135 @@ mc admin group list myminio

 ### 8. Configure `mc`
 ```
-mc config host add myminio-newuser http://localhost:9000 newuser newuser123 --api s3v4
+mc alias set myminio-newuser http://localhost:9000 newuser newuser123 --api s3v4
 mc cat myminio-newuser/my-bucketname/my-objectname
 ```

+### Policy Variables
+You can use policy variables in the *Resource* element and in string comparisons in the *Condition* element.
+
+You can use a policy variable in the Resource element, but only in the resource portion of the ARN. This portion of the ARN appears after the 5th colon (:). You can't use a variable to replace parts of the ARN before the 5th colon, such as the service or account. The following policy might be attached to a group. It gives each of the users in the group full programmatic access to a user-specific object (their own "home directory") in MinIO.
+
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": ["s3:ListBucket"],
+      "Effect": "Allow",
+      "Resource": ["arn:aws:s3:::mybucket"],
+      "Condition": {"StringLike": {"s3:prefix": ["${aws:username}/*"]}}
+    },
+    {
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject"
+      ],
+      "Effect": "Allow",
+      "Resource": ["arn:aws:s3:::mybucket/${aws:username}/*"]
+    }
+  ]
+}
+```
+
+If the user is authenticating using an STS credential which was authorized from OpenID connect we allow all `jwt:*` variables specified in the JWT specification, custom `jwt:*` or extensions are not supported.
+
+List of policy variables for OpenID based STS.
+```
+"jwt:sub"
+"jwt:iss"
+"jwt:aud"
+"jwt:jti"
+"jwt:upn"
+"jwt:name"
+"jwt:groups"
+"jwt:given_name"
+"jwt:family_name"
+"jwt:middle_name"
+"jwt:nickname"
+"jwt:preferred_username"
+"jwt:profile"
+"jwt:picture"
+"jwt:website"
+"jwt:email"
+"jwt:gender"
+"jwt:birthdate"
+"jwt:phone_number"
+"jwt:address"
+"jwt:scope"
+"jwt:client_id"
+```
+
+Following example shows OpenID users with full programmatic access to a OpenID user-specific directory (their own "home directory") in MinIO.
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": ["s3:ListBucket"],
+      "Effect": "Allow",
+      "Resource": ["arn:aws:s3:::mybucket"],
+      "Condition": {"StringLike": {"s3:prefix": ["${jwt:preferred_username}/*"]}}
+    },
+    {
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject"
+      ],
+      "Effect": "Allow",
+      "Resource": ["arn:aws:s3:::mybucket/${jwt:preferred_username}/*"]
+    }
+  ]
+}
+```
+
+If the user is authenticating using an STS credential which was authorized from AD/LDAP we allow `ldap:*` variables, currently only supports `ldap:user`. Following example shows LDAP users full programmatic access to a LDAP user-specific directory (their own "home directory") in MinIO.
+```
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Action": ["s3:ListBucket"],
+      "Effect": "Allow",
+      "Resource": ["arn:aws:s3:::mybucket"],
+      "Condition": {"StringLike": {"s3:prefix": ["${ldap:user}/*"]}}
+    },
+    {
+      "Action": [
+        "s3:GetObject",
+        "s3:PutObject"
+      ],
+      "Effect": "Allow",
+      "Resource": ["arn:aws:s3:::mybucket/${ldap:user}/*"]
+    }
+  ]
+}
+```
+
+#### Common information available in all requests
+
+- *aws:CurrentTime* - This can be used for conditions that check the date and time.
+- *aws:EpochTime* - This is the date in epoch or Unix time, for use with date/time conditions.
+- *aws:PrincipalType* - This value indicates whether the principal is an account (Root credential), user (MinIO user), or assumed role (STS)
+- *aws:SecureTransport* - This is a Boolean value that represents whether the request was sent over TLS.
+- *aws:SourceIp* - This is the requester's IP address, for use with IP address conditions. If running behind Nginx like proxies, MinIO preserve's the source IP.
+
+```
+{
+  "Version": "2012-10-17",
+  "Statement": {
+    "Effect": "Allow",
+    "Action": "s3:ListBucket*",
+    "Resource": "arn:aws:s3:::mybucket",
+    "Condition": {"IpAddress": {"aws:SourceIp": "203.0.113.0/24"}}
+  }
+}
+```
+
+- *aws:UserAgent* - This value is a string that contains information about the requester's client application. This string is generated by the client and can be unreliable. You can only use this context key from `mc` or other MinIO SDKs which standardize the User-Agent string.
+- *aws:username* - This is a string containing the friendly name of the current user, this value would point to STS temporary credential in `AssumeRole`ed requests, instead use `jwt:preferred_username` in case of OpenID connect and `ldap:user` in case of AD/LDAP connect. *aws:userid* is an alias to *aws:username* in MinIO.
+
+
 ## Explore Further
 - [MinIO Client Complete Guide](https://docs.min.io/docs/minio-client-complete-guide)
 - [MinIO STS Quickstart Guide](https://docs.min.io/docs/minio-sts-quickstart-guide)
--- a/docs/multi-user/admin/README.md
+++ b/docs/multi-user/admin/README.md
@@ -62,7 +62,7 @@ This admin user will then be allowed to perform create/delete user operations vi

 ### 3. Configure `mc` and create another user user1 with attached policy user1policy
 ```
-mc config host add myminio-admin1 http://localhost:9000 admin1 admin123 --api s3v4
+mc alias set myminio-admin1 http://localhost:9000 admin1 admin123 --api s3v4

 mc admin user add myminio-admin1 user1 user123
 mc admin policy add myminio-admin1 user1policy ~/user1policy.json