Identity and Access Management

• 1: Silo Identity Management
• 2: User Management
• 3: Group Management
• 4: OpenID Connect Access Management
• 5: Active Directory / LDAP Access Management
• 6: Silo External Identity Management Plugin
• 7: Access Management
• 8: Silo External Access Management Plugin

1 - Silo Identity Management

MinIO includes a built-in IDentity Provider (IDP) that provides core identity management functionality. The MinIO IDP supports creating an arbitrary number of long-lived users on the deployment for supporting client authentication.

Each user consists of a unique access key (username) and corresponding secret key (password). Clients must authenticate their identity by specifying both a valid access key (username) and the corresponding secret key (password) of an existing MinIO user.

Administrators use the mc admin user command to create and manage MinIO users.

MinIO also supports creating access keys. Access Keys are child identities of an authenticated parent user and inherit their permissions from the parent.

MinIO by default denies access to all actions or resources not explicitly allowed by a user’s assigned or inherited policies. You must either explicitly assign a policy describing the user’s authorized actions and resources or assign the user to groups which have associated policies. See Access Management for more information.

2 - User Management

Overview

A MinIO user consists of a unique access key (username) and corresponding secret key (password). Clients must authenticate their identity by specifying both a valid access key (username) and the corresponding secret key (password) of an existing MinIO user.

Each user can have one or more assigned policies that explicitly list the actions and resources to which that user has access. Users can also inherit policies from the groups in which they have membership.

MinIO by default denies access to all actions or resources not explicitly allowed by a user’s assigned or inherited policies. You must either explicitly assign a policy describing the user’s authorized actions and resources or assign the user to groups which have associated policies. See Access Management for more information.

This page documents user management for the MinIO internal IDentity Provider (IDP). MinIO also external management of identities using either an OpenID Connect (OIDC) or Active Directory/LDAP IDentity Provider (IDP). For more information, see:

• OpenID Connect Access Management
• Active Directory / LDAP Access Management

Enabling external identity management disables the MinIO internal IDP, with the exception of creating access keys.

Access Keys

MinIO Access Keys (formerly “Service Accounts”) are child identities of an authenticated MinIO user, including externally managed identities. Each access key inherits its privileges based on the policies attached to it’s parent user or those groups in which the parent user has membership. Access keys also support an optional inline policy which further restricts access to a subset of actions and resources available to the parent user.

A MinIO user can generate any number of access keys. This allows application owners to generate arbitrary access keys for their applications without requiring action from the MinIO administrators. Since the generated access keys have the same or fewer permissions as the parents, administrators can focus on managing the top-level parent users without micro-managing generated access keys.

You can create access keys by using the mc admin user svcacct add command. Identities created by these methods do not expire until you remove the access key or the parent account.

You can also create security token service accounts programmatically with the AssumeRole STS API endpoint. STS tokens default to expire in 1 hour, but you set expiration for up to 7 days from creation.

MinIO root User

MinIO deployments have a root user with access to all actions and resources on the deployment, regardless of the configured identity manager. When a minio server first starts, it sets the root user credentials by checking the value of the following environment variables:

• MINIO_ROOT_USER
• MINIO_ROOT_PASSWORD

Rotating the root user credentials requires updating either or both variables for all MinIO servers in the deployment. Specify long, unique, and random strings for root credentials. 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.

If these variables are unset, minio defaults to minioadmin and minioadmin as the access key and secret key respectively. MinIO strongly discourages use of the default credentials regardless of deployment environment.

User Management

Create a User

Use the mc admin user add command to create a new user on the MinIO deployment:

mc admin user add ALIAS ACCESSKEY SECRETKEY

• Replace ALIAS with the alias of the MinIO deployment.
• Replace ACCESSKEY with the access key for the user. MinIO allows retrieving the access key after user creation through the mc admin user info command.
• Replace SECRETKEY with the secret key for the user. MinIO does not provide any method for retrieving the secret key once set.

Specify a unique, random, and long string for both the ACCESSKEY and SECRETKEY. Your organization may have specific internal or regulatory requirements around generating values for use with access or secret keys.

After creating the user, use mc admin policy attach to associate a MinIO Policy Based Access Control to the new user. The following command assigns the built-in readwrite policy:

mc admin policy attach ALIAS readwrite --user=USERNAME

Replace USERNAME with the ACCESSKEY created in the previous step.

Delete a User

Use the mc admin user rm command to remove a user on a MinIO deployment:

mc admin user rm ALIAS USERNAME

