docs/source/administration/identity-access-management/policy-based-access-control.rst

Access Management

minio

Table of Contents

Overview

MinIO uses Policy-Based Access Control (PBAC) to define the authorized actions and resources to which an authenticated user has access. Each policy describes one or more actions <minio-policy-actions> and conditions <minio-policy-conditions> that outline the permissions of a user <minio-users> or group <minio-groups> of users.

MinIO PBAC is built for compatibility with AWS IAM policy syntax, structure, and behavior. The MinIO documentation makes a best-effort to cover IAM-specific behavior and functionality. Consider deferring to the IAM documentation <> for more complete documentation on AWS IAM-specific topics.

The mc admin policy command supports creation and management of policies on the MinIO deployment. See the command reference for examples of usage.

Tag-Based Policy Conditions

RELEASE.2022-10-02T19-29-29Z

Policies can use conditions to limit a user's access only to objects with a specific tag <minio-object-tagging>.

MinIO supports tag-based conditionals <tagging-and-policies.html> for policies for selected actions <minio-selected-conditional-actions>. Use the s3:ExistingObjectTag/<key> in the Condition statement of the policy.

Built-In Policies

MinIO provides the following built-in policies for assigning to users <minio-users> or groups <minio-groups>:

consoleAdmin

Grants complete access to all S3 and administrative API operations against all resources on the MinIO deployment. Equivalent to the following set of actions:

• s3:*
• admin:*

readonly

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:

• s3:GetBucketLocation
• 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 cp
• mc stat
• mc head
• 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.

readwrite

Grants read and write permissions for all buckets and objects on the MinIO server. Equivalent to s3:*.

diagnostics

Grants permission to perform diagnostic actions on the MinIO deployment. Specifically includes the following actions:

• admin:ServerTrace
• admin:Profiling
• admin:ConsoleLog
• admin:ServerInfo
• admin:TopLocksInfo
• admin:OBDInfo
• admin:BandwidthMonitor
• admin:Prometheus

writeonly

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 s3:PutObject action.

Use mc admin policy attach to associate a policy to a user or group on a MinIO deployment.

For example, consider the following table of users. Each user is assigned a built-in policy <minio-policy-built-in> or a supported action <minio-policy-actions>. The table describes a subset of operations a client could perform if authenticated as that user:

User	Policy	Operations
Operations	readwrite on finance bucket readonly on audit bucket	PUT and GET on finance bucket. GET on audit bucket
Auditing	readonly on audit bucket	GET on audit bucket
Admin	admin:*	All mc admin commands.

Each user can access only those resources and operations which are explicitly granted by the built-in role. MinIO denies access to any other resource or action by default.

Deny overrides Allow

MinIO follows the IAM policy evaluation rules where a Deny rule overrides Allow rule on the same action/resource. For example, if a user has an explicitly assigned policy with an Allow rule for an action/resource while one of its groups has an assigned policy with a Deny rule for that action/resource, MinIO would apply only the Deny rule.

For more information on IAM policy evaluation logic, see the IAM documentation on Determining Whether a Request is Allowed or Denied Within an Account <reference_policies_evaluation-logic.html#policy-eval-denyallow>.

Policy Document Structure

MinIO policy documents use the same schema as AWS IAM Policy <IAM/latest/UserGuide/access.html> documents.

The following sample document provides a template for creating custom policies for use with a MinIO deployment. For more complete documentation on IAM policy elements, see the IAM JSON Policy Elements Reference <IAM/latest/UserGuide/reference_policies_elements.html>.

The maximum size for any single policy document is 20KiB. There is no limit to the number of policy documents that can be attached to a user or group.

{
   "Version" : "2012-10-17",
   "Statement" : [
      {
         "Effect" : "Allow",
         "Action" : [ "s3:<ActionName>", ... ],
         "Resource" : "arn:aws:s3:::*",
         "Condition" : { ... }
      },
      {
         "Effect" : "Deny",
         "Action" : [ "s3:<ActionName>", ... ],
         "Resource" : "arn:aws:s3:::*",
         "Condition" : { ... }
      }
   ]
}

• For the Statement.Action array, specify one or more supported S3 API operations <minio-policy-actions>.

• For the Statement.Resource key, specify the bucket or bucket prefix to which to restrict the policy. You can use * and ? wildcard characters as per the S3 Resource Spec <s3-arn-format.html>.

  The * wildcard may result in unintended application of a policy to multiple buckets or prefixes based on the pattern match <minio-wildcard-matching>. For example, arn:aws:s3:::data* would match the buckets data, data_private, and data_internal. Specifying only * as the resource key applies the policy to all buckets and prefixes on the deployment.

