POC: Fetch Azure user avatar from Microsoft Graph API #41009

gryffus · 2025-07-08T15:18:06Z

gryffus
Jul 8, 2025

Hello,

I have implemented a following mapper SPI that fetches user avatar image from Graph API and saves it into a configurable user attribute.

/*
 * Copyright 2016 Red Hat, Inc. and/or its affiliates
 * and other contributors as indicated by the @author tags.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.cloverdx.keycloak;

import java.io.InputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.HashSet;
import java.util.List;
import java.util.Set;

import org.keycloak.broker.oidc.mappers.UserAttributeMapper;
import org.keycloak.broker.provider.BrokeredIdentityContext;
import org.keycloak.models.IdentityProviderMapperModel;
import org.keycloak.models.IdentityProviderSyncMode;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;
import org.keycloak.provider.ProviderConfigProperty;
import org.keycloak.social.microsoft.MicrosoftIdentityProviderFactory;

import com.fasterxml.jackson.databind.ObjectMapper;

/**
 * Mapper that fetches the avatar from Azure AD Graph API and saves it to the
 * user profile.
 *
 * Attribute name is configurable in the mapper settings. Default is "picture".
 *
 * @author <a href="mailto:lukas.krejza@cloverdx.com">Lukas Krejza</a>
 * @version $Revision: 1 $
 */
public class KeycloakAzureAvatarMapper extends UserAttributeMapper {

    public static final String[] AZURE_COMPATIBLE_PROVIDERS = {MicrosoftIdentityProviderFactory.PROVIDER_ID};
    private static final Set<IdentityProviderSyncMode> IDENTITY_PROVIDER_SYNC_MODES = new HashSet<>(Arrays.asList(IdentityProviderSyncMode.values()));

    private static final List<ProviderConfigProperty> configProperties = new ArrayList<>();

    static {
        ProviderConfigProperty claimsProperty = new ProviderConfigProperty();
        claimsProperty.setName("attribute");
        claimsProperty.setLabel("Attribute");
        claimsProperty.setHelpText("Name of the user attribute to save the avatar to. Default is 'picture'.");
        claimsProperty.setType(ProviderConfigProperty.STRING_TYPE);
        configProperties.add(claimsProperty);
    }

    public static final String AZURE_AVATAR_MAPPER_PROVIDER_ID = "keycloak-azure-avatar-mapper";

    @Override
    public boolean supportsSyncMode(IdentityProviderSyncMode syncMode) {
        return IDENTITY_PROVIDER_SYNC_MODES.contains(syncMode);
    }

    @Override
    public List<ProviderConfigProperty> getConfigProperties() {
        return configProperties;
    }

    @Override
    public String getId() {
        return AZURE_AVATAR_MAPPER_PROVIDER_ID;
    }

    @Override
    public String[] getCompatibleProviders() {
        return AZURE_COMPATIBLE_PROVIDERS;
    }

    @Override
    public String getDisplayCategory() {
        return "Attribute importer";
    }

    @Override
    public String getDisplayType() {
        return "User avatar";
    }

    @Override
    public String getHelpText() {
        return "Saves the user avatar from Azure AD Graph API to the user profile as base64-encoded string.";
    }

    public String getAzureAvatar(String accessToken) {
        try {
            String contentType = fetchAvatarFormatFromGraphAPI(accessToken);
            byte[] avatarBytes = fetchAvatarFromGraphAPI(accessToken);
            if (contentType != null && avatarBytes != null) {
                String base64Avatar = Base64.getEncoder().encodeToString(avatarBytes);
                return "data:" + contentType + ";base64," + base64Avatar;
            }
        } catch (Exception e) {
            System.err.println("Failed to fetch avatar: " + e.getMessage());
        }

        return null;
    }

