Table of Contents
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. The procedure on this page provides instructions for:
Configuring a MinIO cluster for an external OIDC provider.
Logging into the cluster using the MinIO Console and OIDC credentials.
Using the MinIO
AssumeRoleWithWebIdentitySecurity Token Service (STS) API to generate temporary credentials for use by applications.
This procedure is generic for OIDC compatible providers. Defer to the documentation for the OIDC provider of your choice for specific instructions or procedures on authentication and JWT retrieval.
This procedure assumes an existing OIDC provider such as Okta, KeyCloak, Dex, Google, or Facebook. Instructions on configuring these services are out of scope for this procedure.
Ensure each user identity intended for use with MinIO has the appropriate claim configured such that MinIO can associate a policy to the authenticated user. An OpenID user with no assigned policy has no permission to access any action or resource on the MinIO cluster.
This procedure assumes an existing MinIO cluster running the latest stable MinIO version. This procedure may work as expected for older versions of MinIO.
This procedure uses
mc for performing operations on the
MinIO cluster. Install
mc on a machine with network access to the cluster.
mc Installation Quickstart for instructions on
downloading and installing
This procedure assumes a configured
alias for the MinIO
You can configure the OIDC provider using either environment variables or server runtime configuration settings. Both methods require starting/restarting the MinIO deployment to apply changes. The following tabs provide a quick reference of all required and optional environment variables and configuration settings respectively:
You must restart the MinIO deployment to apply the configuration changes.
mc admin service restart command to restart the deployment.
MinIO restarts all
minio server processes associated to the
deployment at the same time. Applications may experience a brief period of
downtime during the restart process.
Consider scheduling the restart during a maintenance period to minimize interruption of services.
mc admin service restart ALIAS
ALIAS with the
alias of the deployment to
The MinIO Console supports the full workflow of authenticating to the OIDC provider, generating temporary credentials using the MinIO AssumeRoleWithWebIdentity Security Token Service (STS) endpoint, and logging the user into the MinIO deployment.
Starting in RELEASE.2021-07-08T01-15-01Z, the MinIO Console is
embedded in the MinIO server. You can access the Console by opening the root URL
for the MinIO cluster. For example,
From the Console, click BUTTON to begin the OpenID authentication flow.
Once logged in, you can perform any action for which the authenticated user is authorized.
You can also create service accounts for supporting applications which must perform operations on MinIO. 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.
MinIO requires clients authenticate using AWS Signature Version 4
protocol with support for the deprecated
Signature Version 2 protocol. Specifically, clients must present a valid access
key and secret key to access any S3 or MinIO administrative API, such as
Applications can generate temporary access credentials as-needed using the AssumeRoleWithWebIdentity Security Token Service (STS) API endpoint and the JSON Web Token (JWT) returned by the OIDC provider.
The application must provide a workflow for logging into the OIDC provider and retrieving the JSON Web Token (JWT) associated to the authentication session. Defer to the provider documentation for obtaining and parsing the JWT token after successful authentication. MinIO provides an example Go application web-identity.go with an example of managing this workflow.
Once the application retrieves the JWT token, use the
AssumeRoleWithWebIdentity endpoint to generate the temporary credentials:
POST https://minio.example.net/Action=AssumeRoleWithWebIdentity &WebIdentityToken=TOKEN &Version=2011-06-15 &DurationSeconds=86400 &Policy=Policy
TOKENwith the JWT token returned in the previous step.
DurationSecondswith the duration in seconds until the temporary credentials expire. The example above specifies a period of
86400seconds, or 24 hours.
Policywith an inline URL-encoded JSON policy that further restricts the permissions associated to the temporary credentials. Omit to use the policy associated to the OpenID user policy claim.
The API response consists of an XML document containing the access key, secret key, session token, and expiration date. Applications can use the access key and secret key to access and perform operations on MinIO.
See the AssumeRoleWithWebIdentity for reference documentation.