• For the Statement.Condition key, you can specify one or more supported Conditions <minio-policy-conditions>.

Supported S3 Policy Actions

MinIO policy documents support a subset of IAM S3 Action keys <list_amazons3.html#amazons3-actions-as-permissions>. This section also includes any condition keys <minio-policy-conditions> supported by a specific action beyond the common set of supported keys.

The following actions control access to common S3 operations. The remaining subsections document actions for more advanced S3 operations:

s3:*

Selector for all MinIO S3 operations. Applying this action to a given resource allows the user to perform any S3 operation against that resource.

s3:CreateBucket

Controls access to the CreateBucket <API_CreateBucket.html> S3 API operation.

s3:DeleteBucket

Controls access to the DeleteBucket <API_DeleteBucket.html> S3 API operation.

s3:ForceDeleteBucket

Controls access to the DeleteBucket <API_DeleteBucket.html> S3 API operation for operations with the x-minio-force-delete flag. Required for removing non-empty buckets.

s3:GetBucketLocation

Controls access to the GetBucketLocation <API_GetBucketLocation.html> S3 API operation.

s3:ListAllMyBuckets

Controls access to the ListBuckets <API_ListBuckets.html> S3 API operation.

s3:DeleteObject

Controls access to the DeleteObject <API_DeleteObject.html> S3 API operation.

s3:GetObject

Controls access to the GetObject <API_GetObject.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:x-amz-server-side-encryption   
s3:x-amz-server-side-encryption-customer-algorithm   
s3:ExistingObjectTag/<key>   
s3:versionid   

s3:ListBucket

Controls access to the ListObjectsV2 <API_ListObjectsV2.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:prefix   
s3:delimiter   
s3:max-keys   

s3:PutObject

Controls access to the PutObject <API_PutObject.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:x-amz-copy-source    
s3:x-amz-server-side-encryption   
s3:x-amz-server-side-encryption-customer-algorithm   
s3:x-amz-metadata-directive   
s3:x-amz-storage-class   
s3:versionid   
s3:object-lock-retain-until-date   
s3:object-lock-mode   
s3:object-lock-legal-hold   
s3:RequestObjectTagKeys   
s3:RequestObjectTag/<key>   

s3:PutObjectTagging

Controls access to the PutObjectTagging <API_PutObjectTagging.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   
s3:RequestObjectTagKeys   
s3:RequestObjectTag/<key>   

s3:GetObjectTagging

Controls access to the GetObjectTagging <API_GetObjectTagging.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

s3:DeleteObjectTagging

Controls access to the DeleteObjectTagging <API_DeleteObjectTagging.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>

Bucket Configuration

s3:GetBucketPolicy

Controls access to the GetBucketPolicy <API_GetBucketPolicy.html> S3 API operation.

s3:PutBucketPolicy

Controls access to the PutBucketPolicy <API_PutBucketPolicy.html> S3 API operation.

s3:DeleteBucketPolicy

Controls access to the DeleteBucketPolicy <API_DeleteBucketPolicy.html> S3 API operation.

s3:GetBucketTagging

Controls access to the GetBucketTagging <API_GetBucketTagging.html> S3 API operation.

s3:PutBucketTagging

Controls access to the PutBucketTagging <API_PutBucketTagging.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:RequestObjectTagKeys   
s3:RequestObjectTag/<key>   

Multipart Upload

s3:AbortMultipartUpload

Controls access to the AbortMultipartUpload <API_AbortMultipartUpload.html> S3 API operation.

s3:ListMultipartUploadParts

Controls access to the ListParts <API_ListParts.html> S3 API operation.

s3:ListBucketMultipartUploads

Controls access to the ListMultipartUploads <API_ListMultipartUploads.html> S3 API operation.

Versioning and Retention

s3:PutBucketVersioning

Controls access to the PutBucketVersioning <API_PutBucketVersioning.html> S3 API operation.

s3:GetBucketVersioning

Controls access to the GetBucketVersioning <API_GetBucketVersioning.html> S3 API operation.

s3:DeleteObjectVersion

Controls access to the DeleteObjectVersion <API_DeleteObjectVersion.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

s3:ListBucketVersions

Controls access to the ListBucketVersions <API_ListBucketVersions.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:prefix   
s3:delimiter   
s3:max-keys   

s3:PutObjectVersionTagging

