minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-07-24 10:22:32 +03:00
Code Activity
Files
e3e9caf593cc246d04fda9a149379b2594e68fb8
docs/source/security/minio-authentication-authorization.rst
ravindk89 e3e9caf593 Alpha Release Work
2020-09-30 18:37:33 -04:00

24 KiB
Raw Blame History

Authentication and Authorization

minio

Table of Contents

Overview

Authentication is the process of verifying the identity of a connecting client. MinIO authentication requires providing user credentials in the form of an access key (username) and corresponding secret key (password). The MinIO deployment only grants access if:

  • The access key corresponds to a user on the deployment, and
  • The secret key corresponds to the specified access key.

Authorization is the process of restricting the actions and resources the authenticated client can perform on the deployment. MinIO uses Policy-Based Access Control (PBAC), where each policy describes one or more rules that outline the permissions of a user or group of users. MinIO supports a subset of IAM actions and conditions <reference_policies_actions-resources-contextkeys.html> when creating policies. By default, MinIO denies access to actions or resources not explicitly referenced in a user's assigned or inherited policies.

  • For more information on MinIO user management, see minio-auth-authz-users.
  • For more information on MinIO group management, see minio-auth-authz-groups.
  • For more information on MinIO policy creation, see minio-auth-authz-pbac-policies.

Users

A user is an identity with associated privileges on a MinIO deployment. Each user consists of a unique access key (username) and corresponding secret key (password). The access key and secret key support authentication on the MinIO deployment, similar to a username and password. Clients must specify both a valid access key (username) and the corresponding secret key (password) to access the MinIO deployment.

Each user can have one or more assigned policies <minio-auth-authz-pbac-policies> that explicitly list the actions and resources to which the user is allowed or denied access. Policies support authorization of operations on the MinIO deployment, such that clients can only perform an operation if the user's assigned policies allow access to both the operation action and the target resources.

For example, consider the following table of users. Each user is assigned a built-in policy <minio-auth-authz-pbac-built-in> or a supported action <minio-auth-authz-pbac-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.
PUT on audit bucket
Auditing
readonly on audit bucket
 GET on audit bucket
Admin admin:* All mc admin commands.

Users also inherit permissions from their assigned groups <minio-auth-authz-groups>. A user's total set of permissions consists of their explicitly assigned permissions and the inherited permissions from each of their assigned groups.

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>.

root User

By default, MinIO deployments provide root user with access to all actions and resources on the deployment. The root user credentials are set when starting the minio server. When specifying the root access key and secret key, consider using long, unique, and random strings. Exercise all possible precautions in storing the access key and secret key, such that only known and trusted individuals who require superuser access to the deployment can retrieve the root credentials.

  • MinIO strongly discourages using the root user for regular client access regardless of the environment (development, staging, or production).
  • MinIO strongly recommends creating users such that each client has access to the minimal set of actions and resources required to perform their assigned workloads.

Groups

A group is a collection of users <minio-auth-authz-users>. Each group can have one or more assigned policies <minio-auth-authz-pbac-policies> that explicitly list the actions and resources to which group members are allowed or denied access.

For example, consider the following groups. Each group is assigned a built-in policy <minio-auth-authz-pbac-built-in> or supported policy action <minio-auth-authz-pbac-actions>. Each group also has one or more assigned users. Each user's total set of permissions consists of their explicitly assigned permission and the inherited permissions from each of their assigned groups.

Group Policy Members
Operations
readwrite on finance bucket
readonly on audit bucket
 john.doe, jane.doe
Auditing
readonly on audit bucket
 jen.doe, joe.doe
Admin admin:* greg.doe, jen.doe

Groups provide a simplified method for managing shared permissions among users with common access patterns and workloads. Client's cannot authenticate to a MinIO deployment using a group as an identity.

Deny overrides Allow

MinIO follows the IAM standard where a Deny rule overrides Allow rule on the same action or 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>.

Policies

MinIO uses Policy-Based Access Control (PBAC) for supporting authorization of users who have successfully authenticated to the deployment. Each policy describes one or more rules that outline the permissions of a user or group of users. MinIO PBAC follows the guidelines and standards set by AWS Identity and Access Management (IAM). MinIO supports a subset of IAM actions and conditions <reference_policies_actions-resources-contextkeys.html> when creating policies. By default, MinIO denies access to actions or resources not explicitly referenced in a user's assigned or inherited policies.

This section focuses on MinIO's implementation and extensions of IAM policies and access management. A complete description of IAM or IAM policies is out of scope of this documentation. Consider deferring to the IAM documentation <> for more complete documentation on the IAM service.

Built-In Policies

MinIO provides the following built-in policies for assigning to users and groups:

readonly

Grants read-only permissions for all buckets and objects on the MinIO server.

readwrite

Grants read and write permissions for all buckets and objects on the MinnIO server.

diagnostics

Grants permission to perform diagnostic actions on the MinIO server.

