Keycloak Identity Provider

This guide covers configuring Keycloak as an OpenID Connect (OIDC) identity provider for MinIO AIStor. For general OIDC configuration, see OpenID Connect Identity Management.

Prerequisites

  • A running Keycloak server. See the Keycloak installation guide for setup instructions.
  • A MinIO AIStor deployment with network connectivity to the Keycloak server.
  • The mc CLI installed and configured with an alias for your MinIO AIStor deployment.

Configure Keycloak

Create a client

  1. In the Keycloak admin console, navigate to Clients and select the account client (or create a new client).
  2. Under Settings, change Access Type to confidential and save.
  3. Under the Credentials tab, copy the Secret value. This value is used for MINIO_IDENTITY_OPENID_CLIENT_SECRET.
  4. Under Settings, set Valid Redirect URIs to * (or restrict to your MinIO AIStor Console URL).
  5. Under Advanced Settings, set Access Token Lifespan to 1 Hours.

Configure policy claim mapping

MinIO AIStor uses a JWT claim to determine which policies to assign to an authenticated user.

  1. Navigate to Users, select the user, and under Attributes add:
    • Key: policy
    • Value: the name of a MinIO AIStor policy (for example, readwrite)
  2. Navigate to Clients > account > Mappers > Create:
    • Name: any descriptive text
    • Mapper Type: User Attribute
    • User Attribute: policy
    • Token Claim Name: policy
    • Claim JSON Type: string

Verify the OpenID discovery document

Open the following URL in a browser to confirm it returns authorization_endpoint and jwks_uri:

http://<keycloak-host>:8080/auth/realms/<your-realm>/.well-known/openid-configuration

Enable Keycloak Admin REST API (optional)

To allow MinIO AIStor to query Keycloak for group memberships:

  1. Ensure the account client has Service Accounts Enabled.
  2. Add a custom Audience mapper in the Mappers section with Included Client Audience set to security-admin-console.
  3. Create an admin role and assign it to the client’s Service Account Roles.

Configure MinIO AIStor

Add the Keycloak OIDC provider using mc:

mc idp openid add ALIAS keycloak \
  config_url="http://<keycloak-host>:8080/auth/realms/<your-realm>/.well-known/openid-configuration" \
  client_id="account" \
  client_secret="<client-secret>" \
  scopes="openid" \
  display_name="Keycloak"

Or using environment variables:

export MINIO_IDENTITY_OPENID_CONFIG_URL="http://<keycloak-host>:8080/auth/realms/<your-realm>/.well-known/openid-configuration"
export MINIO_IDENTITY_OPENID_CLIENT_ID="account"
export MINIO_IDENTITY_OPENID_CLIENT_SECRET="<client-secret>"
export MINIO_IDENTITY_OPENID_SCOPES="openid"
export MINIO_IDENTITY_OPENID_DISPLAY_NAME="Keycloak"

Restart MinIO AIStor to apply the configuration:

mc admin service restart ALIAS
Use the scopes parameter to restrict the OpenID scopes requested by MinIO AIStor. For example, openid,policy_role_attribute where policy_role_attribute is a client scope that maps a role attribute to the policy claim.

Log in with Keycloak

  1. Open the MinIO AIStor Console in a browser.
  2. Select Login with SSO.
  3. Enter your Keycloak credentials on the redirect page.
  4. After successful authentication, you are redirected to the MinIO AIStor Console with access based on your assigned policies.

Using the STS WebIdentity API

Applications can programmatically obtain temporary MinIO AIStor credentials using the AssumeRoleWithWebIdentity STS API. The application authenticates with Keycloak to obtain an ID token, then exchanges it for temporary MinIO AIStor credentials.

Using groups as policy claims

Keycloak supports groups through external connectors. To use groups instead of per-user attributes for policy mapping, set the claim name to groups:

mc idp openid add ALIAS keycloak \
  config_url="http://<keycloak-host>:8080/auth/realms/<your-realm>/.well-known/openid-configuration" \
  client_id="account" \
  client_secret="<client-secret>" \
  claim_name="groups"

Create policies matching your Keycloak group names:

mc admin policy create ALIAS <group-name> policy.json