Security¶

MinIO implements a comprehensive security model covering identity and access management (IAM), server-side encryption (SSE), TLS for transport security, and audit logging. Its security architecture is designed to be compatible with the AWS S3 security model while providing additional features for on-premises and edge deployments.

See also: index, architecture, operations

IAM Policies¶

Policy Structure¶

MinIO uses AWS IAM-compatible JSON policy documents. Each policy contains one or more statements that define what actions are allowed or denied on which resources.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket"
            ],
            "Resource": [
                "arn:aws:s3:::mybucket",
                "arn:aws:s3:::mybucket/*"
            ]
        }
    ]
}

Policy Management via mc CLI¶

# Create a policy from a JSON file
mc admin policy create myminio readwrite-policy /tmp/readwrite-policy.json

# Create a user
mc admin user add myminio newuser newpassword123

# Attach policy to user
mc admin policy attach myminio readwrite-policy --user newuser

# Attach a built-in policy
mc admin policy attach myminio readonly --user vieweruser

# List all policies
mc admin policy list myminio

# View policy details
mc admin policy info myminio readwrite-policy

# Detach policy from user
mc admin policy detach myminio readwrite-policy --user newuser

# Delete a policy
mc admin policy remove myminio readwrite-policy

Built-in Policies¶

MinIO ships with predefined policies for common use cases:

Policy	Description
`readonly`	Read access to all buckets
`readwrite`	Read and write access to all buckets
`writeonly`	Write access to all buckets
`diagnostics`	Access to cluster health and diagnostics endpoints
`consoleAdmin`	Full access to the MinIO Console
`admin`	Full administrative access

Policy Variables¶

MinIO supports policy variables that are substituted at evaluation time:

${aws:username}: Replaced with the authenticated user's username. Useful for user-specific prefix access.
${jwt:claim_name}: Replaced with the corresponding claim from an OIDC JWT token. Enables fine-grained access based on identity provider claims.

Example policy restricting each user to their own prefix:

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

Security Token Service (STS)¶

MinIO STS provides temporary, scoped credentials with a configurable expiration. This avoids long-lived access keys and enables federated identity patterns.

STS Authentication Methods¶

Method	Description	Use Case
Web Identity (OIDC)	Exchange OIDC ID token for temporary credentials	Applications using identity providers (Keycloak, Okta)
Client Grants	Exchange OAuth2 client credentials grant for temporary access	Service-to-service communication
AssumeRole	A user assumes a specific role/policy for a limited time	Cross-account access, privilege escalation with audit
LDAP STS	Bind LDAP username/password to temporary S3 credentials	LDAP-integrated environments

STS Configuration¶

Set the STS endpoint for the MinIO Client:

export MC_STS_ENDPOINT_myalias=https://sts.minio-operator.svc.cluster.local:4223/sts/ns-1

Use STS credentials as a host alias:

export MC_HOST_myalias=https://<AccessKey>:<SecretKey>:<SessionToken>@<endpoint>

The session token is validated on every request and expires according to the STS policy duration.

Bucket Policies¶

Bucket policies are JSON policy documents attached directly to a bucket (not to a user). They control access for anonymous, authenticated, and specific principal-based requests:

Anonymous access: Principal: "*" allows unauthenticated access (equivalent to S3 public buckets).
Principal-based: Restrict access to specific users or accounts.
Condition keys: Support IP-based conditions (aws:SourceIp), VPC endpoint conditions, TLS version requirements, and more.
Versioning: Policies apply to all object versions in a versioned bucket unless scoped otherwise.

Server-Side Encryption (SSE)¶

MinIO provides three server-side encryption modes to protect data at rest:

SSE-S3 (Server-Managed Keys)¶

MinIO manages the encryption keys internally. Objects are encrypted automatically using a per-object key derived from a master key managed by MinIO.

# Enable SSE-S3 on a bucket
mc encrypt set sse-s3 myminio/mybucket

Key management is entirely handled by MinIO.
Suitable for compliance requirements where encryption at rest is mandated but key management complexity must be minimized.
MinIO rotates master keys automatically.

SSE-KMS (Customer-Managed Keys via KMS)¶

