Documentation

Documentation

External Identity Management

MinIO supports offloading identity management onto one of the following supported IDentity Providers (IDP):

The external IDP must have at least one configured user identity with the required policy claims. If no such user exists, the MinIO server is effectively inaccessible outside of using the root user.

OpenID Connect (OIDC)

MinIO supports using an OpenID Connect (OIDC) compatible IDentity Provider (IDP) such as Okta, KeyCloak, Dex, Google, or Facebook for external management of user identities. Configuring an external IDP enables Single-Sign On workflows, where applications authenticate against the external IDP before accessing MinIO.

MinIO uses Policy Based Access Control (PBAC) to define the actions and resources to which an authenticated user has access. MinIO supports creating and managing policies which an externally managed user can claim.

For identities managed by the external OpenID Connect (OIDC) compatible provider, MinIO uses a JSON Web Token claim to identify the policy to assign to the authenticated user.

MinIO by default looks for a policy claim and reads a list of one or more policies to assign. MinIO attempts to match existing policies to those specified in the JWT claim. If none of the specified policies exist on the MinIO deployment, MinIO denies authorization for any and all operations issued by that user. For example, consider a claim with the following key-value assignment:

policy="readwrite_data,read_analytics,read_logs"

The specified policy claim directs MinIO to attach the policies with names matching readwrite_data, read_analytics, and read_logs to the authenticated user.

You can set a custom policy claim using the MINIO_IDENTITY_OPENID_CLAIM_NAME environment variable or by using mc admin config set to set the identity_openid claim_name setting.

See OpenID Connect Access Management for more information on mapping MinIO policies to an OIDC-managed identity.

You can use a JWT Debugging tool to decode the returned JWT token and validate that the user attributes include the specified claim. See RFC 7519: JWT Claim for more information on JWT claims. Defer to the documentation for your preferred OIDC provider for instructions on configuring user claims.

Active Directory / LDAP

MinIO supports using an Active Directory or LDAP (AD/LDAP) service for external management of user identities. Configuring an external IDentity Provider (IDP) enables Single-Sign On (SSO) workflows, where applications authenticate against the external IDP before accessing MinIO.

Querying the Active Directory / LDAP Service

MinIO queries the configured Active Directory / LDAP server to verify the credentials specified by the application and optionally return a list of groups in which the user has membership. MinIO supports two modes for performing these queries:

  • Lookup-Bind Mode - Use a special read-only account for querying the LDAP server.

  • Username-Bind Mode - Use the credentials specified by the application to login to the LDAP server.

MinIO recommends using Lookup-Bind mode as the preferred method for verifying AD/LDAP credentials. Username-Bind mode is a legacy method retained for backwards compatibility only.

Lookup-Bind Mode

In Lookup-Bind mode, MinIO uses a read-only AD/LDAP account with the minimum privileges required to authenticate to the AD/LDAP server and perform user and group lookups.

The following tabs provide a reference of the environment variables and configuration settings required for enabling Lookup-Bind mode.

See the identity_ldap reference documentation for more information on these settings. The Configure MinIO for Authentication using OpenID tutorial includes complete instructions on setting these variables.

Lookup-Bind is incompatible and mutually exclusive with Username-Bind Mode.

Username-Bind Mode

In Username-Bind mode, MinIO uses the AD/LDAP credentials provided by the client attempting authentication to login to the AD/LDAP server and perform and group lookups.

Username-Bind mode is preserved for compatibility only. MinIO recommends using Lookup-Bind Mode wherever possible.

The following tabs provide a reference of the environment variables and configuration settings required for enabling Username-Bind mode.

See the Active Directory / LDAP Identity Management reference documentation for more information on this variable.

See the identity_ldap reference documentation for more information on this setting.

Username-bind is incompatible and mutually exclusive with Lookup-Bind Mode.

Access Control for AD/LDAP-Managed Identities

MinIO uses Policy Based Access Control (PBAC) to define the actions and resources to which an authenticated user has access. When using an Active Directory/LDAP server for identity management (authentication), MinIO maintains control over access (authorization) through PBAC.

When a user successfully authenticates to MinIO using their AD/LDAP credentials, MinIO searches for all policies which are explicitly associated to that user’s Distinguished Name (DN). Specifically, the policy must be assigned to a user with a matching DN using the mc admin policy set command.

MinIO also supports querying for the user’s AD/LDAP group membership. MinIO attempts to match existing policies to the DN for each of the user’s groups. The authenticated users complete set of permissions consists of its explicitly assigned and group-inherited policies. See Group Lookup for more information.

MinIO uses deny-by-default behavior where a user with no explicitly assigned or group-inherited policies cannot access any resource on the MinIO deployment.

MinIO provides built-in policies for basic access control. You can create new policies using the mc admin policy command.

Group Lookup

MinIO supports querying the Active Directory / LDAP server for a list of groups in which the authenticated user has membership. MinIO attempts to match existing policies to each group DN and assigns each matching policy to the authenticated user.

The following tabs provide a reference of the environment variables and configuration settings required for enabling group lookups:

See the Active Directory / LDAP Identity Management reference documentation for more information on these variables. The Configure MinIO for Authentication using Active Directory / LDAP tutorial includes complete instructions on setting these values.

See the identity_ldap reference documentation for more information on these settings. The Configure MinIO for Authentication using Active Directory / LDAP tutorial includes complete instructions on setting these variables.