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.

This page has procedures for configuring OIDC for MinIO deployments in Kubernetes and Baremetal infrastructures.

Select the tab corresponding to your infrastructure to switch between instruction sets.

Kubernetes

For MinIO Tenants deployed using the MinIO Kubernetes Operator, this procedure covers:

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.

Baremetal

For MinIO deployments on baremetal infrastructure, this procedure covers:

Configuring a MinIO cluster for an external OIDC provider.
Logging into the cluster using the MinIO Console and 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

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.

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.

Access to MinIO Cluster

Configure MinIO with OpenID External Identity Management

Kubernetes

Access the Operator Console

Temporarily forward traffic between the local host machine and the MinIO Operator Console and retrieve the JWT token for your Operator deployment. For instructions, see Configure access to the Operator Console service.

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

To deploy a new MinIO Tenant with OIDC external identity management, select the + Create Tenant button.

TO configure an existing MinIO Tenant with OIDC external identity management select that Tenant from the displayed list. The following steps reference the necessary sections and configuration settings for existing Tenants.

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.

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.
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.

Baremetal

Set the OpenID Configuration Settings

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:
Environment Variables
MinIO supports specifying the OIDC provider settings using environment variables. The minio server process applies the specified settings on its next startup. For distributed deployments, specify these settings across all nodes in the deployment using the same values consistently.

The following example code sets all environment variables related to configuring an OIDC provider for external identity management. The minimum required variable is MINIO_IDENTITY_OPENID_CONFIG_URL:
export MINIO_IDENTITY_OPENID_CONFIG_URL="https://openid-provider.example.net/.well-known/openid-configuration" export MINIO_IDENTITY_OPENID_CLIENT_ID="<string>" export MINIO_IDENTITY_OPENID_CLIENT_SECRET="<string>" export MINIO_IDENTITY_OPENID_CLAIM_NAME="<string>" export MINIO_IDENTITY_OPENID_CLAIM_PREFIX="<string>" export MINIO_IDENTITY_OPENID_SCOPES="<string>" export MINIO_IDENTITY_OPENID_REDIRECT_URI="<string>" export MINIO_IDENTITY_OPENID_COMMENT="<string>"
Replace the MINIO_IDENTITY_OPENID_CONFIG_URL with the URL endpoint of the OIDC provider discovery document.

For complete documentation on these variables, see OpenID Identity Management Settings
Configuration Settings
MinIO supports specifying the OIDC provider settings using configuration settings. The minio server process applies the specified settings on its next startup. For distributed deployments, the mc admin config command applies the configuration to all nodes in the deployment.

The following example code sets all configuration settings related to configuring an OIDC provider for external identity management. The minimum required setting is identity_openid config_url:
mc admin config set ALIAS/ identity_openid \ config_url="https://openid-provider.example.net/.well-known/openid-configuration" \ client_id="<string>" \ client_secret="<string>" \ claim_name="<string>" \ claim_prefix="<string>" \ scopes="<string>" \ redirect_uri="<string>" \ comment="<string>"
Replace the config_url with the URL endpoint of the OIDC provider discovery document.

For more complete documentation on these settings, see identity_openid.
Restart the MinIO Deployment

You must restart the MinIO deployment to apply the configuration changes. Use the mc admin service restart command to restart the deployment.
```
mc admin service restart ALIAS
```
Replace ALIAS with the alias of the deployment to restart.
Use the MinIO 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 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, https://minio.example.net:9000.

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 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 service account.
Generate S3-Compatible Temporary Credentials using OIDC Credentials

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 PUT, GET, and DELETE operations.

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 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.