Objects are encrypted using keys managed by an external Key Management Service, accessed through the MinIO Key Encryption Service (KES).

# Enable SSE-KMS with a named key
mc encrypt set sse-kms my-minio-sse-kms-key myminio/mybucket

Requires deploying MinIO KES (Key Encryption Service) as a proxy to the KMS.
Supported KMS backends: HashiCorp Vault, AWS KMS, GCP KMS, Azure Key Vault.
Each object is encrypted with a unique data key, which is itself encrypted by the KMS key.
Provides key rotation, audit, and compliance capabilities.

SSE-C (Client-Provided Keys)¶

The client provides the encryption key with each request. MinIO uses the key to encrypt/decrypt but does not store it.

# Copy an object with SSE-C encryption
mc cp myminio/mybucket/file.txt myminio/mybucket/encrypted.txt \
  --encrypt-key "myminio/mybucket/=c2VjcmV0ZW5jcnlwdGlvbmtleWNoYW5nZW1lMTIzNAo="

The encryption key is sent with each request header (X-Amz-Server-Side-Encryption-Customer-Key).
MinIO does not persist the key. If the client loses the key, the data is unrecoverable.
Suitable for applications that require full control over encryption keys.

KES (Key Encryption Service)¶

MinIO KES is a lightweight stateless proxy that sits between MinIO and the KMS:

flowchart LR
    MINIO[MinIO Server]
    KES[KES Proxy]
    KMS[HashiCorp Vault<br/>AWS KMS / GCP KMS]
    MINIO -->|Encrypt/Decrypt requests| KES
    KES -->|Key operations| KMS

KES authenticates MinIO servers via mutual TLS (mTLS).
KES enforces access policies on which keys each MinIO instance can use.
KES is stateless and can be deployed with multiple replicas for HA.

TLS Configuration¶

MinIO requires TLS for production deployments, especially when SSE, STS, or S3 signature-based authentication is used.

Server TLS¶

# Start MinIO with TLS certificates
minio server /data --certs-dir /opt/certs

Certificate files expected in the certs directory:

public.crt: Server certificate (or full chain).
private.key: Private key matching the certificate.

Mutual TLS (mTLS)¶

MinIO can enforce client certificate validation:

Set the MINIO_CERT_PASSWD environment variable if the private key is encrypted.
Configure the SNI (Server Name Indication) to support multiple domains.
Client certificates can be used as an additional authentication factor alongside or instead of access keys.

Audit Logging¶

MinIO provides detailed audit logging for compliance and security monitoring:

Audit endpoints: Configure webhook targets to receive audit events for every S3 API operation.
Log contents: Each audit entry includes the requesting user, action, bucket/object, source IP, request ID, response status, and error details.
Configuration: mc admin config set myminio audit_webhook:endpoint http://audit-collector:8080/minio-audit
Multiple targets: Multiple webhook endpoints can be configured for redundancy or different consumers.

Console Audit Logs¶

The MinIO Console (web UI) provides a viewable audit log of all administrative operations, including user creation, policy changes, and configuration modifications.

Identity Provider Integration¶

OIDC (OpenID Connect)¶

MinIO integrates with OIDC providers (Keycloak, Okta, Dex, Entra ID) for user authentication:

Users authenticate via the OIDC provider and receive a JWT token.
MinIO validates the JWT and maps it to IAM policies using ${jwt:claim_name} policy variables.
Supports dynamic policy assignment based on OIDC group memberships or custom claims.

LDAP (Active Directory)¶

MinIO supports LDAP for enterprise environments:

Users authenticate with their LDAP credentials via STS.
MinIO maps LDAP groups to IAM policies.
Supports DN-based and group-based access control.

Threat Model Summary¶

Threat	Mitigation
Unauthorized S3 access	IAM policies, bucket policies, access key scoping
Data exposure at rest	SSE-S3, SSE-KMS, or SSE-C encryption
Key compromise	KES key rotation, KMS-managed key lifecycle
Network interception	TLS on all endpoints; mTLS for KES communication
Credential leakage	STS temporary credentials with short TTLs
Privilege escalation	Policy variable scoping, OIDC claim-based policies
Missing audit trail	Webhook audit logging for all API operations
Replay attacks	AWS Signature V4 with timestamp validation