    private byte[] fetchAvatarFromGraphAPI(String accessToken) throws Exception {
        URL url = java.net.URI.create("https://graph.microsoft.com/v1.0/me/photo/$value").toURL();
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestProperty("Authorization", "Bearer " + accessToken);
        conn.setRequestMethod("GET");

        if (conn.getResponseCode() == 200) {
            try (InputStream is = conn.getInputStream()) {
                return is.readAllBytes();
            }
        }

        return null;
    }

    private String fetchAvatarFormatFromGraphAPI(String accessToken) throws Exception {
        URL url = java.net.URI.create("https://graph.microsoft.com/v1.0/me/photo").toURL();
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestProperty("Authorization", "Bearer " + accessToken);
        conn.setRequestMethod("GET");

        if (conn.getResponseCode() == 200) {
            try (InputStream is = conn.getInputStream()) {
                return new ObjectMapper().readTree(is).get("@odata.mediaContentType").asText();
            }
        }

        return null;
    }

    @Override
    public void preprocessFederatedIdentity(KeycloakSession session, RealmModel realm, IdentityProviderMapperModel mapperModel, BrokeredIdentityContext context) {
        String attribute = mapperModel.getConfig().getOrDefault("attribute", "picture");
        String accessToken = null;
        try {
            accessToken = new ObjectMapper().readTree(context.getToken()).get("access_token").asText();
        } catch (java.io.IOException e) {
            System.err.println("[KeycloakAzureAvatarMapper] Failed to parse access token from context: " + e.getMessage());
        }

        if (accessToken != null) {
            String avatarBase64 = getAzureAvatar(accessToken);
            if (avatarBase64 != null) {
                context.setUserAttribute(attribute, avatarBase64);
            } else {
                System.out.println("[KeycloakAzureAvatarMapper] Avatar data is null, not setting user attribute.");
            }
        } else {
            System.out.println("[KeycloakAzureAvatarMapper] No access token found in context data.");
        }
    }

    @Override
    public void updateBrokeredUser(KeycloakSession session, RealmModel realm, UserModel user, IdentityProviderMapperModel mapperModel, BrokeredIdentityContext context) {
        String attribute = mapperModel.getConfig().getOrDefault("attribute", "picture");
        String accessToken = null;
        try {
            accessToken = new ObjectMapper().readTree(context.getToken()).get("access_token").asText();
        } catch (java.io.IOException e) {
            System.err.println("[KeycloakAzureAvatarMapper] Failed to parse access token from context: " + e.getMessage());
        }

        if (accessToken != null) {
            String avatarBase64 = getAzureAvatar(accessToken);
            if (avatarBase64 != null) {
                user.setSingleAttribute(attribute, avatarBase64);
            } else {
                System.out.println("[KeycloakAzureAvatarMapper] Avatar data is null, not setting user attribute.");
            }
        } else {
            System.out.println("[KeycloakAzureAvatarMapper] No access token found in context data.");
        }
    }
}

To configure it, you need to:

Add a new Attribute in Realm settings -> User profile -> Create attribute (name it picture for seamless integration)
Under "Validations", add new "length" validator with max about 512000 so it can fit the image
In your Microsoft Identity provider config, under mappers add a new "User avatar" mapper.

After login, you should now see the "picture" attribute filled with the base64-encoded image data:

In account-console, you should see your avatar image.

