IAM and STS

MinIO's identity layer covers users, groups, service accounts, policies, and external identity providers, plus AWS-style STS endpoints for issuing temporary credentials. The runtime entry point is cmd/iam.go; persistence is pluggable.

Purpose

• Authenticate every request that isn't anonymous.
• Authorise it against attached policies (account-level + bucket-level + service-account inline).
• Bridge external IDPs (LDAP, OpenID) into the same policy model.
• Hand out short-lived credentials (STS).

Directory layout

cmd/
├── iam.go                          # Top-level IAM coordinator
├── iam-store.go                    # In-memory store + dispatch to backends (huge file)
├── iam-object-store.go             # Persist to the object store itself
├── iam-etcd-store.go               # Persist to etcd
├── auth-handler.go                 # Auth dispatch from HTTP layer
├── jwt.go                          # Console JWT issuance and verification
├── sts-handlers.go                 # STS endpoints (AssumeRole*)
├── sts-datatypes.go, sts-errors.go
├── stserrorcode_string.go
├── admin-handlers-users.go         # /minio/admin/v3 IAM endpoints
├── admin-handlers-idp-config.go
├── admin-handlers-idp-ldap.go
├── admin-handlers-idp-openid.go
└── user-provider-utils.go
internal/config/identity/
├── ldap/                           # LDAP IDP config + auth
├── openid/                         # OIDC IDP config + auth
├── plugin/                         # AuthN plugin shim
└── tls/                            # mTLS-as-identity
internal/config/policy/
├── opa/                            # External OPA evaluation (legacy)
└── plugin/                         # Authorization plugin shim

Key abstractions

Symbol	File	What it is
IAMSys	cmd/iam.go	The cluster-wide IAM coordinator.
IAMStorageAPI	cmd/iam-store.go	Backend-agnostic persistence interface.
IAMObjectStore	cmd/iam-object-store.go	Backend that stores IAM as objects on the cluster.
IAMEtcdStore	cmd/iam-etcd-store.go	Backend that stores IAM in etcd.
madmin.UserInfo, madmin.AddOrUpdateUserReq	external madmin-go	Wire types mc admin uses.
policy.Policy	pkg/v3/policy	The IAM policy AST + evaluator.
iampolicy.Args	pkg/v3/policy	Arguments passed to Policy.IsAllowed(...).

How it works

graph LR
    REQ[HTTP request] --> AUTH[auth-handler]
    AUTH --> IAM[IAMSys]
    IAM --> POL[Policy evaluation]
    POL --> ALLOW{allowed?}
    ALLOW -- yes --> H[Handler]
    ALLOW -- no --> ERR[AccessDenied]
    IAM --> STORE[IAMStorageAPI]
    STORE --> OBJ[Object store backend]
    STORE --> ETCD[etcd backend]
    AUTH --> STS[STS endpoints]
    STS --> LDAP[LDAP IDP]
    STS --> OIDC[OpenID IDP]
    STS --> CERT[mTLS IDP]

Identity sources

• Local users. Created via mc admin user add. Stored under .minio.sys/iam/users/.
• Service accounts. Long-lived credentials owned by a parent identity. They can carry an inline policy that further restricts the parent's permissions.
• STS-issued credentials. Short-lived; carry a session token and an embedded policy.
• External LDAP / OpenID identities. Mapped to local policies via group membership claims.
• mTLS / certificate identities. SPIFFE-style identities turned into STS credentials by internal/config/identity/tls/.

Policy evaluation

Policies are JSON documents in the IAM-policy dialect (pkg/v3/policy). IAMSys.IsAllowed aggregates:

1. Effective policies for the calling identity (account + groups).
2. Service-account inline policy (if any).
3. STS session policy (if any).
4. Bucket policy (cmd/bucket-policy.go).

The first matching Deny short-circuits; otherwise the request needs at least one matching Allow across the union.

STS endpoints

Routes mounted directly in cmd/sts-handlers.go:

Endpoint	Use
POST /?Action=AssumeRole	Native (root or user) impersonation.
POST /?Action=AssumeRoleWithLDAPIdentity	LDAP login → temp credentials.
POST /?Action=AssumeRoleWithWebIdentity	OIDC ID token → temp credentials.
POST /?Action=AssumeRoleWithClientGrants	OAuth2 client-credentials flow.
POST /?Action=AssumeRoleWithCertificate	mTLS-presented certificate → temp credentials.
POST /?Action=AssumeRoleWithCustomToken	Plug-in IdP.
POST /?Action=GetSessionToken	Self-issued token.

Issued credentials carry an embedded session policy (defaulting to the parent's effective policy) and an expiry. They are signed with the cluster's root key so peers accept them without an extra round trip.

Persistence and propagation

IAMStorageAPI writes to whichever backend is configured (object store by default, etcd if configured). Changes are propagated to peers via the peer REST (cmd/peer-rest-server.go); each peer reloads the affected portion of iam-store rather than the whole tree.

The store layer guards against thundering-herd reloads with a refresh lock and uses internal/lock/ filesystem locks while writing the iam.json files on the object store.

Identity provider configuration

External IDPs are described in internal/config/identity/:

• ldap/ — server URI, base DN, bind DN, group/user search filters, lookup vs. attribute-based.
• openid/ — issuer URL, client id/secret, scopes, claim mappings.
• tls/ — accepted CAs and certificate-to-policy mapping.
• plugin/ — generic external auth plugin (HTTP webhook).

Multiple OpenID providers can be configured at once; LDAP is currently single-provider.

Integration points

• Called by cmd/auth-handler.go for every request.
• Read by every S3 verb to build the authorisation arguments.
• Surfaces metrics in cmd/metrics-v3-cluster-iam.go.
• Cluster-to-cluster sync is handled by Site replication.

Entry points for modification

• New identity provider. Add a config block under internal/config/identity/<name>/, register it with cmd/iam.go, and either return STS credentials or feed an existing STS handler.
• Custom policy logic. Extend pkg/v3/policy (out of tree). For project-local hooks use the policy plugin in internal/config/policy/plugin/.
• New admin endpoint. Extend cmd/admin-handlers-users.go and the matching madmin-go client.