Configure MinIO for Authentication using Keycloak

MinIO Deployment

This procedure assumes an existing MinIO cluster running the latest stable MinIO version. Refer to the Install and Deploy MinIO for more complete documentation on new MinIO deployments.

This procedure may work as expected for older versions of MinIO.

Keycloak Deployment and Realm Configuration

This procedure assumes an existing Keycloak deployment to which you have administrative access. Specifically, you must have permission to create and configure Realms, Clients, Client Scopes, Realm Roles, Users, and Groups on the Keycloak deployment.

This procedure assumes bidirectional access between the Keycloak and MinIO deployments.

Install and Configure mc with Access to the MinIO Cluster

This procedure uses mc for performing operations on the MinIO cluster. Install mc on a machine with network access to the cluster.

See the mc Installation Quickstart for instructions on downloading and installing mc.

This procedure assumes a configured alias for the MinIO cluster.

1) Configure or Create a Client for Accessing Keycloak

Authenticate to the Keycloak Administrative Console and navigate to Clients.

Select Create client and follow the instructions to create a new Keycloak client for MinIO. Fill in the specified inputs as follows:

Keycloak deploys the client with a default set of configuration values. Modify these values as necessary for your Keycloak setup and desired behavior. The following table provides a baseline of settings and values to configure:

2) Create Client Scope for MinIO Client

Client scopes allow Keycloak to map user attributes as part of the JSON Web Token (JWT) returned in authentication requests. This allows MinIO to reference those attributes when assigning policies to the user. This step creates the necessary client scope to support MinIO authorization after successful Keycloak authentication.

Navigate to the Client scopes view and create a new client scope for MinIO authorization:

Once created, select the scope from the list and navigate to Mappers.

Select Configure a new mapper to create a new mapping:

Once created, assign the Client Scope to the MinIO client.

1. Navigate to Clients and select the MinIO client.

2. Select Client scopes, then select Add client scope.

3. Select the previously created scope and set the Assigned type to default.

3) Apply the Necessary Attribute to Keycloak Users/Groups

You must assign an attribute named policy to the Keycloak Users or Groups. Set the value to any policy on the MinIO deployment.

For Users, navigate to Users and select or create the User:

For Groups, navigate to Groups and select or create the Group:

You can assign users to groups such that they inherit the specified policy attribute. If you set the Mapper settings to enable Aggregate attribute values, Keycloak includes the aggregated array of policies as part of the authenticated user’s JWT token. MinIO can use this list of policies when authorizing the user.

You can test the configured policies of a user by using the Keycloak API:

curl -d "client_id=minio" \
     -d "client_secret=secretvalue" \
     -d "grant_type=password" \
     -d "username=minio-user-1" \
     -d "password=minio-user-1-password" \
     http://keycloak-url.example.net:8080/realms/REALM/protocol/openid-connect/token

If successful, the access_token contains the JWT necessary to use the MinIO AssumeRoleWithWebIdentity STS API and generate S3 credentials.

You can use a JWT decoder to review the payload and ensure it contains the policy key with one or more MinIO policies listed.

4) Configure MinIO for Keycloak Authentication

MinIO supports multiple methods for configuring Keycloak authentication:

• Using the MinIO Console

• Using a terminal/shell and the mc idp openid command

• Using environment variables set prior to starting MinIO

mc idp openid add ALIAS PRIMARY_IAM \
   client_id=MINIO_CLIENT \
   client_secret=MINIO_CLIENT_SECRET \
   config_url="https://keycloak-url.example.net:8080/realms/REALM/.well-known/openid-configuration" \
   display_name="SSO_IDENTIFIER"
   scopes="openid,email,preferred_username" \
   redirect_uri_dynamic="on"

MINIO_IDENTITY_OPENID_CONFIG_URL_PRIMARY_IAM="https://keycloak-url.example.net:8080/.well-known/openid-configuration"
MINIO_IDENTITY_OPENID_CLIENT_ID_PRIMARY_IAM="MINIO_CLIENT"
MINIO_IDENTITY_OPENID_CLIENT_SECRET_PRIMARY_IAM="MINIO_CLIENT_SECRET"
MINIO_IDENTITY_OPENID_DISPLAY_NAME_PRIMARY_IAM="SSO_IDENTIFIER"
MINIO_IDENTITY_OPENID_SCOPES_PRIMARY_IAM="openid,email,preferred_username"
MINIO_IDENTITY_OPENID_REDIRECT_URI_DYNAMIC_PRIMARY_IAM="on"

Restart the MinIO deployment for the changes to apply.

Check the MinIO logs and verify that startup succeeded with no errors related to the OIDC configuration.

If you attempt to log in with the Console, you should now see an (SSO) button using the configured Display Name.

Specify a configured user and attempt to log in. MinIO should automatically redirect you to the Keycloak login entry. Upon successful authentication, Keycloak should redirect you back to the MinIO Console using either the originating Console URL or the Redirect URI if configured.

5) Generate Application Credentials using the Security Token Service (STS)