Unfortunatelly, there is no way to get the avatar from Azure as a link, they only provide it as binary data (ref: https://learn.microsoft.com/en-us/graph/api/profilephoto-get?view=graph-rest-1.0&tabs=http )

I can create a github repository with a build for testing if requested, but first I would like to ask:

Is this functionality wanted and would it be possible to merge it into keycloak codebase?
As this is my first keycloak SPI, I would be glad for any code review and hints on possible improvements

chrisbertagnolli · 2025-07-08T23:28:30Z

chrisbertagnolli
Jul 8, 2025

Hey thank you for this! I saw your post on Slack and used this as a starting point and made a few tweaks since I have Entra as a generic OIDC provider (not the social provider option) in an enterprise environment. I'm not a developer but was able to hack this together with some help.

Also changed verbiage around "Profile Picture" versus "Avatar" since in our case that's the usage and keeps it more inline with wording in Entra space (Profile Photo / Profile Picture).

I think it's helpful even outside of the account console, because now that can also be passed as claims to apps - some have asked for it this way before so will help a lot.

Here's the few tweaks I made if it helps you at all. I included a drop down on the size because the baseline /photo/me is the "largest available size" and wanted some control around that. The account console was also having issues with really large sizes so I excluded anything above the 360x360 - at least the ones that I tested above that size would give a "something went wrong" error when getting into the account console (images were >80 KB in total size).

import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Base64;
import java.util.HashSet;
import java.util.List;
import java.util.Map;
import java.util.Set;

import org.jboss.logging.Logger;
import org.keycloak.broker.oidc.mappers.UserAttributeMapper;
import org.keycloak.broker.provider.BrokeredIdentityContext;
import org.keycloak.models.IdentityProviderMapperModel;
import org.keycloak.models.IdentityProviderSyncMode;
import org.keycloak.models.KeycloakSession;
import org.keycloak.models.RealmModel;
import org.keycloak.models.UserModel;
import org.keycloak.provider.ProviderConfigProperty;

/**
 * Fetches a user's Microsoft Graph profile picture and stores it
 * as a base‑64 data‑URL in a Keycloak attribute (default: {@code picture}).
 */
public class KeycloakProfilePictureMapper extends UserAttributeMapper {

    // ---------------------------------------------------------------------
    // Constants & helpers
    // ---------------------------------------------------------------------

    public static final String PROVIDER_ID = "keycloak-profile-picture-mapper";
    private static final Logger LOG = Logger.getLogger(KeycloakProfilePictureMapper.class);

    private static final String DEFAULT_SIZE = "120x120";
    private static final String URL_TEMPLATE = "https://graph.microsoft.com/v1.0/me/photos/%s/$value";

    private static final HttpClient HTTP = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5))
            .build();

    private static final List<ProviderConfigProperty> CONFIG_PROPERTIES = new ArrayList<>();
    static {
        // where to save
        ProviderConfigProperty attr = new ProviderConfigProperty();
        attr.setName("attribute");
        attr.setLabel("Attribute");
        attr.setHelpText("User attribute that will hold the profile picture.");
        attr.setType(ProviderConfigProperty.STRING_TYPE);
        attr.setDefaultValue("picture");
        CONFIG_PROPERTIES.add(attr);

        // size selector
        ProviderConfigProperty size = new ProviderConfigProperty();
        size.setName("photoSize");
        size.setLabel("Thumbnail size");
        size.setHelpText("Select the Microsoft Graph thumbnail size you want Keycloak to store");
        size.setType(ProviderConfigProperty.LIST_TYPE);
        size.setOptions(List.of("48x48","64x64","96x96","120x120","240x240","360x360"));
        size.setDefaultValue(DEFAULT_SIZE);
        CONFIG_PROPERTIES.add(size);
    }

    private static final Set<IdentityProviderSyncMode> SUPPORTED_SYNC_MODES =
            new HashSet<>(Arrays.asList(IdentityProviderSyncMode.values()));

    // ---------------------------------------------------------------------
    // Provider meta-data
    // ---------------------------------------------------------------------

    @Override public String getId()                       { return PROVIDER_ID; }
    @Override public String[] getCompatibleProviders()    { return new String[]{"oidc"}; }
    @Override public boolean supportsSyncMode(IdentityProviderSyncMode m){ return SUPPORTED_SYNC_MODES.contains(m); }
    @Override public List<ProviderConfigProperty> getConfigProperties() { return CONFIG_PROPERTIES; }
    @Override public String getDisplayCategory()          { return "Attribute importer"; }
    @Override public String getDisplayType()              { return "Entra Profile Picture"; }
    @Override public String getHelpText() {
        return "Imports the user’s Microsoft Entra profile picture (selectable thumbnail size).";
    }

    // ---------------------------------------------------------------------
    // Core logic
    // ---------------------------------------------------------------------

    private String fetchPicture(String token, String size) {
        String url = String.format(URL_TEMPLATE, size);
        try {
            HttpRequest req = HttpRequest.newBuilder(URI.create(url))
                    .header("Authorization", "Bearer " + token)
                    .header("Accept", "image/*")
                    .timeout(Duration.ofSeconds(5))
                    .GET().build();

            HttpResponse<byte[]> res = HTTP.send(req, HttpResponse.BodyHandlers.ofByteArray());

            LOG.debugf("profile‑picture‑mapper: Graph %s -> %d", size, res.statusCode());

            if (res.statusCode() == 404) return null;              // no photo set
            if (res.statusCode() != 200) {
                LOG.warnf("profile‑picture‑mapper: Graph returned %d", res.statusCode());
                return null;
            }

            String type = res.headers().firstValue("Content-Type").orElse("image/jpeg");
            String b64  = Base64.getEncoder().encodeToString(res.body());
            return "data:" + type + ";base64," + b64;

        } catch (IOException | InterruptedException e) {
            LOG.error("profile‑picture‑mapper: Failed to fetch picture", e);
            Thread.currentThread().interrupt();
            return null;
        }
    }

    // ---------------------------------------------------------------------
    // Broker hooks
    // ---------------------------------------------------------------------

    @Override
    public void preprocessFederatedIdentity(KeycloakSession session,
                                            RealmModel realm,
                                            IdentityProviderMapperModel model,
                                            BrokeredIdentityContext ctx) {
        storePicture(model, ctx, null);
    }

    @Override
    public void updateBrokeredUser(KeycloakSession session,
                                   RealmModel realm,
                                   UserModel user,
                                   IdentityProviderMapperModel model,
                                   BrokeredIdentityContext ctx) {
        storePicture(model, ctx, user);
    }

    // ---------------------------------------------------------------------
    // Helper shared by both hooks
    // ---------------------------------------------------------------------

    private void storePicture(IdentityProviderMapperModel model,
                              BrokeredIdentityContext ctx,
                              UserModel persistentUser) {

        String attrName = model.getConfig().getOrDefault("attribute", "picture");
        String size     = model.getConfig().getOrDefault("photoSize", DEFAULT_SIZE);

        // --- Fetch token with fallback ------------------------------------
        String token = (String) ctx.getContextData().get("FEDERATED_ACCESS_TOKEN");

        if (token == null) {
            Object tr = ctx.getContextData().get("FEDERATED_ACCESS_TOKEN_RESPONSE");
            if (tr == null) tr = ctx.getContextData().get("IDENTITY_PROVIDER_TOKEN_RESPONSE");
            if (tr instanceof org.keycloak.representations.AccessTokenResponse atr) {
                token = atr.getToken();
            } else if (tr instanceof Map<?,?> map) {
                token = (String) map.get("access_token");
            } else if (tr instanceof String json) {
                try {
                    token = new com.fasterxml.jackson.databind.ObjectMapper()
                            .readTree(json).path("access_token").asText(null);
                } catch (Exception e) {
                    LOG.debug("profile‑picture‑mapper: unable to parse token JSON", e);
                }
            }
        }

        if (LOG.isDebugEnabled()) {
            LOG.debugf("contextData keys → %s", ctx.getContextData().keySet());
            LOG.debug("profile‑picture‑mapper: token present? " + (token != null && !token.isBlank()));
        }

        if (token == null || token.isBlank()) {
            LOG.debug("profile‑picture‑mapper: No access token; skipping.");
            return;
        }

        String picture = fetchPicture(token, size);
        if (picture == null) {
            LOG.debug("profile‑picture‑mapper: Graph returned no picture or non‑200 status; skipping.");
            return;
        }

        if (persistentUser == null) {
            ctx.setUserAttribute(attrName, picture);
        } else {
            persistentUser.setSingleAttribute(attrName, picture);
        }
    }
}

