mirror of
https://github.com/pgsty/minio.git
synced 2026-07-23 06:00:24 +03:00
docs: refresh security docs and fork references
Update the STS, security, select, and Docker documentation to reflect the recent hardening work, including LDAP STS throttling details, OIDC JWT verification changes, and the new pgsty-specific security policy and advisory index. Rewrite repository and raw-document links that still pointed at minio/minio so the docs consistently reference pgsty/minio instead. The core idea is to keep the documentation aligned with the fork's actual security behavior, ownership, and upgrade guidance without mixing in unrelated code changes.
This commit is contained in:
Feng Ruohang
+8
-8
@@ -15,17 +15,17 @@ Following are advantages for using temporary credentials:
|
||||
|
||||
| AuthN | Description |
|
||||
| :---------------------- | ------------------------------------------ |
|
||||
| [**WebIdentity**](https://github.com/minio/minio/blob/master/docs/sts/web-identity.md) | Let users request temporary credentials using any OpenID(OIDC) compatible web identity providers such as KeyCloak, Dex, Facebook, Google etc. |
|
||||
| [**AD/LDAP**](https://github.com/minio/minio/blob/master/docs/sts/ldap.md) | Let AD/LDAP users request temporary credentials using AD/LDAP username and password. |
|
||||
| [**AssumeRole**](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md) | Let MinIO users request temporary credentials using user access and secret keys. |
|
||||
| [**WebIdentity**](https://github.com/pgsty/minio/blob/master/docs/sts/web-identity.md) | Let users request temporary credentials using any OpenID(OIDC) compatible web identity providers such as KeyCloak, Dex, Facebook, Google etc. |
|
||||
| [**AD/LDAP**](https://github.com/pgsty/minio/blob/master/docs/sts/ldap.md) | Let AD/LDAP users request temporary credentials using AD/LDAP username and password. |
|
||||
| [**AssumeRole**](https://github.com/pgsty/minio/blob/master/docs/sts/assume-role.md) | Let MinIO users request temporary credentials using user access and secret keys. |
|
||||
|
||||
### Understanding JWT Claims
|
||||
|
||||
> NOTE: JWT claims are only meant for WebIdentity and ClientGrants.
|
||||
> AssumeRole or LDAP users can skip the entire portion and directly visit one of the links below.
|
||||
>
|
||||
> - [**AssumeRole**](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md)
|
||||
> - [**AD/LDAP**](https://github.com/minio/minio/blob/master/docs/sts/ldap.md)
|
||||
> - [**AssumeRole**](https://github.com/pgsty/minio/blob/master/docs/sts/assume-role.md)
|
||||
> - [**AD/LDAP**](https://github.com/pgsty/minio/blob/master/docs/sts/ldap.md)
|
||||
|
||||
The id_token received is a signed JSON Web Token (JWT). Use a JWT decoder to decode the id_token to access the payload of the token that includes following JWT claims, `policy` claim is mandatory and should be present as part of your JWT claim. Without this claim the generated credentials will not have access to any resources on the server, using these credentials application would receive 'Access Denied' errors.
|
||||
|
||||
@@ -37,12 +37,12 @@ The id_token received is a signed JSON Web Token (JWT). Use a JWT decoder to dec
|
||||
|
||||
In this document we will explain in detail on how to configure all the prerequisites.
|
||||
|
||||
> NOTE: If you are interested in AssumeRole API only, skip to [here](https://github.com/minio/minio/blob/master/docs/sts/assume-role.md)
|
||||
> NOTE: If you are interested in AssumeRole API only, skip to [here](https://github.com/pgsty/minio/blob/master/docs/sts/assume-role.md)
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- [Configuring keycloak](https://github.com/minio/minio/blob/master/docs/sts/keycloak.md) or [Configuring Casdoor](https://github.com/minio/minio/blob/master/docs/sts/casdoor.md)
|
||||
- [Configuring etcd](https://github.com/minio/minio/blob/master/docs/sts/etcd.md)
|
||||
- [Configuring keycloak](https://github.com/pgsty/minio/blob/master/docs/sts/keycloak.md) or [Configuring Casdoor](https://github.com/pgsty/minio/blob/master/docs/sts/casdoor.md)
|
||||
- [Configuring etcd](https://github.com/pgsty/minio/blob/master/docs/sts/etcd.md)
|
||||
|
||||
### Setup MinIO with Identity Provider
|
||||
|
||||
|
||||
@@ -6,6 +6,8 @@ Returns a set of temporary security credentials for applications/clients who hav
|
||||
|
||||
Calling AssumeRoleWithClientGrants does not require the use of MinIO default credentials. Therefore, client application can be distributed that requests temporary security credentials without including MinIO default credentials. Instead, the identity of the caller is validated by using a JWT access token from the identity provider. The temporary security credentials returned by this API consists of an access key, a secret key, and a security token. Applications can use these temporary security credentials to sign calls to MinIO API operations.
|
||||
|
||||
**Breaking change (`CVE-2026-33322`)**: releases after `RELEASE.2026-03-25T00-00-00Z` validate the JWT access token with the provider JWKS endpoint advertised by the configured OpenID discovery document. In practice, MinIO currently accepts the RSA PKCS#1 v1.5 and ECDSA families already implemented in the verifier (`RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, plus the existing `RS3*` and `ES3*` aliases). HMAC-signed tokens such as `HS256`, `HS384`, and `HS512` are rejected. Algorithms such as `PS256` and `EdDSA` are not currently supported. `MINIO_IDENTITY_OPENID_CLIENT_SECRET` is used for OpenID/OAuth client interactions only and is not used as a JWT verification key. If your provider previously issued HMAC-signed access tokens for this flow, reconfigure it to publish RSA or ECDSA signing keys through JWKS before upgrading.
|
||||
|
||||
By default, the temporary security credentials created by AssumeRoleWithClientGrants last for one hour. However, use the optional DurationSeconds parameter to specify the duration of the credentials. This value varies from 900 seconds (15 minutes) up to the maximum session duration of 365 days.
|
||||
|
||||
## API Request Parameters
|
||||
@@ -95,7 +97,7 @@ minio server /mnt/export
|
||||
```
|
||||
|
||||
Testing with an example
|
||||
> Obtaining client ID and secrets follow [Keycloak configuring documentation](https://github.com/minio/minio/blob/master/docs/sts/keycloak.md)
|
||||
> Obtaining client ID and secrets follow [Keycloak configuring documentation](https://github.com/pgsty/minio/blob/master/docs/sts/keycloak.md)
|
||||
|
||||
```
|
||||
$ go run client-grants.go -cid PoEgXP6uVO45IsENRngDXj5Au5Ya -csec eKsw6z8CtOJVBtrOWvhRWL4TUCga
|
||||
|
||||
+2
-2
@@ -50,7 +50,7 @@ NOTE: If `etcd` is configured with `Client-to-server authentication with HTTPS c
|
||||
|
||||
Once etcd is configured, **any STS configuration** will work including Client Grants, Web Identity or AD/LDAP.
|
||||
|
||||
For example, you can configure STS with Client Grants (KeyCloak) using the guides at [MinIO STS Quickstart Guide](https://docs.min.io/community/minio-object-store/developers/security-token-service.html) and [KeyCloak Configuration Guide](https://github.com/minio/minio/blob/master/docs/sts/keycloak.md). Once this is done, STS credentials can be generated:
|
||||
For example, you can configure STS with Client Grants (KeyCloak) using the guides at [MinIO STS Quickstart Guide](https://docs.min.io/community/minio-object-store/developers/security-token-service.html) and [KeyCloak Configuration Guide](https://github.com/pgsty/minio/blob/master/docs/sts/keycloak.md). Once this is done, STS credentials can be generated:
|
||||
|
||||
```
|
||||
go run client-grants.go -cid PoEgXP6uVO45IsENRngDXj5Au5Ya -csec eKsw6z8CtOJVBtrOWvhRWL4TUCga
|
||||
@@ -64,7 +64,7 @@ go run client-grants.go -cid PoEgXP6uVO45IsENRngDXj5Au5Ya -csec eKsw6z8CtOJVBtrO
|
||||
}
|
||||
```
|
||||
|
||||
These credentials can now be used to perform MinIO API operations, these credentials automatically expire in 1hr. To understand more about credential expiry duration and client grants STS API read further [here](https://github.com/minio/minio/blob/master/docs/sts/client-grants.md).
|
||||
These credentials can now be used to perform MinIO API operations, these credentials automatically expire in 1hr. To understand more about credential expiry duration and client grants STS API read further [here](https://github.com/pgsty/minio/blob/master/docs/sts/client-grants.md).
|
||||
|
||||
## Explore Further
|
||||
|
||||
|
||||
+43
-16
@@ -46,7 +46,7 @@ MINIO_IDENTITY_LDAP_GROUP_SEARCH_BASE_DN (list) ";" separated list of gr
|
||||
MINIO_IDENTITY_LDAP_TLS_SKIP_VERIFY (on|off) trust server TLS without verification (default: 'off')
|
||||
MINIO_IDENTITY_LDAP_SERVER_INSECURE (on|off) allow plain text connection to AD/LDAP server (default: 'off')
|
||||
MINIO_IDENTITY_LDAP_SERVER_STARTTLS (on|off) use StartTLS connection to AD/LDAP server (default: 'off')
|
||||
MINIO_IDENTITY_LDAP_STS_TRUSTED_PROXIES (list) "," separated list of trusted proxy IPs or CIDRs whose forwarded client IP headers may be used for LDAP STS rate limiting
|
||||
MINIO_IDENTITY_LDAP_STS_TRUSTED_PROXIES (list) comma/semicolon/whitespace-separated list of trusted proxy IPs or CIDRs whose forwarded client IP headers may be used for LDAP STS rate limiting
|
||||
MINIO_IDENTITY_LDAP_COMMENT (sentence) optionally add a comment to this setting
|
||||
```
|
||||
|
||||
@@ -62,20 +62,6 @@ MINIO_IDENTITY_LDAP_SERVER_INSECURE (on|off) allow plain text connect
|
||||
MINIO_IDENTITY_LDAP_SERVER_STARTTLS (on|off) use StartTLS connection to AD/LDAP server, defaults to "off"
|
||||
```
|
||||
|
||||
### LDAP STS rate limiting behind trusted proxies
|
||||
|
||||
LDAP STS login throttling is keyed by the socket peer address by default. This is the safe default because MinIO does **not** trust `X-Forwarded-For`, `X-Real-IP`, or `Forwarded` headers for this security-sensitive rate-limit key unless you opt in explicitly.
|
||||
|
||||
If MinIO is deployed behind a trusted reverse proxy, load balancer, or API gateway and you want LDAP STS throttling to bucket by the forwarded client IP instead of the proxy peer address, configure:
|
||||
|
||||
```
|
||||
MINIO_IDENTITY_LDAP_STS_TRUSTED_PROXIES (list) "," separated list of trusted proxy IPs or CIDRs
|
||||
```
|
||||
|
||||
Only requests whose peer address matches this allowlist may supply forwarded client IP headers for LDAP STS rate limiting. Requests from all other peers continue to use the peer address directly.
|
||||
|
||||
For trusted-proxy deployments, prefer setting a clean single-value `X-Real-IP` header. If you rely on `X-Forwarded-For`, make sure the proxy strips or overwrites any inbound forwarding headers instead of appending to a client-supplied value. In nginx, prefer `$remote_addr` for the trusted client IP header; `proxy_add_x_forwarded_for` appends and is not suitable unless you first clear inbound forwarding headers.
|
||||
|
||||
The server address variable is _required_. TLS is assumed to be on by default. The port in the server address is optional and defaults to 636 if not provided.
|
||||
|
||||
**MinIO sends LDAP credentials to the LDAP server for validation. So we _strongly recommend_ to use MinIO with AD/LDAP server over TLS or StartTLS _only_. Using plain-text connection between MinIO and LDAP server means _credentials can be compromised_ by anyone listening to network traffic.**
|
||||
@@ -96,6 +82,39 @@ With the default (empty) value for `srv_record_name`, MinIO **will not** perform
|
||||
|
||||
The value of `srv_record_name` does not affect any TLS settings - they must be configured with their own parameters.
|
||||
|
||||
### LDAP STS rate limiting
|
||||
|
||||
LDAP STS rate limiting is enforced before each LDAP bind. Requests are tracked independently by source IP and by normalized username. A login attempt is throttled when either bucket is exhausted.
|
||||
|
||||
By default, the source IP used for this key is the socket peer address. This is the safe default because MinIO does **not** trust `X-Forwarded-For`, `X-Real-IP`, or `Forwarded` headers for this security-sensitive rate-limit key unless you opt in explicitly.
|
||||
|
||||
Each login attempt reserves capacity for the duration of the LDAP bind. Successful logins and LDAP infrastructure failures refund that reservation. Only real authentication failures permanently consume tokens. Concurrent bursts above the burst capacity can still receive `429` responses even if those in-flight requests later succeed.
|
||||
|
||||
| Behavior | Value |
|
||||
| :-- | :-- |
|
||||
| Bucket keys | Source IP and normalized username, enforced independently |
|
||||
| Burst capacity | 10 attempts per bucket |
|
||||
| Refill rate | 1 token every 6 seconds, about 10 attempts per minute per bucket |
|
||||
| Reservation lifetime | Held for the duration of the LDAP bind |
|
||||
| Idle entry cleanup | Bucket state is removed after 15 minutes without activity |
|
||||
| Throttled response | HTTP `429`, STS code `ThrottlingException`, `Retry-After: 6` |
|
||||
| Scope | Per-node, in-memory, not cluster-wide |
|
||||
| Configurability | Not currently configurable |
|
||||
|
||||
In a multi-node deployment behind a load balancer, each MinIO node tracks its own buckets. The effective aggregate budget therefore depends on how requests are distributed across nodes.
|
||||
|
||||
#### Trusted proxies
|
||||
|
||||
If MinIO is deployed behind a trusted reverse proxy, load balancer, or API gateway and you want LDAP STS throttling to bucket by the forwarded client IP instead of the proxy peer address, configure:
|
||||
|
||||
```
|
||||
MINIO_IDENTITY_LDAP_STS_TRUSTED_PROXIES (list) comma/semicolon/whitespace-separated list of trusted proxy IPs or CIDRs
|
||||
```
|
||||
|
||||
Only requests whose peer address matches this allowlist may supply forwarded client IP headers for LDAP STS rate limiting. Requests from all other peers continue to use the peer address directly.
|
||||
|
||||
For trusted-proxy deployments, prefer setting a clean single-value `X-Real-IP` header. If you rely on `X-Forwarded-For`, make sure the proxy strips or overwrites any inbound forwarding headers instead of appending to a client-supplied value. In nginx, prefer `$remote_addr` for the trusted client IP header; `proxy_add_x_forwarded_for` appends and is not suitable unless you first clear inbound forwarding headers.
|
||||
|
||||
### Lookup-Bind
|
||||
|
||||
A low-privilege read-only LDAP service account is configured in the MinIO server by providing the account's Distinguished Name (DN) and password. This service account is used to perform directory lookups as needed.
|
||||
@@ -276,6 +295,14 @@ XML response for this API is similar to [AWS STS AssumeRoleWithWebIdentity](http
|
||||
|
||||
XML error response for this API is similar to [AWS STS AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html#API_AssumeRoleWithWebIdentity_Errors)
|
||||
|
||||
Authentication failures caused by unknown users and invalid passwords intentionally return the same external STS error response to prevent username enumeration via response differentiation (`CVE-2026-33419`).
|
||||
|
||||
| Condition | HTTP status | STS code | Notes |
|
||||
| :-- | :-- | :-- | :-- |
|
||||
| Unknown user or invalid password | `400` | `InvalidParameterValue` | Same response for both cases to prevent username enumeration |
|
||||
| LDAP backend, network, or other infrastructure failure | `500` | `InternalError` | Returned as an upstream/internal failure and logged server-side |
|
||||
| Rate limit exhausted | `429` | `ThrottlingException` | Includes a `Retry-After` header |
|
||||
|
||||
## Sample `POST` Request
|
||||
|
||||
```
|
||||
@@ -318,7 +345,7 @@ export MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER='(&(objectclass=groupOfNames)(mem
|
||||
minio server ~/test
|
||||
```
|
||||
|
||||
You can make sure it works appropriately using our [example program](https://raw.githubusercontent.com/minio/minio/master/docs/sts/ldap.go):
|
||||
You can make sure it works appropriately using our [example program](https://raw.githubusercontent.com/pgsty/minio/master/docs/sts/ldap.go):
|
||||
|
||||
```
|
||||
$ go run ldap.go -u foouser -p foopassword
|
||||
|
||||
@@ -6,6 +6,8 @@ MinIO supports the standard AssumeRoleWithWebIdentity STS API to enable integrat
|
||||
|
||||
Calling AssumeRoleWithWebIdentity does not require the use of MinIO root or IAM credentials. Therefore, you can distribute an application (for example, on mobile devices) that requests temporary security credentials without including MinIO long lasting credentials in the application. Instead, the identity of the caller is validated by using a JWT id_token from the web identity provider. The temporary security credentials returned by this API consists of an access key, a secret key, and a security token. Applications can use these temporary security credentials to sign calls to MinIO API operations.
|
||||
|
||||
**Breaking change (`CVE-2026-33322`)**: releases after `RELEASE.2026-03-25T00-00-00Z` validate the `id_token` with the provider JWKS endpoint advertised by the OpenID discovery document at `MINIO_IDENTITY_OPENID_CONFIG_URL`. In practice, MinIO currently accepts the RSA PKCS#1 v1.5 and ECDSA families already implemented in the verifier (`RS256`, `RS384`, `RS512`, `ES256`, `ES384`, `ES512`, plus the existing `RS3*` and `ES3*` aliases). HMAC-signed tokens such as `HS256`, `HS384`, and `HS512` are rejected. Algorithms such as `PS256` and `EdDSA` are not currently supported. `MINIO_IDENTITY_OPENID_CLIENT_SECRET` is used for OpenID/OAuth client interactions only and is not used as a JWT verification key. If your provider previously issued HMAC-signed `id_token`s, reconfigure it to publish RSA or ECDSA signing keys through JWKS before upgrading.
|
||||
|
||||
By default, the temporary security credentials created by AssumeRoleWithWebIdentity last for one hour. However, the optional DurationSeconds parameter can be used to specify the validity duration of the generated credentials. This value varies from 900 seconds (15 minutes) up to the maximum session duration of 365 days.
|
||||
|
||||
## Configuring OpenID Identity Provider on MinIO
|
||||
|
||||
+1
-1
@@ -101,7 +101,7 @@ go run client-grants.go -cid PoEgXP6uVO45IsENRngDXj5Au5Ya -csec eKsw6z8CtOJVBtrO
|
||||
}
|
||||
```
|
||||
|
||||
These credentials can now be used to perform MinIO API operations, these credentials automatically expire in 1hr. To understand more about credential expiry duration and client grants STS API read further [here](https://github.com/minio/minio/blob/master/docs/sts/client-grants.md).
|
||||
These credentials can now be used to perform MinIO API operations, these credentials automatically expire in 1hr. To understand more about credential expiry duration and client grants STS API read further [here](https://github.com/pgsty/minio/blob/master/docs/sts/client-grants.md).
|
||||
|
||||
## Explore Further
|
||||
|
||||
|
||||
Reference in New Issue
Block a user