Applications using an S3-compatible SDK must specify credentials in the form of an access key and secret key. The MinIO AssumeRoleWithWebIdentity API returns the necessary temporary credentials, including a required session token, using a JWT returned by Keycloak after authentication.

You can test this workflow using the following sequence of HTTP calls and the curl utility:

1. Authenticate as a Keycloak user and retrieve the JWT token

   curl -X POST "https://keycloak-url.example.net:8080/realms/REALM/protocol/openid-connect/token" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "username=USER" \
        -d "password=PASSWORD" \
        -d "grant_type=password" \
        -d "client_id=CLIENT" \
        -d "client_secret=SECRET"
   

   • Replace the USER and PASSWORD with the credentials of a Keycloak user on the REALM.

   • Replace the CLIENT and SECRET with the client ID and secret for the MinIO-specific Keycloak client on the REALM

   You can process the results using jq or a similar JSON-formatting utility. Extract the access_token field to retrieve the necessary access token. Pay attention to the expires_in field to note the number of seconds before the token expires.

2. Generate MinIO Credentials using the AssumeRoleWithWebIdentity API

   curl -X POST "https://minio-url.example.net:9000" \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "Action=AssumeRoleWithWebIdentity" \
        -d "Version=2011-06-15" \
        -d "DurationSeconds=86000" \
        -d "WebIdentityToken=TOKEN"
   

   Replace the TOKEN with the access_token value returned by Keycloak.

   The API returns an XML document on success containing the following keys:

   • Credentials.AccessKeyId - the Access Key for the Keycloak User

   • Credentials.SecretAccessKey - the Secret Key for the Keycloak User

   • Credentials.SessionToken - the Session Token for the Keycloak User

   • Credentials.Expiration - the Expiration Date for the generated credentials

3. Test the Credentials

   Use your preferred S3-compatible SDK to connect to MinIO using the generated credentials.

   For example, the following Python code using the MinIO Python SDK connects to the MinIO deployment and returns a list of buckets:

   from minio import Minio
   
   client = MinIO(
      "minio-url.example.net:9000",
      access_key = "ACCESS_KEY",
      secret_key = "SECRET_KEY",
      session_token = "SESSION_TOKEN"
      secure = True
   )
   
   client.list_buckets()
   

Next Steps

Applications should implement the STS AssumeRoleWithWebIdentity flow using their SDK of choice. When STS credentials expire, applications should have logic in place to regenerate the JWT token, STS token, and MinIO credentials before retrying and continuing operations.

Alternatively, users can generate access keys through the MinIO Console for the purpose of creating long-lived API-key like access using their Keycloak credentials.

1) Create the Necessary Client Scopes

Navigate to the Client scopes view and create a new scope:

Navigate to Clients and select the MinIO client

1. From Service account roles, select Assign role and assign the admin role

2. From Client scopes, select Add client scope and add the previously created scope

Navigate to Settings and ensure Authentication flow includes Service accounts roles.

2) Validate Admin API Access

You can validate the functionality by using the Admin REST API with the MinIO client credentials to retrieve a bearer token and user data:

1. Retrieve the bearer token:

   curl -d "client_id=minio" \
        -d "client_secret=secretvalue" \
        -d "grant_type=password" \
        http://keycloak-url:port/admin/realms/REALM/protocol/openid-connect/token
   

2. Use the value returned as the access_token to access the Admin API:

   curl -H "Authentication: Bearer ACCESS_TOKEN_VALUE" \
        http://keycloak-url:port/admin/realms/REALM/users/UUID
   

   Replace UUID with the unique ID for the user which you want to retrieve. The response should resemble the following:

   {
      "id": "954de141-781b-4eaf-81bf-bf3751cdc5f2",
      "createdTimestamp": 1675866684976,
      "username": "minio-user-1",
      "enabled": true,
      "totp": false,
      "emailVerified": false,
      "firstName": "",
      "lastName": "",
      "attributes": {
         "policy": [
            "readWrite"
         ]
      },
      "disableableCredentialTypes": [],
      "requiredActions": [],
      "notBefore": 0,
      "access": {
         "manageGroupMembership": true,
         "view": true,
         "mapRoles": true,
         "impersonate": true,
         "manage": true
      }
   }
   

   MinIO would revoke access for an authenticated user if the returned value has enabled: false or null (user was removed from Keycloak).

3) Enable Keycloak Admin Support on MinIO

MinIO supports multiple methods for configuring Keycloak Admin API Support:

• Using a terminal/shell and the mc idp openid command

• Using environment variables set prior to starting MinIO

mc idp openid update ALIAS KEYCLOAK_IDENTIFIER \
   vendor="keycloak" \
   keycloak_admin_url="https://keycloak-url:port/admin"
   keycloak_realm="REALM"

MINIO_IDENTITY_OPENID_VENDOR_PRIMARY_IAM="keycloak"
MINIO_IDENTITY_OPENID_KEYCLOAK_ADMIN_URL_PRIMARY_IAM="https://keycloak-url:port/admin"
MINIO_IDENTITY_OPENID_KEYCLOAK_REALM_PRIMARY_IAM="REALM"