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

1) Create the Podman Pod

Create a Podman Pod to deploy the Keycloak and MinIO containers in a Pod with shared networking. This ensures both containers can communicate normally.

podman pod create \ 
     -p 9000:9000 -p 9090:9090 -p 8080:8080 \
     -v ~/minio-keycloak/minio:/mnt/minio \
     -n minio-keycloak

Replace ~/minio-keycloak/minio with a path to an empty folder in which the MinIO container stores data.

You can alternatively deploy the Containers as Root to allow access to the host network for the purpose of inter-container networking.

Deploying via Docker Compose is out of scope for this tutorial.

2) Start the Keycloak Container

Follow the instructions for running Keycloak in a container. The Try Keycloak in development mode steps are sufficient for this procedure.

podman run -dt \
       --name keycloak \
       --pod minio-keycloak \
       -e KEYCLOAK_ADMIN=keycloakadmin \
       -e KEYCLOAK_ADMIN_PASSWORD=keycloakadmin123 \
       quay.io/keycloak/keycloak:latest start-dev

Go to localhost:8080 to access the Keycloak container.

3) Configure or Create a Client for Accessing Keycloak

Authenticate to the Keycloak Administrative Console and navigate to Clients.

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

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

6) Start the MinIO Container

The following command starts the MinIO Container and attaches it to the minio-keycloak pod.

podman run -dt \
       --name minio-server \
       --pod minio-keycloak \
       quay.io/minio/minio:RELEASE.2023-02-22T18-23-45Z server /mnt/data --console-address :9090

Go to localhost:9090 to access the MinIO Console. Log in using the default credentials minioadmin:minioadmin.

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

MinIO Console

CLI

Environment Variables

You must restart the MinIO deployment for the changes to apply.

Check the MinIO server logs <minio-logging> and verify that startup succeeded with no errors related to the Keycloak 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.

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

Next Steps

Applications should implement the STS <minio-security-token-service> 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.