writeonly

Grants write-only permissions for all buckets and objects on the MinIO server.

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 general schema 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>.

{
   "Version" : "2012-10-17",
   "Statement" : [
      {
         "Effect" : "Allow",
         "Action" : [ "s3:<ActionName>", ... ],
         "Resource" : "arn:minio:s3:::*",
         "Condition" : { ... }
      },
      {
         "Effect" : "Deny",
         "Action" : [ "s3:<ActionName>", ... ],
         "Resource" : "arn:minio:s3:::*",
         "Condition" : { ... }
      }
   ]
}
  • For the Statement.Action array, specify one or more supported S3 actions <minio-auth-authz-pbac-actions>. MinIO deployments supports a subset of AWS S3 actions.
  • For the Statement.Resource key, you can replace the * with the specific bucket to which the policy statement should apply. Using * applies the statement to all resources on the MinIO deployment.
  • For the Statement.Condition key, you can specify one or more supported Conditions <minio-auth-authz-pbac-conditions>. MinIO deployments supports a subset of AWS S3 conditions.

Supported Policy Actions

MinIO policy documents support a subset of IAM S3 Action keys <list_amazons3.html#amazons3-actions-as-permissions>.

The following table lists the MinIO-supported policy action keys.

s3:*

Selector for all supported S3 actions.

s3:AbortMultipartUpload

Corresponds to the s3:AbortMultipartUpload <API_AbortMultipartUpload.html> IAM action.

s3:CreateBucket

Corresponds to the s3:CreateBucket <API_CreateBucket.html> IAM action.

s3:DeleteBucket

Corresponds to the s3:DeleteBucket <API_DeleteBucket.html> IAM action.

s3:ForceDeleteBucket

Corresponds to the s3:DeleteBucket <API_ForceDeleteBucket.html> IAM action for operations with the x-minio-force-delete flag.

s3:DeleteBucketPolicy

Corresponds to the s3:DeleteBucketPolicy <API_DeleteBucketPolicy.html> IAM action.

s3:DeleteObject

Corresponds to the s3:DeleteObject <API_DeleteObject.html> IAM action.

s3:GetBucketLocation

Corresponds to the s3:GetBucketLocation <API_GetBucketLocation.html> IAM action.

s3:GetBucketNotification

Corresponds to the s3:GetBucketNotification <API_GetBucketNotification.html> IAM action.

s3:GetBucketPolicy

Corresponds to the s3:GetBucketPolicy <API_GetBucketPolicy.html> IAM action.

s3:GetObject

Corresponds to the s3:GetObject <API_GetObject.html> IAM action.

s3:HeadBucket

Corresponds to the s3:HeadBucket <API_HeadBucket.html> IAM action.

This action is unused in MinIO.

s3:ListAllMyBuckets

Corresponds to the s3:ListAllMyBuckets <API_ListAllMyBuckets.html> IAM action.

s3:ListBucket

Corresponds to the s3:ListBucket <API_ListBucket.html> IAM action.

s3:ListMultipartUploads

Corresponds to the s3:ListMultipartUploads <API_ListMultipartUploads.html> IAM action.

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.

s3:ListParts

Corresponds to the s3:ListParts <API_ListParts.html> IAM action.

s3:PutBucketLifecycle

Corresponds to the s3:PutBucketLifecycle <API_PutBucketLifecycle.html> IAM action.

s3:GetBucketLifecycle

Corresponds to the s3:GetBucketLifecycle <API_GetBucketLifecycle.html> IAM action.

s3:PutObjectNotification

Corresponds to the s3:PutObjectNotification <API_PutObjectNotification.html> IAM action.

s3:PutBucketPolicy

Corresponds to the s3:PutBucketPolicy <API_PutBucketPolicy.html> IAM action.

s3:PutObject

Corresponds to the s3:PutObject <API_PutObject.html> IAM action.

s3:DeleteObjectVersion

Corresponds to the s3:DeleteObjectVersion <API_DeleteObjectVersion.html> IAM action.

s3:DeleteObjectVersionTagging

Corresponds to the s3:DeleteObjectVersionTagging <API_DeleteObjectVersionTagging.html> IAM action.

s3:GetObjectVersion

Corresponds to the s3:GetObjectVersion <API_GetObjectVersion.html> IAM action.

s3:GetObjectVersionTagging

Corresponds to the s3:GetObjectVersionTagging <API_GetObjectVersionTagging.html> IAM action.

s3:PutObjectVersionTagging

Corresponds to the s3:PutObjectVersionTagging <API_PutObjectVersionTagging.html> IAM action.

s3:BypassGovernanceRetention

Corresponds to the s3:BypassGovernanceRetention <object-lock-managing.html#object-lock-managing-bypass> IAM action.

This action applies to the following API operations on objects locked under GOVERNANCE <mc retention set MODE> retention mode:

  • PutObjectRetention
  • PutObject
  • DeleteObject

