External identity and SSO

MinIO IAM is fed by three kinds of identity sources: the local IAM store, an LDAP directory, and one or more OpenID Connect providers. This page summarises how a request from "alice@example.com" turns into an authorised S3 call.

The flow

sequenceDiagram
    participant U as User
    participant IDP as External IDP
    participant STS as MinIO STS
    participant IAM as MinIO IAM
    participant H as S3 handler

    U->>IDP: Login (LDAP bind / OIDC redirect / mTLS handshake)
    IDP-->>U: Token / cert
    U->>STS: AssumeRoleWith*
    STS->>IDP: Validate token / cert
    STS->>IAM: Map identity → policy
    STS-->>U: Temporary credentials (AK/SK/Session token)
    U->>H: Signed S3 request
    H->>IAM: Resolve session policy
    IAM-->>H: Allow / Deny
    H-->>U: Result

The STS endpoints live in cmd/sts-handlers.go; the per-IDP validators live under internal/config/identity/.

LDAP

internal/config/identity/ldap/ does:

• A bind to a configured LDAP server using a search-bind or simple-bind flow.
• A user attribute lookup (typically uid or userPrincipalName).
• A group lookup that maps memberships to MinIO policy names.

AssumeRoleWithLDAPIdentity is the STS endpoint that wraps it. Sample env vars: MINIO_IDENTITY_LDAP_SERVER_ADDR, MINIO_IDENTITY_LDAP_USER_DN_SEARCH_FILTER, MINIO_IDENTITY_LDAP_GROUP_SEARCH_FILTER.

The console can also log a user in via LDAP and persist a console JWT (see cmd/jwt.go).

OpenID Connect

internal/config/identity/openid/ supports any OIDC provider (Auth0, Okta, Keycloak, AzureAD, Cognito, ...). It does:

• Discovery via the issuer URL.
• ID-token validation (signature, audience, expiry).
• Claim → policy mapping. The default claim is policy; can be overridden.
• Multiple providers configured at once with distinct prefixes.

AssumeRoleWithWebIdentity is the STS endpoint.

Certificate / mTLS

internal/config/identity/tls/ accepts client certificates issued by configured CAs and turns them into STS credentials. Used in zero-trust deployments where workloads already have SPIFFE-style identities.

AssumeRoleWithCertificate is the STS endpoint.

Plugin

internal/config/identity/plugin/ lets an operator wire in an HTTP webhook that authenticates a custom token. The webhook returns a policy name; MinIO issues STS credentials. Useful for proprietary auth schemes.

AssumeRoleWithCustomToken is the STS endpoint.

Local IAM

For users created via mc admin user add, the path is simpler:

• cmd/auth-handler.go validates the SigV4 signature using the secret key from cmd/iam-store.go.
• The user's effective policy is the union of attached policies + group policies.
• Service accounts add an inline policy that further restricts the parent.

Policy

pkg/v3/policy (out of tree) is the IAM-policy AST. cmd/iam.go.IsAllowed walks the AST against the request's Args.

Bucket policies (cmd/bucket-policy.go) layer on top: they grant access to a bucket from any account; the AND of bucket policy and IAM policy must allow the action.

Configuration

Subsystem	Config dir	Sample env var
LDAP	internal/config/identity/ldap/	MINIO_IDENTITY_LDAP_SERVER_ADDR
OpenID	internal/config/identity/openid/	MINIO_IDENTITY_OPENID_CONFIG_URL
mTLS	internal/config/identity/tls/	MINIO_IDENTITY_TLS_CERT_DIR
Plugin	internal/config/identity/plugin/	MINIO_IDENTITY_PLUGIN_URL

Test entry points

• make test-iam — Go tests TestIAM* cover LDAP/OIDC mapping with etcd backends.
• make test-iam-import-with-openid — config import with OpenID.
• make test-site-replication-{ldap,oidc,minio} — multi-site IAM consistency.

Where to start reading

• cmd/sts-handlers.go
• cmd/iam.go, cmd/iam-store.go
• internal/config/identity/<x>/
• cmd/admin-handlers-idp-{ldap,openid,config}.go

See IAM and STS for the runtime view.