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

• Configuring a MinIO Tenant to use an external AD/LDAP provider
• Accessing the Tenant Console using AD/LDAP Credentials.
• Using the MinIO AssumeRoleWithLDAPIdentity Security Token Service (STS) API to generate temporary credentials for use by applications.

For MinIO deployments on baremetal infrastructure, this procedure covers:

• Configuring a MinIO cluster for an external AD/LDAP provider.
• Accessing the MinIO Console using AD/LDAP credentials.
• Using the MinIO AssumeRoleWithLDAPIdentity Security Token Service (STS) API to generate temporary credentials for use by applications.

You must have access to the MinIO Operator Console web UI. You can either expose the MinIO Operator Console service using your preferred Kubernetes routing component, or use temporary port forwarding to expose the Console service port on your local machine.

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.

• For AD/LDAP deployments 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 AD/LDAP service.
• For AD/LDAP deployments 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.

The MinIO deployment must have bidirectional network connectivity to the target AD / LDAP service.

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

• Configure Keycloak for use with MinIO authentication and authorization
• Configure a new or existing MinIO Tenant to use Keycloak as the OIDC provider
• Create policies to control access of Keycloak-authenticated users
• Log into the MinIO Tenant Console using SSO and a Keycloak-managed identity
• Generate temporary S3 access credentials using the AssumeRoleWithWebIdentity Security Token Service (STS) API

For MinIO deployments on baremetal infrastructure, this procedure covers:

• Configure Keycloak for use with MinIO authentication and authorization
• Configure a new or existing MinIO cluster to use Keycloak as the OIDC provider
• Create policies to control access of Keycloak-authenticated users
• Log into the MinIO Console using SSO and a Keycloak-managed identity
• Generate temporary S3 access credentials using the AssumeRoleWithWebIdentity Security Token Service (STS) API

For Keycloak deployments within the same Kubernetes cluster as the MinIO Tenant, this procedure assumes bidirectional access between the Keycloak and MinIO pods/services. For Keycloak deployments external to the Kubernetes cluster, this procedure assumes an existing Ingress, Load Balancer, or similar Kubernetes network control component that manages network access to and from the MinIO Tenant.

The MinIO deployment must have bidirectional access to the target OIDC service.

You must have access to the MinIO Operator Console web UI. You can either expose the MinIO Operator Console service using your preferred Kubernetes routing component, or use temporary port forwarding to expose the Console service port on your local machine.

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:

   Client ID	Set to a unique identifier for MinIO (minio)
   Client type	Set to OpenID Connect
   Always display in console	Toggle to On
   Client authentication	Toggle to On
   Authentication flow	Toggle on Standard flow
   (Optional) Authentication flow	Toggle on Direct access grants (API testing)

   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:

   Root URL	Set to ${authBaseUrl}
   Home URL	Set to the Realm you want MinIO to use (/realms/master/account/)
   Valid Redirect URI	Set to *
   Keys -> Use JWKS URL	Toggle to On
   Advanced -> Advanced Settings -> Access Token Lifespan	Set to 1 Hour.

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:

   Name	Set to any recognizable name for the policy (minio-authorization)
   Include in token scope	Toggle to On

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

   Select Configure a new mapper to create a new mapping:

   User Attribute	Select the Mapper Type
   Name	Set to any recognizable name for the mapping (minio-policy-mapper)
   User Attribute	Set to policy
   Token Claim Name	Set to policy
   Add to ID token	Set to On
   Claim JSON Type	Set to String
   Multivalued	Set to On This allows setting multiple policy values in the single claim.
   Aggregate attribute values	Set to On This allows users to inherit any policy set in their Groups

   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:

   Credentials	Set the user password to a permanent value if not already set
   Attributes	Create a new attribute with key policy and value of any policy (consoleAdmin)

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

   Attributes

   Create a new attribute with key policy and value of any policy (consoleAdmin)

   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-service.keycloak-namespace.svc.cluster-domain.example/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

You can use the mc idp openid add command to create a new configuration for the Keycloak service. The command takes all supported OpenID Configuration Settings:

mc idp openid add ALIAS PRIMARY_IAM \
   client_id=MINIO_CLIENT \
   client_secret=MINIO_CLIENT_SECRET \
   config_url="https://keycloak-service.keycloak-namespace.svc.cluster-domain.example/realms/REALM/.well-known/openid-configuration" \
   display_name="SSO_IDENTIFIER"
   scopes="openid,email,preferred_username" \
   redirect_uri_dynamic="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.

1. 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-service.keycloak-namespace.svc.cluster-domain.example/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.minio-tenant.svc.cluster-domain.example" \
           -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.minio-tenant.svc.cluster-domain.example",
         access_key = "ACCESS_KEY",
         secret_key = "SECRET_KEY",
         session_token = "SESSION_TOKEN"
         secure = True
      )
      
      client.list_buckets()

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

   Client ID	Set to a unique identifier for MinIO (minio)
   Client type	Set to OpenID Connect
   Always display in console	Toggle to On
   Client authentication	Toggle to On
   Authentication flow	Toggle on Standard flow
   (Optional) Authentication flow	Toggle on Direct access grants (API testing)

   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:

   Root URL	Set to ${authBaseUrl}
   Home URL	Set to the Realm you want MinIO to use (/realms/master/account/)
   Valid Redirect URI	Set to *
   Keys -> Use JWKS URL	Toggle to On
   Advanced -> Advanced Settings -> Access Token Lifespan	Set to 1 Hour.

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:

   Name	Set to any recognizable name for the policy (minio-authorization)
   Include in token scope	Toggle to On

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

   Select Configure a new mapper to create a new mapping:

   User Attribute	Select the Mapper Type
   Name	Set to any recognizable name for the mapping (minio-policy-mapper)
   User Attribute	Set to policy
   Token Claim Name	Set to policy
   Add to ID token	Set to On
   Claim JSON Type	Set to String
   Multivalued	Set to On This allows setting multiple policy values in the single claim.
   Aggregate attribute values	Set to On This allows users to inherit any policy set in their Groups

   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:

   Credentials	Set the user password to a permanent value if not already set
   Attributes	Create a new attribute with key policy and value of any policy (consoleAdmin)

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

   Attributes

   Create a new attribute with key policy and value of any policy (consoleAdmin)

   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 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/realms/REALM/.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"