• Replace ALIAS with the alias of the MinIO deployment.
• Replace USERNAME with the name of the user to remove.

3 - Group Management

Overview

A group is a collection of users. Each group can have one or more assigned 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 or supported policy action. 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. MinIO by default denies access to any resource or operation not explicitly allowed by a user’s assigned or inherited policies.

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.

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

4 - OpenID Connect Access Management

MinIO supports using an OpenID Connect (OIDC) compatible IDentity Provider (IDP) such as Okta, KeyCloak, Dex, Google, or Facebook for external management of user identities.

For identities managed by the external OpenID Connect (OIDC) compatible provider, MinIO can use either of two methods to assign policies to the authenticated user.

1. Use the JSON Web Token claim returned as part of the OIDC authentication flow to identify the policies to assign to the authenticated user.
2. Use the RoleArn specified in the authorization request to assign the policies attached to the provider’s RolePolicy.

MinIO by default denies access to all actions or resources not explicitly allowed by a user’s assigned or inherited policies. Users managed by an OIDC provider must specify the necessary policies as part of the JWT claim. If the user JWT claim has no matching MinIO policies, that user has no permissions to access any action or resource on the MinIO deployment.

The specific claim which MinIO looks for is configured as part of deploying the cluster with OIDC identity management. This page focuses on creating MinIO policies to match the configured OIDC claims.

Authentication and Authorization Flow

MinIO supports two OIDC authentication and authorization flows:

1. The RolePolicy flow sets the assigned policies for an authenticated user in the MinIO configuration.

   MinIO recommends using the RolePolicy method for authenticating with an OpenID provider.

2. The JWT flow sets the assigned policies for an authenticated user as part of the OIDC configuration.

MinIO supports multiple OIDC provider configurations. However, you can configure only one JWT claim-based OIDC provider per deployment. All other providers must use RolePolicy.

RolePolicy and RoleArn

With a RolePolicy, all clients which generate an STS credential using a given RoleArn receive the policy or policies associated to the RolePolicy configuration for that RoleArn.

You can use OpenID Policy Variables to create policies that programmatically manage what each individual user has access to.

The login flow for an application using OIDC credentials with a RolePolicy claim flow is as follows:

1. Create an OIDC Configuration.

2. Record the RoleArn assigned to the configuration either at time of creation or at MinIO start. Use this RoleArn with the AssumeRoleWithWebIdentity STS API.

3. Create a RolePolicy to use with the RoleArn. Use either the MINIO_IDENTITY_OPENID_ROLE_POLICY environment variable or the identity_openid role_policy configuration setting to define the list of policies to use for the provider

4. Users select the configured OIDC provider when logging in to MinIO.

5. Users complete authentication to the configured OIDC provider and redirect back to MinIO.

   MinIO only supports the OpenID Authorization Code Flow. Authentication using Implicit Flow is not supported.

6. MinIO verifies the RoleArn in the API call and checks for the RolePolicy to use. Any authentication request with the RoleArn receives the same policy access permissions.

7. MinIO returns temporary credentials in the STS API response in the form of an access key, secret key, and session token. The credentials have permissions matching those policies specified in the RolePolicy.

8. Applications use the temporary credentials returned by the STS endpoint to perform authenticated S3 operations on MinIO.

JSON Web Token Claim

Using JSON Web Tokens allows you to have individual assignment of policies. However, the use of web tokens also comes at the increased cost of managing multiple policies for separate claims.

The login flow for an application using OIDC credentials with a JSON Web Token Claim flow is as follows:

1. Authenticate to the configured OIDC provider and retrieve a JSON Web Token (JWT).

   MinIO only supports the OpenID Authorization Code Flow. Authentication using Implicit Flow is not supported.

2. Specify the JWT to the MinIO Security Token Service (STS) AssumeRoleWithWebIdentity API endpoint.

   MinIO verifies the JWT against the configured OIDC provider.

   If the JWT is valid, MinIO checks for a claim specifying a list of one or more policies to assign to the authenticated user. MinIO defaults to checking the policy claim.

3. MinIO returns temporary credentials in the STS API response in the form of an access key, secret key, and session token. The credentials have permissions matching those policies specified in the JWT claim.

4. Applications use the temporary credentials returned by the STS endpoint to perform authenticated S3 operations on MinIO.

MinIO provides an example Go application web-identity.go that handles the full login flow.

Identifying the JWT Claim Value

MinIO uses the JWT token returned as part of the OIDC authentication flow to identify the specific policies to assign to the authenticated user.

