Documentation

Configure MinIO for Authentication using OpenID

Overview

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 Tenant to use an external OIDC provider.

  • Accessing the Tenant Console using OIDC Credentials.

  • Using the MinIO AssumeRoleWithWebIdentity Security 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.

Prerequisites

MinIO Kubernetes Operator and Plugin

Ensure your target Kubernetes cluster has a valid and working installation of the MinIO Kubernetes Operator. The host machine from which you perform the procedure should have a matching installation of the MinIO Kubernetes Plugin

This documentation assumes the latest stable Operator and Plugin version 5.0.14.

OpenID-Connect (OIDC) Compatible IDentity Provider

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.

  • For OIDC services within the same Kubernetes cluster as the MinIO Tenant, you can use Kubernetes service names to allow the MinIO Tenant to establish connectivity to the OIDC service.

  • For OIDC services external to the Kubernetes cluster, you must ensure the cluster supports routing communications between Kubernetes services and pods and the external network. This may require configuration or deployment of additional Kubernetes network components and/or enabling access to the public internet.

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.

MinIO Tenant

This procedure assumes your Kubernetes cluster has sufficient resources to deploy a new MinIO Tenant.

You can also use this procedure as guidance for modifying an existing MinIO Tenant to enable OIDC Identity Management.

Deploy MinIO Tenant with OpenID Connect Identity Management

1) Access the Operator Console

Use the kubectl minio proxy command to temporarily forward traffic between the local host machine and the MinIO Operator Console:

kubectl minio proxy

The command returns output similar to the following:

Starting port forward of the Console UI.

To connect open a browser and go to http://localhost:9001

Current JWT to login: TOKEN

Open your browser to the specified URL and enter the JWT Token into the login page. You should see the Tenants page:

MinIO Operator Console

Click the + Create Tenant to start creating a MinIO Tenant.

If you are modifying an existing Tenant, select that Tenant from the list. The following steps reference the necessary sections and configuration settings for existing Tenants.

2) Complete the Identity Provider Section

To enable external identity management with an OIDC select the Identity Provider section. You can then change the radio button to OIDC to display the configuration settings.

MinIO Operator Console - Create a Tenant - External Identity Provider Section - OpenID

An asterisk * marks required fields. The following table provides general guidance for those fields:

Field

Description

Configuration URL

The hostname of the OpenID .well-known/openid-configuration file.

Client ID
Secret ID

The Client and Secret ID MinIO uses when authenticating OIDC user credentials against OIDC service.

Claim Name

The OIDC Claim MinIO uses for identifying the policies to attach to the authenticated user.

Once you complete the section, you can finish any other required sections of Tenant Deployment.

3) Assign Policies to OIDC Users

MinIO by default assigns no policies to OIDC users. MinIO uses the specified user Claim to identify one or more policies to attach to the authenticated user. If the Claim is empty or specifies policies which do not exist on the deployment, the authenticated user has no permissions on the Tenant.

The following example assumes an existing alias configured for the MinIO Tenant.

Consider the following example policy that grants general S3 API access on only the data bucket:

{
   "Version": "2012-10-17",
   "Statement": [
      {
         "Effect": "Allow",
         "Action": [
            "s3:*"
         ],
         "Resource": [
            "arn:aws:s3:::data",
            "arn:aws:s3:::data/*"
         ]
      }
   ]
}

Use the mc admin policy create command to create a policy for use by an OIDC user:

mc admin policy create minio-tenant datareadonly /path/to/datareadonly.json

MinIO attaches the datareadonly policy to any authenticated OIDC user with datareadonly included in the configured claim.

See OpenID Connect Access Management for more information on access control with OIDC users and groups.

4) Use the MinIO Tenant Console to Log In with OIDC Credentials

The MinIO Console supports the full workflow of authenticating to the OIDC provider, generating temporary credentials using the MinIO AssumeRoleWithLDAPIdentity Security Token Service (STS) endpoint, and logging the user into the MinIO deployment.

See the Deploy MinIO Tenant: Access the Tenant’s MinIO Console for instructions on accessing the Tenant Console.

If the OIDC configuration succeeded, the Console displays a button to login with OIDC credentials.

Enter the user’s OIDC credentials and log in to access the Console.

Once logged in, you can perform any action for which the authenticated user is authorized.

You can also create access keys for supporting applications which must perform operations on MinIO. Access Keys are long-lived credentials which inherit their privileges from the parent user. The parent user can further restrict those privileges while creating the access keys.

5) Generate S3-Compatible Temporary Credentials using OIDC Credentials

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
  • Replace minio.example.net with the hostname or URL of the MinIO Tenant service.

  • Replace the TOKEN with the JWT token returned in the previous step.

  • Replace the DurationSeconds with the duration in seconds until the temporary credentials expire. The example above specifies a period of 86400 seconds, or 24 hours.

  • Replace the Policy with 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.