Avatar Extension + Keycloakify Account Theme

This repository contains two parts that work together:

• A Keycloak server extension (Java) that exposes POST /realms/{realm}/avatar/{userId} and stores avatar images through pluggable backends.
• A Keycloakify Single-Page account theme (avatar-account-ui/) that overrides the Personal Info page with avatar upload + crop (react-easy-crop).

What The Personal Info Override Does

The custom Personal Info route adds an avatar panel that allows users to:

1. Select an image file (png, jpeg, webp, max 5MB).
2. Crop it to a square/round avatar.
3. Upload it to the extension endpoint using the logged-in user's bearer token.

The server endpoint now enforces:

• authenticated bearer token,
• token.subject == {userId} authorization,
• MIME allow-list (image/jpeg, image/png, image/webp),
• max payload size (5MB).

Picture Claim In Tokens

When the extension initializes, it ensures the default profile client scope contains a picture OIDC mapper (oidc-usermodel-attribute-mapper) so the claim is available in tokens.

On successful avatar upload, the extension also updates the user attribute picture to point at:

• /realms/{realm}/avatar/{userId}

Token claim values are evaluated when tokens are issued, so users need to refresh/re-login to see a newly uploaded avatar reflected in picture.

Build

1) Build the extension JAR

From the repository root:

mvn clean package

Output:

• target/avatar-extension-0.0.1-SNAPSHOT.jar
• target/providers/*.jar (runtime dependencies needed by the extension, including AWS SDK when using S3)

2) Build the Keycloakify theme JAR

From theme/:

npm install
npm run build-keycloak-theme

Output:

• theme/dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar (for Keycloak 26+)
• theme/dist_keycloak/keycloak-theme-for-kc-22-to-25.jar (for Keycloak 22-25)

3) Publish the Keycloakify theme to Maven Central

From theme/:

npm run publish-maven-theme

What this does:

1. Builds the Keycloakify theme.
2. Syncs generated Keycloakify Maven resources into theme/maven/keycloak-theme-for-kc-all-other-versions/.
3. Publishes via mvn -Prelease -DskipTests deploy using the checked-in pom.xml.

The sync step also keeps a verbatim copy of Keycloakify's generated POM in:

• theme/maven/keycloak-theme-for-kc-all-other-versions/pom.keycloakify.xml

Deploy To Keycloak

Copy the extension JAR, its runtime dependency JARs, and the theme JAR into Keycloak providers, then rebuild the Keycloak distribution:

# Optional but recommended when iterating: remove previously copied runtime deps
rm -f /opt/keycloak/providers/jackson-*.jar /opt/keycloak/providers/slf4j-api-*.jar

cp target/avatar-extension-0.0.1-SNAPSHOT.jar /opt/keycloak/providers/
cp target/providers/*.jar /opt/keycloak/providers/
cp theme/dist_keycloak/keycloak-theme-for-kc-all-other-versions.jar /opt/keycloak/providers/
/opt/keycloak/bin/kc.sh build

Then start Keycloak and set the realm Account Theme to avatar-account-ui.

MinIO setup notes

If you select storage-type=minio in avatar storage settings:

• set minio-host, minio-port, and bucket,
• set minio-access-key and minio-secret-key when authentication is required,
• set minio-secure=false for local HTTP MinIO instances,
• keep minio-secure=true when connecting over HTTPS.

Local Verification Checklist

1. Start Keycloak.
2. Log into the admin console (/).
3. Go to the avatar settings section and set the storage backend to the one you want to test.
4. Set the account theme to avatar-account-ui.
5. Log in to account console (/realms/{realm}/account).
6. Open Personal Info.
7. Upload a valid image, crop, click Upload avatar.
8. Confirm success alert and storage backend write.
9. Confirm oversized or invalid MIME uploads are rejected.
10. Confirm users cannot upload avatars for another user id.