You can use a JWT Debugging tool to decode the returned JWT token and validate that the user attributes include the required claims.

See RFC 7519: JWT Claim for more information on JWT claims.

Defer to the documentation for your preferred OIDC provider for instructions on configuring user claims.

Creating Policies to Match Claims

Use the mc admin policy command to create policies that match one or more claim values.

OIDC Policy Variables

The following table contains a list of supported policy variables for use in authorizing OIDC-managed users.

Each variable corresponds to a claim returned as part of the authenticated user’s JWT token:

See the OpenID Connect Core 1.0 document for more information on these scopes. Your OIDC provider of choice may have more specific documentation.

For example, the following policy uses variables to substitute the authenticated user’s preferred_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": ["${jwt:preferred_username}/*"]}}
      },
      {
         "Action": [
         "s3:GetObject",
         "s3:PutObject"
         ],
         "Effect": "Allow",
         "Resource": ["arn:aws:s3:::mybucket/${jwt:preferred_username}/*"]
      }
   ]
}

MinIO replaces the ${jwt:preferred_username} variable in the Resource field with the value of the preferred_username in the JWT token. MinIO then evaluates the policy and grants or revokes access to the requested API and resource.

5 - Active Directory / LDAP Access Management

MinIO supports configuring a single Active Directory or LDAP (AD/LDAP) service for external management of user identities. Enabling AD/LDAP external identity management disables the MinIO internal IDP.

For identities managed by the external AD/LDAP provider, MinIO uses the user’s Distinguished Name and attempts to map it against an existing policy.

If the AD/LDAP configuration includes the necessary settings to query the user’s AD/LDAP group membership, MinIO also uses those group Distinguished Names and attempts to map each against an existing policy.

MinIO by default denies access to all actions or resources not explicitly allowed by a user’s assigned or inherited policies. Users managed by an AD/LDAP provider must specify the necessary policies as part of the user profile data. If no policies match either the user DN or group DNs, MinIO blocks all access to actions and resources on the deployment.

The specific AD/LDAP queries MinIO issues to authenticate the user and retrieve it’s group membership are configured as part of deploying the cluster with Active Directory / LDAP identity management. This page covers creation of MinIO policies to match the possible returned Distinguished Names.

Authentication and Authorization Flow

The login flow for an application using Active Directory / LDAP credentials is as follows:

1. Specify the AD/LDAP credentials to the MinIO Security Token Service (STS) AssumeRoleWithLDAPIdentity API endpoint.

2. MinIO verifies the provided credentials against the AD/LDAP server.

3. MinIO checks for any policy whose name matches the user Distinguished Name (DN) and assigns that policy to the authenticated user.

   If configured to perform group queries, MinIO also queries for a list of AD/LDAP groups in which the user has membership. MinIO checks for any policy whose name matches a returned group DN and assigns that policy to the authenticated user.

4. MinIO returns temporary credentials in the STS API response in the form of an access key, secret key, and session token. The credentials have permissions matching those policies whose name matches either the authenticated user DN or a group DN.

MinIO provides an example Go application ldap.go that handles the full login flow.

AD/LDAP users can alternatively create access keys associated to their AD/LDAP user Distinguished Name. Access Keys are long-lived credentials which inherit their privileges from the parent user. The parent user can further restrict those privileges while creating the access keys. Use either of the following methods to create a new access key:

Use the mc admin user svcacct add command to create the access keys. Specify the user Distinguished Name as the username to which to associate the access keys.

Mapping Policies to User DN

The following commands use mc idp ldap policy attach to associate an existing MinIO policy to an AD/LDAP User DN.

mc idp ldap policy attach myminio consoleAdmin \
  --user='cn=sisko,cn=users,dc=example,dc=com'

mc idp ldap policy attach myminio readwrite,diagnostics \
  --user='cn=dax,cn=users,dc=example,dc=com'

• MinIO would assign an authenticated user with DN matching cn=sisko,cn=users,dc=example,dc=com the consoleAdmin policy, granting complete access to the MinIO server.
• MinIO would assign an authenticated user with DN matching cn=dax,cn=users,dc=example,dc=com both the readwrite and diagnostics policies, granting general read/write access to the MinIO server and access to diagnostic administrative operations.
• MinIO would assign no policies to an authenticated user with DN matching cn=quark,cn=users,dc=example,dc=com and deny all access to API operations.

Mapping Policies to Group DN

The following commands use mc idp ldap policy attach to associate an existing MinIO policy to an AD/LDAP Group DN.

mc idp ldap policy attach myminio consoleAdmin \
  --group='cn=ops,cn=groups,dc=example,dc=com'

mc idp ldap policy attach myminio diagnostics \
  --group='cn=engineering,cn=groups,dc=example,dc=com'

• MinIO would assign any authenticating user with membership in the cn=ops,cn=groups,dc=example,dc=com AD/LDAP group the consoleAdmin policy, granting complete access to the MinIO server.
• MinIO would assign any authenticating user with membership in the cn=engineering,cn=groups,dc=example,dc=com AD/LDAP group the diagnostics policy, granting access to diagnostic administrative operations.

6 - Silo External Identity Management Plugin

Overview

The MinIO Identity Management Plugin provides a REST interface for offloading authentication to an external identity manager through a webhook service.

Once enabled, client applications use the AssumeRoleWithCustomToken STS API extension to generate access tokens for MinIO. MinIO verifies this token by making a POST request to the configured plugin endpoint and uses the returned response to determine the authentication status of the client.

Configuration Settings

You can configure the MinIO Identity Management Plugin using the following environment variables or configuration settings:

MINIO_IDENTITY_PLUGIN_URL="https://external-auth.example.net:8080/auth"
MINIO_IDENTITY_PLUGIN_ROLE_POLICY="consoleAdmin"

# All other envvars are optional
MINIO_IDENTITY_PLUGIN_TOKEN="Bearer TOKEN"
MINIO_IDENTITY_PLUGIN_ROLE_ID="external-auth-provider"
MINIO_IDENTITY_PLUGIN_COMMENT="External Identity Management using PROVIDER"

mc admin config set identity_plugin \
   url="https://external-auth.example.net:8080/auth" \
   role_policy="consoleAdmin" \

   # All other config settings are optional
   token="Bearer TOKEN" \
   role_id="external-auth-provider" \
   comment="External Identity Management using PROVIDER"

Authentication and Authorization Flow

The login flow for an application is as follows:

1. Make a POST request using the AssumeRoleWithCustomToken API.

   The request includes a token used by the configured external identity manager for authenticating the client.

2. MinIO makes a POST call to the configured identity plugin URL using the token specified to the STS API.

3. On successful authentication, the identity manager returns a 200 OK response with an application/json content-type and body with the following structure:

   {
      "user": "<string>",
      "maxValiditySeconds": 3600,
      "claims": {"KEY": "VALUE", ...}
   }

   user	The owner of the requested credentials
   maxValiditySeconds	The maximum allowed expiry duration for the returned credentials
   claims	A JSON string of "key": "value" pair claims associated with the requested credentials. MinIO reserves and ignores the exp, parent, and sub claims objects if present.

4. MinIO returns a response to the STS API request that includes temporary credentials for use with making authenticated requests.

If the identity manager rejects the authentication request or otherwise encounters an error, the response must return a 403 FORBIDDEN HTTP status code with an application/json content-type and body with the following structure:

{
     "reason": "<string>"
}

The "reason" field should include the reason for the 403.

Creating Policies to Match Claims

Use the mc admin policy command to create policies that match one or more claim values.

7 - Access Management

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 and conditions that outline the permissions of a user or group 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

Built-In Policies

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

consoleAdmin

userpolicy

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

userpolicy

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

userpolicy

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

diagnostics

userpolicy

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

userpolicy

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 or a supported action. The table describes a subset of operations a client could perform if authenticated as that user:

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.

Policy Document Structure

MinIO policy documents use the same schema as AWS IAM Policy 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.

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.

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

  The * wildcard may result in unintended application of a policy to multiple buckets or prefixes based on the pattern match. 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.

  An object pattern and a bucket ARN are not interchangeable. See Bucket and Object Resources.

• For the Statement.Condition key, you can specify one or more supported Conditions.

Bucket and Object Resources

A resource ARN either names a bucket or names objects within it, and the two forms authorize different operations:

• arn:aws:s3:::mybucket names the bucket itself, and authorizes bucket-level operations such as ListBucket or PutBucketPolicy.
• arn:aws:s3:::mybucket/* names the objects in the bucket, and authorizes object operations such as GetObject or PutObject.

Grant both when a principal needs both, which is the conventional form for a policy that manages a bucket and its contents:

"Resource": ["arn:aws:s3:::mybucket", "arn:aws:s3:::mybucket/*"]

Everything else is unchanged. ListBucket, GetBucketLocation, the bucket configuration reads, and CreateBucket are still authorized through an object pattern, so listing and provisioning flows written that way keep working. Deny statements and NotResource exclusions match as they always did, so no restriction written against mybucket/* is weakened. The built-in readwrite, readonly, writeonly and diagnostics policies use arn:aws:s3:::* and are unaffected.

Supported S3 Policy Actions

MinIO policy documents support a subset of IAM S3 Action keys. This section also includes any condition keys 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:*

policy-action

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

policy-action

Controls access to the CreateBucket S3 API operation.

s3:DeleteBucket

policy-action

Controls access to the DeleteBucket S3 API operation.

s3:ForceDeleteBucket

policy-action

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

s3:GetBucketLocation

policy-action

Controls access to the GetBucketLocation S3 API operation.

s3:ListAllMyBuckets

policy-action

Controls access to the ListBuckets S3 API operation.

s3:DeleteObject

policy-action

Controls access to the DeleteObject S3 API operation.

Supports the following additional condition key:

s3:versionid

s3:GetObject

policy-action

Controls access to the GetObject S3 API operation.

Supports the following additional condition keys:

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

s3:GetObjectAttributes

policy-action

Controls access to the GetObjectAttributes S3 API operation.

The policy parser admits the following condition key for this action:

s3:ExistingObjectTag/<key>

The current handler authorizes before it loads object metadata, however, so that condition value is absent for this operation.

s3:GetObjectVersionAttributes

policy-action

Controls access to the GetObjectAttributes S3 API operations on versioned objects.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

The version ID comes from the request query. The current handler authorizes before it loads object metadata, so s3:ExistingObjectTag/<key> is admitted by the policy parser but absent at evaluation time for this operation.

s3:RestoreObject

policy-action

Controls access to the RestoreObject S3 API operation.

s3:ListBucket

policy-action

Controls access to the ListObjectsV2 S3 API operation.

Supports the following additional condition keys:

s3:prefix
s3:delimiter
s3:max-keys

s3:PutObject

policy-action

Controls access to the PutObject S3 API operation.

Supports the following additional condition keys:

s3:x-amz-copy-source
s3:x-amz-server-side-encryption
s3:x-amz-server-side-encryption-customer-algorithm
s3:x-amz-server-side-encryption-aws-kms-key-id
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

policy-action

Controls access to the PutObjectTagging S3 API operation.

Supports the following additional condition keys:

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

s3:GetObjectTagging

policy-action

Controls access to the GetObjectTagging S3 API operation.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

s3:DeleteObjectTagging

policy-action

Controls access to the DeleteObjectTagging S3 API operation.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

Bucket Configuration

s3:GetBucketPolicy

policy-action

Controls access to the GetBucketPolicy S3 API operation.

s3:PutBucketPolicy

policy-action

Controls access to the PutBucketPolicy S3 API operation.

s3:DeleteBucketPolicy

policy-action

Controls access to the DeleteBucketPolicy S3 API operation.

s3:GetBucketTagging

policy-action

Controls access to the GetBucketTagging S3 API operation.

s3:PutBucketTagging

policy-action

Controls access to the PutBucketTagging S3 API operation.

The policy parser retains the following condition keys for compatibility:

s3:RequestObjectTagKeys
s3:RequestObjectTag/<key>

The handler does not populate them from the bucket-tagging XML body. Only the historical, client-supplied X-Amz-Tagging Header fallback can populate them, and that Header does not constrain the bucket tags stored from the body. Do not use these keys to enforce the contents of a PutBucketTagging request.

s3:GetBucketPolicyStatus

policy-action

Controls access to the GetBucketPolicyStatus S3 API operation.

Multipart Upload

s3:AbortMultipartUpload

policy-action

Controls access to the AbortMultipartUpload S3 API operation.

s3:ListMultipartUploadParts

policy-action

Controls access to the ListParts S3 API operation.

s3:ListBucketMultipartUploads

policy-action

Controls access to the ListMultipartUploads S3 API operation.

Versioning and Retention

s3:PutBucketVersioning

policy-action

Controls access to the PutBucketVersioning S3 API operation.

s3:GetBucketVersioning

policy-action

Controls access to the GetBucketVersioning S3 API operation.

s3:DeleteObjectVersion

policy-action

Controls access to the DeleteObjectVersion S3 API operation.

Supports the following additional condition keys:

s3:versionid

s3:ListBucketVersions

policy-action

Controls access to the ListBucketVersions S3 API operation.

Supports the following additional condition keys:

s3:prefix
s3:delimiter
s3:max-keys

s3:PutObjectVersionTagging

policy-action

Controls access to the PutObjectVersionTagging S3 API operation.

Supports the following additional condition keys:

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

s3:GetObjectVersionTagging

policy-action

Controls access to the GetObjectVersionTagging S3 API operation.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

s3:DeleteObjectVersionTagging

policy-action

Controls access to the DeleteObjectVersionTagging S3 API operation.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

s3:GetObjectVersion

policy-action

Controls access to the GetObjectVersion S3 API operation.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

s3:BypassGovernanceRetention

policy-action

Controls access to the following S3 API operations on objects locked under GOVERNANCE retention mode:

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

See the S3 documentation on s3:BypassGovernanceRetention for more information.

Supports the following additional condition keys:

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

policy-action

Controls access to the PutObjectRetention S3 API operation.

Required for any PutObject operation that specifies retention metadata.

Supports the following additional condition keys:

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

s3:GetObjectRetention

policy-action

Controls access to the GetObjectRetention S3 API operation.

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

Supports the following additional condition keys:

s3:x-amz-server-side-encryption
s3:x-amz-server-side-encryption-customer-algorithm
s3:x-amz-server-side-encryption-aws-kms-key-id
s3:versionid

s3:GetObjectLegalHold

policy-action

Controls access to the GetObjectLegalHold S3 API operation.

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

s3:PutObjectLegalHold

policy-action

Controls access to the PutObjectLegalHold S3 API operation.

Required for any PutObject operation that specifies legal hold metadata.

Supports the following additional condition keys:

s3:x-amz-server-side-encryption
s3:x-amz-server-side-encryption-customer-algorithm
s3:x-amz-server-side-encryption-aws-kms-key-id
s3:object-lock-legal-hold
s3:versionid

s3:GetBucketObjectLockConfiguration

policy-action

Controls access to the GetObjectLockConfiguration S3 API operation.

s3:PutBucketObjectLockConfiguration

policy-action

Controls access to the PutObjectLockConfiguration S3 API operation.

Bucket Notifications

s3:GetBucketNotification

policy-action

Controls access to the GetBucketNotification S3 API operation.

s3:PutBucketNotification

policy-action

Controls access to the PutBucketNotification S3 API operation.

s3:ListenNotification

policy-action

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

policy-action

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

policy-action

Controls access to the PutLifecycleConfiguration S3 API operation.

s3:GetLifecycleConfiguration

policy-action

Controls access to the GetLifecycleConfiguration S3 API operation.

Object Encryption

s3:PutEncryptionConfiguration

policy-action

Controls access to the PutEncryptionConfiguration S3 API operation.

s3:GetEncryptionConfiguration

policy-action

Controls access to the GetEncryptionConfiguration S3 API operation.

Bucket Replication

s3:GetReplicationConfiguration

policy-action

Controls access to the GetBucketReplication S3 API operation.

s3:PutReplicationConfiguration

policy-action

Controls access to the PutBucketReplication S3 API operation.

s3:ReplicateObject

policy-action

MinIO Extension for controlling API operations related to Server-Side Bucket Replication.

Required for MinIO server-side replication.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

s3:ReplicateDelete

policy-action

MinIO Extension for controlling API operations related to Server-Side Bucket Replication.

Required for synchronizing delete operations as part of MinIO server-side replication.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

s3:ReplicateTags

policy-action

MinIO Extension for controlling API operations related to Server-Side Bucket Replication.

Required for MinIO server-side replication.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

s3:GetObjectVersionForReplication

policy-action

MinIO Extension for controlling API operations related to Server-Side Bucket Replication.

Required for MinIO server-side replication.

Supports the following additional condition keys:

s3:versionid
s3:ExistingObjectTag/<key>

Supported S3 Policy Condition Keys

MinIO policy documents support IAM conditional statements.

Each condition element consists of operators 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

MinIO supports the following condition keys for all supported actions:

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

Condition Value Sources and Precedence

Silo constructs the condition-value map from semantic request sources instead of treating every header and query parameter as interchangeable. A raw header or query parameter whose name resembles an internal condition key cannot replace a value calculated by the server or create one that the server did not provide.

If an API path does not load or calculate a listed source, that condition key is absent. Its result then follows the semantics of the policy operator in use; do not assume that merely listing a key for an action causes the server to synthesize a value.

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

Note

Added: 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 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:*

policy-action

Selector for all admin action keys.

admin:Heal

policy-action

Allows heal command

admin:StorageInfo

policy-action

Allows listing server info

admin:DataUsageInfo

policy-action

Allows listing data usage info

admin:TopLocksInfo

policy-action

Allows listing top locks

admin:Profiling

policy-action

Allows profiling

admin:ServerTrace

policy-action

Allows listing server trace

admin:ConsoleLog

policy-action

Allows listing console logs on terminal

admin:KMSCreateKey

policy-action

Allows creating a new KMS master key

While this option is still supported, kms:CreateKey is preferred.

admin:KMSKeyStatus

policy-action

Allows getting KMS key status

While this option is still supported, kms:KeyStatus is preferred.

admin:ServerInfo

policy-action

Allows listing server info

admin:OBDInfo

policy-action

Allows obtaining cluster on-board diagnostics

admin:ServerUpdate

policy-action

Allows MinIO binary update

admin:ServiceRestart

policy-action

Allows restart of MinIO service.

admin:ServiceStop

policy-action

Allows stopping MinIO service.

admin:ConfigUpdate

policy-action

Allows MinIO config management

admin:CreateUser

policy-action

Allows creating MinIO user

admin:DeleteUser

policy-action

Allows deleting MinIO user

admin:ListUsers

policy-action

Allows list users permission

admin:EnableUser

policy-action

Allows enable user permission

admin:DisableUser

policy-action

Allows disable user permission

admin:GetUser

policy-action

Allows GET permission on user info

admin:AddUserToGroup

policy-action

Allows adding user to group permission

admin:RemoveUserFromGroup

policy-action

Allows removing user to group permission

admin:GetGroup

policy-action

Allows getting group info

admin:ListGroups

policy-action

Allows list groups permission

admin:EnableGroup

policy-action

Allows enable group permission

admin:DisableGroup

policy-action

Allows disable group permission

admin:CreatePolicy

policy-action

Allows create policy permission

admin:DeletePolicy

policy-action

Allows delete policy permission

admin:GetPolicy

policy-action

Allows get policy permission

admin:AttachUserOrGroupPolicy

policy-action

Allows attaching a policy to a user/group

admin:ListUserPolicies

policy-action

Allows listing user policies

admin:CreateServiceAccount

policy-action

Allows creating MinIO Access Key

admin:UpdateServiceAccount

policy-action

Allows updating MinIO Access Key

admin:RemoveServiceAccount

policy-action

Allows deleting MinIO Access Key

admin:ListServiceAccounts

policy-action

Allows listing MinIO Access Key

admin:SetBucketQuota

policy-action

Allows setting bucket quota

admin:GetBucketQuota

policy-action

Allows getting bucket quota

admin:SetBucketTarget

policy-action

Allows setting bucket target

admin:GetBucketTarget

policy-action

Allows getting bucket targets

admin:SetTier

policy-action

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

admin:ListTier

policy-action

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

admin:BandwidthMonitor

policy-action

Allows retrieving metrics related to current bandwidth consumption.

admin:Prometheus

policy-action

Allows access to MinIO metrics. Only required if MinIO requires authentication for scraping metrics.

admin:ListBatchJobs

policy-action

Allows access to list the active batch jobs.

admin:DescribeBatchJob

policy-action

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

admin:StartBatchJob

policy-action

Allows user to begin a batch job run.

admin:CancelBatchJob

policy-action

Allows user to stop a batch job currently in process.

admin:Rebalance

policy-action

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

KMS policy action keys

MinIO supports restricting key management service (KMS) actions by policy.

You can restrict KMS activities in a policy with any of the following KMS actions:

kms:Status

policy-action

Check the status of KMS.

kms:Metrics

policy-action

Obtain Prometheus-formatted metrics.

kms:API

policy-action

List supported API endpoints.

kms:Version

policy-action

Retrieve the KMS version.

kms:CreateKey

policy-action

Create a new KMS key.

kms:ListKeys

policy-action

Retrieve a list of existing KMS keys.

kms:KeyStatus

policy-action

Retrieve the status of a specified KMS key.

To select all of the available kms policy actions, use kms:*.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "kms:CreateKey",
                "kms:KeyStatus",
                "kms:ListKeys"
            ],
            "Resource": [
                "arn:minio:kms:::keys-abc-*",
                "arn:minio:kms:::myuser-*"
            ]
        }
    ]
}

mc admin Policy Condition Keys

MinIO supports the following conditions for use with defining policies for 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.

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.

Each MinIO identity provider supports its own set of policy variables:

• MinIO Policy Variables
• OpenID Policy Variables
• Active Directory / LDAP Policy Variables

MinIO Policy Variables

The following table contains a list of recommended policy variables for use in authorizing MinIO-managed users:

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

The following table contains a list of supported policy variables for use in authorizing OIDC-managed users.

Each variable corresponds to a claim returned as part of the authenticated user’s JWT token:

See the OpenID Connect Core 1.0 document for more information on these scopes. Your OIDC provider of choice may have more specific documentation.

For example, the following policy uses variables to substitute the authenticated user’s preferred_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": ["${jwt:preferred_username}/*"]}}
      },
      {
         "Action": [
         "s3:GetObject",
         "s3:PutObject"
         ],
         "Effect": "Allow",
         "Resource": ["arn:aws:s3:::mybucket/${jwt:preferred_username}/*"]
      }
   ]
}

MinIO replaces the ${jwt:preferred_username} variable in the Resource field with the value of the preferred_username in the JWT token. MinIO then evaluates the policy and grants or revokes access to the requested API and resource.

Active Directory / LDAP Policy Variables

The following table contains a list of supported policy variables for use in authorizing AD/LDAP users:

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.

8 - Silo External Access Management Plugin

Overview

The MinIO Access Management Plugin provides a REST interface for offloading authorization through a webhook service.

Once enabled, MinIO sends the request and credential details for every API call to the configured external HTTP(S) endpoint and looks for a response of ALLOW or DENY. MinIO can therefore delegate the access management to the external system instead of relying on S3 policy based access control.

Configuration Settings

You can configure the MinIO External Access Management Plugin using the following environment variables or configuration settings.

MINIO_POLICY_PLUGIN_URL="https://external-authz.example.net:8080/authz"

# All other envvars are optional
MINIO_POLICY_PLUGIN_AUTH_TOKEN="Bearer TOKEN"
MINIO_POLICY_PLUGIN_ENABLE_HTTP2="OFF"
MINIO_POLICY_PLUGIN_COMMENT="External Access Management using PROVIDER"

mc admin config set policy_plugin \
   url="https://external-authz.example.net:8080/authz" \

   # All other config settings are optional
   auth_token="Bearer TOKEN" \
   enable_http2="off" \
   comment="External Access Management using PROVIDER"

Authentication and Authorization Flow

The login flow for an application is as follows:

1. The client includes authentication information as part of performing the API call
2. The configured Identity Manager authenticates the client
3. MinIO makes a POST call to the configured access management plugin URL which includes the context of the API call and authentication data
4. On successful authorization, the access manager returns a 200 OK response with a JSON body of either result true or "result" : { "allow" : true }:

If the access manager rejects the authorization request, MinIO automatically blocks and denies the API call.

Request Body Example

The following JSON resembles the request body sent as part of the POST to the configured access manager webhook.

{
   "input": {
      "account": "minio",
      "groups": null,
      "action": "s3:ListBucket",
      "bucket": "test",
      "conditions": {
         "Authorization": [
         "AWS4-HMAC-SHA256 Credential=minio/20220507/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=62012db6c47d697620cf6c68f0f45f6e34894589a53ab1faf6dc94338468c78a"
         ],
         "CurrentTime": [ "2022-05-07T18:31:41Z" ],
         "Delimiter": [ "/" ],
         "EpochTime": [
         "1651948301"
         ],
         "Prefix": [ "" ],
         "Referer": [ "" ],
         "SecureTransport": [ "false" ],
         "SourceIp": [ "127.0.0.1" ],
         "User-Agent": [ "MinIO (linux; amd64) minio-go/v7.0.24 mc/DEVELOPMENT.2022-04-20T23-07-53Z" ],
         "UserAgent": [ "MinIO (linux; amd64) minio-go/v7.0.24 mc/DEVELOPMENT.2022-04-20T23-07-53Z" ],
         "X-Amz-Content-Sha256": [ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855" ],
         "X-Amz-Date": [ "20220507T183141Z" ],
         "authType": [ "REST-HEADER" ],
         "principaltype": [ "Account" ],
         "signatureversion": [ "AWS4-HMAC-SHA256" ],
         "userid": [ "minio" ],
         "username": [ "minio" ],
         "versionid": [ "" ]
      },
      "owner": true,
      "object": "",
      "claims": {},
      "denyOnly": false
   }
}

Response Body Example

MinIO requires the response body from the Access Management service meet one of the two following formats:

{ "result" : true }

{ "result" : { "allow" : true } }