docs/source/includes/k8s/steps-configure-keycloak-identity-management.rst

1) Configure or Create a Client for Accessing Keycloak

Authenticate to the Keycloak Administrative Console and navigate to Clients.

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.

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 <minio-policy> on the MinIO deployment.

4) Configure MinIO for Keycloak Authentication

MinIO supports multiple methods for configuring Keycloak authentication:

• Using the MinIO Operator Console
• Using the MinIO Tenant Console
• Using a terminal/shell and the mc idp openid command

MinIO Operator Console

You can use the MinIO Operator Console to configure Keycloak as the External Identity Provider for the MinIO Tenant. See minio-operator-console-connect for specific instructions.

Select Identity Provider from the left-hand navigation bar, then select OpenID. Select Create Configuration to create a new configuration.

Enter the following information into the modal:

Name	Enter a unique name for the Keycloak instance
Config URL	Specify the address of the Keycloak OpenID configuration document (keycloak-service.keycloak-namespace.svc.cluster-domain.example) Ensure the REALM matches the Keycloak realm you want to use for authenticating users to MinIO
Client ID	Specify the name of the Keycloak client created in Step 1
Client Secret	Specify the secret credential value for the Keycloak client created in Step 1
Display Name	Specify the user-facing name the MinIO Console should display as part of the Single-Sign On (SSO) workflow for the configured Keycloak service
Scopes	Specify the OpenID scopes to include in the JWT, such as preferred_username or email You can reference these scopes using supported OpenID policy variables for the purpose of programmatic policy configurations
Redirect URI Dynamic	Toggle to on Substitutes the MinIO Console address used by the client as part of the Keycloak redirect URI. Keycloak returns authenticated users to the Console using the provided URI. For MinIO Console deployments behind a reverse proxy, load balancer, or similar network control plane, you can instead use the MINIO_BROWSER_REDIRECT_URL variable to set the redirect address for Keycloak to use.

Select Save to apply the configuration.

MinIO Tenant Console

You can use the MinIO Tenant Console to configure Keycloak as the External Identity Provider for the MinIO Tenant.

Access the Console service using the NodePort, Ingress, or Load Balancer endpoint. You can use the following command to review the Console configuration:

kubectl describe svc/TENANT_NAME-console -n TENANT_NAMESPACE

Replace TENANT_NAME and TENANT_NAMESPACE with the name of the MinIO Tenant and it's Namespace, respectively.

Select Save to apply the configuration.

CLI

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)

Next Steps

Applications should implement the STS AssumeRoleWithWebIdentity <minio-sts-assumerolewithwebidentity> flow using their SDK <minio-drivers> 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 <minio-id-access-keys> through the MinIO Console for the purpose of creating long-lived API-key like access using their Keycloak credentials.