OpenID External Identity Management


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 by default denies access to all actions or resources not explicitly allowed by a user’s assigned or inherited policies. Users managed by an OIDC provider must specify the necessary policies as part of the user profile data. See Access Control for OIDC Managed Identities for more information.

See Configure MinIO for Authentication using OpenID for instructions on enabling external identity management using an OIDC compatible service.

MinIO Supports At Most One Configured IDentity Provider

Configuring an external IDP disables the MinIO internal IDP and prevents the configuration of any other external 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.

Authentication and Authorization Flow

The login flow for an application using OIDC credentials is as follows:

  1. Authenticate to the configured OIDC provider and retrieve a JSON Web Token (JWT).

    MinIO only supports the OpenID Authorization Code Flow. Authentication using Implicit Flow is not supported.

  2. Specify the JWT to the MinIO Security Token Service (STS) AssumeRoleWithWebIdentity API endpoint.

    MinIO verifies the JWT against the configured OIDC provider.

    If the JWT is valid, MinIO checks for a claim specifying a list of one or more policies to assign to the authenticated user. MinIO defaults to checking the policy claim.

  3. MinIO returns temporary credentials in the STS API response in the form of an access key, secret key, and session token. The credentials have permissions matching those policies specified in the JWT claim.

  4. Applications use the temporary credentials returned by the STS endpoint to perform authenticated S3 operations on MinIO.

MinIO provides an example Go application web-identity.go that handles the full login flow.

OIDC users can alternatively create service accounts associated to their AD/LDAP user. Service accounts are long-lived credentials which inherit their privileges from the parent user. The parent user can further restrict those privileges while creating the service account. To create a new service account, log into the MinIO Console using the OIDC-managed user credentials. From the Identity section of the left navigation, select Service Accounts followed by the Create service account + button.

Access Control for Externally Managed Identities

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:


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.

You can use a JWT Debugging tool to decode the returned JWT token and validate that the user attributes include the required claims. 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.

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

MinIO does not support using MinIO groups with OIDC. Instead, an OIDC administrator can use the configured OIDC claim to list multiple, comma-separated MinIO policies to assign to the user. The OIDC administrator can create a type of “group” assignment managed entirely within OIDC. For example, 'policy[,policy]'.