Controls access to the PutObjectVersionTagging <API_PutObjectVersionTagging.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   
s3:RequestObjectTagKeys   
s3:RequestObjectTag/<key>   

s3:GetObjectVersionTagging

Controls access to the GetObjectVersionTagging <API_GetObjectVersionTagging.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>

s3:DeleteObjectVersionTagging

Controls access to the DeleteObjectVersionTagging <API_DeleteObjectVersionTagging.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

s3:GetObjectVersion

Controls access to the GetObjectVersion <API_GetObjectVersion.html> S3 API operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

s3:BypassGovernanceRetention

Controls access to the following S3 API operations on objects locked under GOVERNANCE <mc retention set MODE> retention mode:

• s3:PutObjectRetention
• s3:PutObject
• s3:DeleteObject

See the S3 documentation on s3:BypassGovernanceRetention <object-lock-managing.html#object-lock-managing-bypass> for more information.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:object-lock-remaining-retention-days   
s3:object-lock-retain-until-date   
s3:object-lock-mode   
s3:object-lock-legal-hold   
s3:RequestObjectTagKeys   
s3:RequestObjectTag/<key>   

s3:PutObjectRetention

Controls access to the PutObjectRetention <API_PutObjectRetention.html> S3 API operation.

Required for any PutObject operation that specifies retention metadata <minio-object-locking>.

Supports the following additional condition keys <minio-policy-conditions>:

s3:x-amz-server-side-encryption   
s3:x-amz-server-side-encryption-customer-algorithm   
s3:x-amz-object-lock-remaining-retention-days   
s3:x-amz-object-lock-retain-until-date   
s3:x-amz-object-lock-mode   
s3:versionid   

s3:GetObjectRetention

Controls access to the GetObjectRetention <API_GetObjectRetention.html> S3 API operation.

Required for including object locking metadata <minio-object-locking> as part of the response to a GetObject or HeadObject operation.

Supports the following additional condition keys <minio-policy-conditions>:

s3:x-amz-server-side-encryption   
s3:x-amz-server-side-encryption-customer-algorithm   
s3:versionid

s3:GetObjectLegalHold

Controls access to the GetObjectLegalHold <API_GetObjectLegalHold.html> S3 API operation.

Required for including object locking metadata <minio-object-locking> as part of the response to a GetObject or HeadObject operation.

s3:PutObjectLegalHold

Controls access to the PutObjectLegalHold <API_PutObjectLegalHold.html> S3 API operation.

Required for any PutObject operation that specifies legal hold metadata <minio-object-locking>.

Supports the following additional condition keys <minio-policy-conditions>:

s3:x-amz-server-side-encryption   
s3:x-amz-server-side-encryption-customer-algorithm   
s3:object-lock-legal-hold   
s3:versionid   

s3:GetBucketObjectLockConfiguration

Controls access to the GetObjectLockConfiguration <API_GetObjectLockConfiguration.html> S3 API operation.

s3:PutBucketObjectLockConfiguration

Controls access to the PutObjectLockConfiguration <API_PutObjectLockConfiguration.html> S3 API operation.

Bucket Notifications

s3:GetBucketNotification

Controls access to the GetBucketNotification <API_GetBucketNotification.html> S3 API operation.

s3:PutBucketNotification

Controls access to the PutBucketNotification <API_PutBucketNotification.html> S3 API operation.

s3:ListenNotification

MinIO Extension for controlling API operations related to MinIO Bucket Notifications.

This action is not intended for use with other S3-compatible services.

s3:ListenBucketNotification

MinIO Extension for controlling API operations related to MinIO Bucket Notifications.

This action is not intended for use with other S3-compatible services.

Object Lifecycle Management

s3:PutLifecycleConfiguration

Controls access to the PutLifecycleConfiguration <API_PutBucketLifecycleConfiguration.html> S3 API operation.

s3:GetLifecycleConfiguration

Controls access to the GetLifecycleConfiguration <API_GetBucketLifecycleConfiguration.html> S3 API operation.

Object Encryption

s3:PutEncryptionConfiguration

Controls access to the PutEncryptionConfiguration <API_PutBucketEncryption.html> S3 API operation.

s3:GetEncryptionConfiguration

Controls access to the GetEncryptionConfiguration <API_GetBucketEncryption.html> S3 API operation.

Bucket Replication

s3:GetReplicationConfiguration

Controls access to the GetBucketReplication <API_GetBucketReplication.html> S3 API operation.

s3:PutReplicationConfiguration