s3:PutObjectRetention

Corresponds to the s3:PutObjectRetention <API_PutObjectRetention.html> IAM action.

s3:GetObjectRetention

Corresponds to the s3:GetObjectRetention <API_GetObjectRetention.html> IAM action.

This action applies to the following API operations on objects locked under any retention mode:

  • GetObject
  • HeadObject

s3:GetObjectLegalHold

Corresponds to the s3:GetObjectLegalHold <API_GetObjectLegalHold.html> IAM action.

This action applies to the following API operations on objects locked under legal hold:

  • GetObject

s3:PutObjectLegalHold

Corresponds to the s3:PutObjectLegalHold <API_PutObjectLegalHold.html> IAM action.

This action applies to the following API operations on objects locked under legal hold:

  • PutObject

s3:GetBucketObjectLockConfiguration

Corresponds to the s3:GetBucketObjectLockConfiguration <API_GetBucketObjectLockConfiguration.html> IAM action.

s3:PutBucketObjectLockConfiguration

Corresponds to the s3:PutBucketObjectLockConfiguration <API_PutBucketObjectLockConfiguration.html> IAM action.

s3:GetBucketTagging

Corresponds to the s3:GetBucketTagging <API_GetBucketTagging.html> IAM action.

s3:PutBucketTagging

Corresponds to the s3:PutBucketTagging <API_PutBucketTagging.html> IAM action.

s3:Get

Corresponds to the s3:Get <API_Get.html> IAM action.

s3:Put

Corresponds to the s3:Put <API_Put.html> IAM action.

s3:Delete

Corresponds to the s3:Delete <API_Delete.html> IAM action.

s3:PutBucketEncryption

Corresponds to the s3:PutBucketEncryption <API_PutBucketEncryption.html> IAM action.

s3:GetBucketEncryption

Corresponds to the s3:GetBucketEncryption <API_GetBucketEncryption.html> IAM action.

s3:PutBucketVersioning

Corresponds to the s3:PutBucketVersioning <API_PutBucketVersioning.html> IAM action.

s3:GetBucketVersioning

Corresponds to the s3:GetBucketVersioning <API_GetBucketVersioning.html> IAM action.

s3:GetReplicationConfiguration

Corresponds to the s3:GetReplicationConfiguration <API_GetReplicationConfiguration.html> IAM action.

s3:PutReplicationConfiguration

Corresponds to the s3:PutReplicationConfiguration <PutReplicationConfiguration.html> IAM action.

s3:ReplicateObject

Corresponds to the s3:ReplicateObject <API_ReplicateObject.html> IAM action.

s3:ReplicateDelete

Corresponds to the s3:ReplicateDelete <API_ReplicateDelete.html> IAM action.

s3:ReplicateTags

Corresponds to the s3:ReplicateTags <API_ReplicateTags.html> IAM action.

s3:GetObjectVersionForReplication

Corresponds to the s3:GetObjectVersionForReplication <API_GetObjectVersionForReplication.html> IAM action.

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:SetBucketQuota

Allows setting bucket quota

admin:GetBucketQuota

Allows getting bucket quota

admin:SetBucketTarget

Allows setting bucket target

admin:GetBucketTarget

Allows getting bucket targets

Supported 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-auth-authz-pbac-actions>:

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

The following table lists additional supported condition keys for specific actions:

Action Key Condition Keys
s3:GetObject
s3:x-amz-server-side-encryption
s3:x-amz-server-side-encryption-customer-algorithm
s3:ListBucket
s3:prefix
s3:delimiter
s3:max-keys
s3:PutObject
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:object-lock-retain-until-date
s3:object-lock-mode
s3:object-lock-legal-hold
s3:PutObjectRetention
s3:x-amz-object-lock-remaining-retention-days
s3:x-amz-object-lock-retain-until-date
s3:x-amz-object-lock-mode
s3:PutObjectLegalHold s3:object-lock-legal-hold
s3:BypassGovernanceRetention
s3:object-lock-remaining-retention-days
s3:object-lock-retain-until-date
s3:object-lock-mode
s3:object-lock-legal-hold
s3:GetObjectVersion s3:versionid
s3:GetObjectVersionTagging s3:versionid
s3:DeleteObjectVersion s3:versionid
s3:DeleteObjectVersionTagging s3:versionid

mc admin Policy Condition Keys

MinIO supports the following conditions for use with defining policies for mc admin actions <minio-auth-authz-pbac-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>

Creating Custom Policies

Use the mc admin policy command to add a policy to the MinIO server. The policy must be a valid JSON document formatted according to IAM policy specifications. For example:

mc config host add myminio http://myminio1.example.net:9000 <access_key> <secret_key>

mc admin policy add myminio/ new_policy new_policy.json

To add this policy to a user or group, use the mc admin policy set command:

mc admin policy set myminio/ new_policy user=user_name

mc admin policy set myminio/ new_policy group=group_name