Design MinIO temporary credentials around session policy limits

MinIO's Security Token Service (STS) offers a secure way to manage access credentials by providing temporary keys that include an expiration and, when supported, a session policy. Rather than distributing long-lived keys that are difficult to retire, applications exchange a trusted identity for temporary credentials. This approach has several important considerations.

The STS supports various identity inputs, such as existing MinIO identities, OIDC tokens, LDAP identities, client certificates, and custom tokens. The endpoint for obtaining credentials varies depending on the identity input, but the result is always a set of access keys, secret keys, a session token, and an expiration time. Applications must use both the temporary keys and the session token together.

A common mistake is to assume that the short duration alone provides sufficient control. However, if a token requests a policy granting access to every bucket, it retains significant authority throughout its lifetime. To mitigate this risk, an inline session policy should be used to narrow the scope based on the specific needs of the workflow. This policy should define exact bucket prefixes, object operations, and conditions.

The identity mapping also plays a crucial role. Depending on the identity source, it can map to a policy using an OIDC claim, an LDAP group, a certificate subject, or a built-in user. Any change to this mapping will alter the credentials received by the application, even if the application code and STS request remain unchanged. It's essential to separate the bootstrap identity (the principal that calls STS) from the workload access.

The bootstrap path should have a narrow identity and should not be used as a general-purpose object-storage key.

When designing the credential exchange process, it's vital to start with a narrow identity and prevent the bootstrap credential from being used for general-purpose access. Workloads should receive only the temporary credentials necessary for their specific task. Each identity source should be mapped to an owner and a lifecycle, with separate failure modes for each source. A negative test should be performed for each source to ensure proper handling.

Expiration is not the same as revocation. While STS credentials do expire, some deployments also support revoking STS tokens before their expiration. Revocation is useful for offboarding, incident response, and failed deployment rollback. If revocation is available, it should be used to manage offboarding and incident response effectively. Keep a record linking the session token to the identity and policy, so an operator can identify which token to revoke.

The expiration time should be short enough to limit stale access but long enough for the workload to complete without requiring uncontrolled token renewals. If a job runs for hours, consider implementing a renewal path that re-checks identity and policy rather than simply extending the token. This renewal path should verify the identity and policy again, not just extend the token because the old one is still valid.

To ensure the design is robust, several tests should be conducted. First, request credentials with the intended policy and perform one allowed operation. Then, try different buckets, prefixes, administrative operations, and requests without the session token. Confirm that failures are due to authorization issues and not malformed requests.

Additionally, test after an identity group change to confirm that the new policy is reflected. Finally, verify the expiration timestamp in the response and the storage client's handling of an expired session. Pay particular attention to time skew between the application host and the identity provider, as a valid token at the provider may become unusable at the client if the local clock is incorrect.