Controls access to the PutBucketReplication <PutBucketReplication.html> S3 API operation.

s3:ReplicateObject

MinIO Extension for controlling API operations related to Server-Side Bucket Replication <minio-bucket-replication-serverside>.

Required for MinIO server-side replication.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

s3:ReplicateDelete

MinIO Extension for controlling API operations related to Server-Side Bucket Replication <minio-bucket-replication-serverside>.

Required for synchronizing delete operations <minio-object-delete> as part of MinIO server-side replication.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

s3:ReplicateTags

MinIO Extension for controlling API operations related to Server-Side Bucket Replication <minio-bucket-replication-serverside>.

Required for MinIO server-side replication.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

s3:GetObjectVersionForReplication

MinIO Extension for controlling API operations related to Server-Side Bucket Replication <minio-bucket-replication-serverside>.

Required for MinIO server-side replication.

Supports the following additional condition keys <minio-policy-conditions>:

s3:versionid   
s3:ExistingObjectTag/<key>   

Supported S3 Policy Condition Keys

MinIO policy documents support IAM conditional statements <reference_policies_elements_condition.html>.

Each condition element consists of operators <reference_policies_elements_condition_operators.html> and condition keys. MinIO supports a subset of IAM condition keys. For complete information on any listed condition key, see the IAM Condition Element Documentation <reference_policies_elements_condition.html>

MinIO supports the following condition keys for all supported actions <minio-policy-actions>:

• aws:Referer
• aws:SourceIp
• aws:UserAgent
• aws:SecureTransport
• aws:CurrentTime
• aws:EpochTime
• aws:PrincipalType
• aws:userid
• aws:username
• x-amz-content-sha256
• s3:signatureAge

Warning

The aws:Referer, aws:SourceIp, and aws.UserAgent keys may be easily spoofed and therefore pose a potential security risk. MinIO recommends only using these condition keys to deny access as a secondary security measure.

Never use these three keys to grant access by themselves.

For additional keys supported by a specific S3 action, see the reference documentation for that action.

MinIO Extended Condition Keys

MinIO extends the S3 standard condition keys with the following extended key:

sts:DurationSeconds

MinIO SERVER RELEASE.2024-02-06T21-36-22Z

Specify a time in seconds to limit the duration of all Security Token Service credentials generated by minio-sts-assumerolewithwebidentity.

This value overrides the DurationSeconds field specified to the client.

For example:

{
   "Version": "2012-10-17",
   "Statement": [
      {
            "Effect": "Allow",
            "Action": [
               "sts:AssumeRoleWithWebIdentity"
            ],
            "Condition": {
               "NumericLessThanEquals": {
                  "sts:DurationSeconds": "300"
               }
            }
      }
   ]
}

mc admin Policy Action Keys

MinIO supports the following actions for use with defining policies for mc admin operations. These actions are only valid for MinIO deployments and are not intended for use with other S3-compatible services:

admin:*

Selector for all admin action keys.

admin:Heal

Allows heal command

admin:StorageInfo

Allows listing server info

admin:DataUsageInfo

Allows listing data usage info

admin:TopLocksInfo

Allows listing top locks

admin:Profiling

Allows profiling

admin:ServerTrace

Allows listing server trace

admin:ConsoleLog

Allows listing console logs on terminal

admin:KMSCreateKey

Allows creating a new KMS master key

admin:KMSKeyStatus

Allows getting KMS key status

admin:ServerInfo

Allows listing server info

admin:OBDInfo

Allows obtaining cluster on-board diagnostics

admin:ServerUpdate

Allows MinIO binary update

admin:ServiceRestart

Allows restart of MinIO service.

admin:ServiceStop

Allows stopping MinIO service.

admin:ConfigUpdate

Allows MinIO config management

admin:CreateUser

Allows creating MinIO user

admin:DeleteUser

Allows deleting MinIO user

admin:ListUsers

Allows list users permission

admin:EnableUser

Allows enable user permission

admin:DisableUser

Allows disable user permission

admin:GetUser

Allows GET permission on user info

admin:AddUserToGroup

Allows adding user to group permission

admin:RemoveUserFromGroup

Allows removing user to group permission

admin:GetGroup

Allows getting group info

admin:ListGroups

Allows list groups permission

admin:EnableGroup

Allows enable group permission

admin:DisableGroup

Allows disable group permission

admin:CreatePolicy

Allows create policy permission

admin:DeletePolicy

Allows delete policy permission

admin:GetPolicy

Allows get policy permission

admin:AttachUserOrGroupPolicy