0 replies

gryffus · 2025-07-09T09:17:37Z

gryffus
Jul 9, 2025
Author

Hey! I quickly checked your code and I like it much more than my hacky version :)
I also love the idea about configurable photo size and extracting the image format directly from the $value API request.

Although I am not sure if the provider should be available for any generic OIDC provider, since it will really work only with AAD (or however they name it nowadays :D )

Thanks a lot!

It would be awesome if we could get this merged into the keycloak's microsoft provider!

If not, I will setup a repository with your improvements so others can contribute too.

1 reply

chrisbertagnolli Jul 9, 2025

Azure AD renamed to Entra ID ...hopefully they keep that a while cause renaming things is annoying :D.

I agree that I'd keep anything hard configured for Entra to be bound to the MS provider - if it's a built-in capability. Having a streamlined option for the MS Provider makes sense for those using it that way.

My case specifically I don't want to use the "social" provider from Keycloak, because I want to control everything without any assumptions from the "social" one. It's also not "social" (nit pick on the wording , it's Enterprise IDP not social accounts which are for public).

With the generic provider I can still do all the same SSO but also easy to do basic ACRS processing in the request; those can be static enough for a given IDP configuration in a realm that you can just slap them on the end of the Authorization URL in the config to force those conditions; then validate the response contains the right values in the acrs claim (e.g., c1 = phishing resistant MFA, c5 = compliant device, c15 = trustedCountryLocation).

The other reason is that I was thinking of making the API call generic input. Because there's possibilities to fetch data too out of like LDAP directories (such as Ping Directory) which have a REST API that can be called with OAuth.

Basically creating a generic type of "Fetch Attribute via API" that I could re-use across any provider just inputting what the API endpoint is, method, a few other parameters. Just haven't thought enough about what that would look like in the end but will start poking around at that idea.

Especially when there's disparate data across directories I could grab from the right place to get the right data.

E.g.,

I log in through Entra ID and get an Access Token scoped to my IDENTITY REST API audience (not Graph)

this is configured as an "Exposed API" on the application registration with a unique URI + scopes/roles

I grab Access Token during log in to call my IDENTITY API with {someParameters}

IDENTITY API fetches attributes from wherever it needs to (it might have to go to a database, another LDAP store, whatever to fetch the right information) or performs other custom business logic

IDENTITY API returns response with attributes

Keycloak store attribute

chrisbertagnolli · 2025-07-10T19:27:50Z

chrisbertagnolli
Jul 10, 2025

Something else I was just looking at yesterday / today was if user changes their image. I don't want to do a Force update on very log in due to JIT.

There is the ETag header returned which can be used in subsequent Graph requests with the If-None-Match header. This way there wouldn't be unnecessary fetching of the image content or writing to the database for no reason.

I just haven't had much luck making it work exactly as desired, but the idea is something like:

Get Etag from Graph and store in pictureEtag

SPI checks if pictureEtag is present, if yes then include in request to Graph If-None-Match + Etag

If user has not modified their image, 304 returned, skip picture update (no change)

If user has modified their image, 200 ok returned + new picture + new ETag, update picture and pictureEtag attribute.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

POC: Fetch Azure user avatar from Microsoft Graph API #41009

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 3 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

POC: Fetch Azure user avatar from Microsoft Graph API #41009

Uh oh!

Uh oh!

gryffus Jul 8, 2025

Replies: 3 comments · 1 reply

Uh oh!

chrisbertagnolli Jul 8, 2025

Uh oh!

Uh oh!

gryffus Jul 9, 2025 Author

Uh oh!

chrisbertagnolli Jul 9, 2025

Uh oh!

chrisbertagnolli Jul 10, 2025

gryffus
Jul 8, 2025

Replies: 3 comments 1 reply

chrisbertagnolli
Jul 8, 2025

gryffus
Jul 9, 2025
Author

chrisbertagnolli
Jul 10, 2025