Welcome to the upcoming version of the MinIO Documentation! The content on this page is under active development and may change at any time. If you can't find what you're looking for, check our legacy documentation. Thank you for your patience.

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.

As an alternative to implementing this application flow, application owners can log into the MinIO Console using their external user credentials and create service accounts for their applications. 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.

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 assigning groups to an OIDC managed identity. Specify any and all policies to attach to the user as part of its JWT policy claim.