Allows attaching a policy to a user/group

admin:ListUserPolicies

Allows listing user policies

admin:CreateServiceAccount

Allows creating MinIO Access Key

admin:UpdateServiceAccount

Allows updating MinIO Access Key

admin:RemoveServiceAccount

Allows deleting MinIO Access Key

admin:ListServiceAccounts

Allows listing MinIO Access Key

admin:SetBucketQuota

Allows setting bucket quota

admin:GetBucketQuota

Allows getting bucket quota

admin:SetBucketTarget

Allows setting bucket target

admin:GetBucketTarget

Allows getting bucket targets

admin:SetTier

Allows creating and modifying remote storage tiers using the mc ilm tier commands.

admin:ListTier

Allows listing configured remote storage tiers using the mc ilm tier commands.

admin:BandwidthMonitor

Allows retrieving metrics related to current bandwidth consumption.

admin:Prometheus

Allows access to MinIO metrics <minio-metrics-and-alerts>. Only required if MinIO requires authentication for scraping metrics.

admin:ListBatchJobs

Allows access to list the active batch jobs.

admin:DescribeBatchJobs

Allows access to the see the definition details of a running batch job.

admin:StartBatchJob

Allows user to begin a batch job run.

admin:CancelBatchJob

Allows user to stop a batch job currently in process.

admin:Rebalance

Allows access to start, query, or stop a rebalancing of objects across pools with varying free storage space.

mc admin Policy Condition Keys

MinIO supports the following conditions for use with defining policies for mc admin actions <minio-policy-mc-admin-actions>.

• aws:Referer
• aws:SourceIp
• aws:UserAgent
• aws:SecureTransport
• aws:CurrentTime
• aws:EpochTime

For complete information on any listed condition key, see the IAM Condition Element Documentation <reference_policies_elements_condition.html>.

Policy Variables

MinIO supports using policy variables for automatically substituting context from the authenticated user and/or the operation into the user's assigned policy or policies. Use the ${POLICYVARIABLE} format to specify the variable to the policy as part of the Condition or Resource definition. MinIO policy variables function similarly to AWS IAM policy elements: Variables and tags <reference_policies_variables.html>.

Each MinIO identity provider <minio-authentication-and-identity-management> supports its own set of policy variables:

• minio-policy-variables-internal
• minio-policy-variables-oidc
• minio-policy-variables-ad-ldap

MinIO Policy Variables

The following table contains a list of recommended policy variables for use in authorizing MinIO-managed users <minio-internal-idp>:

Variable	Description
aws:referrer <reference_policies_condition-keys.html#condition-keys-referer>	The referrer in the HTTP header for the authenticated API call.
aws:SourceIp <reference_policies_condition-keys.html#condition-keys-sourceip>	The source IP in the HTTP header for the authenticated API call.
aws:username <reference_policies_condition-keys.html#condition-keys-username>	The name of the user associated with the authenticated API call.

For example, the following policy uses variables to substitute the authenticated user's username as part of the Resource field such that the user can only access those prefixes which match their username:

{
"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}/*"]
      }
   ]
}

MinIO replaces the ${aws:username} variable in the Resource field with the username. MinIO then evaluates the policy and grants or revokes access to the requested API and resource.

OpenID Policy Variables

Active Directory / LDAP Policy Variables

The following table contains a list of supported policy variables for use in authorizing AD/LDAP users <minio-external-identity-management-ad-ldap>:

Variable	Description
ldap:username	The simple username (name) for the authenticated user. This is distinct from the user's DistinguishedName or CommonName.
ldap:user	The Distinguished Name used by the authenticated user.
ldap:groups	The Group Distinguished Name for the authenticated user.

For example, the following policy uses variables to substitute the authenticated user's name as part of the Resource field such that the user can only access those prefixes which match their name:

{
"Version": "2012-10-17",
"Statement": [
      {
         "Action": ["s3:ListBucket"],
         "Effect": "Allow",
         "Resource": ["arn:aws:s3:::mybucket"],
         "Condition": {"StringLike": {"s3:prefix": ["${ldap:username}/*"]}}
      },
      {
         "Action": [
         "s3:GetObject",
         "s3:PutObject"
         ],
         "Effect": "Allow",
         "Resource": ["arn:aws:s3:::mybucket/${ldap:username}/*"]
      }
   ]
}

MinIO replaces the ${ldap:username} variable in the Resource field with the value of the authenticated user's name. MinIO then evaluates the policy and grants or revokes access to the requested API and resource.