Upload user avatars and store in attributes as URL instead of base64 encoded data

[drpetersen]

Background

There is an issue (#2631) ongoing about how to allow users to upload their own avatars. Basic functionality seems to work with the file prompt field (#3156) and the AUTHENTIK_AVATARS=attributes.avatar,… setting, but a few problems still remain to be solved.

While a file cropper seems nice to have, the show-stopper for me is having to store image files as base64-encoded strings directly in the user profile (attributes). Even with reasonably sized image files, this leads to performance issues (e.g., see #5942), makes it more cumbersome to edit the user profile in the admin interface (the YAML is hundreds of lines long), and may cause problems with proxying authentik-ated web applications (with avatars of ca. 100 KBytes, I received error 500 codes from nginx until I found out that I had to increase proxy buffers in size); even then, the /outpost.goauthentik.io/sign_out redirect for proxied applications errored out because query strings (presumably containing user profile data) became too long (I suppose).

My proposed solution is a workaround for this problem which allows the user to upload an image file as a user avatar, stores this image file in your authentik server's /media/ subdirectory under a random (non-guessable) file name, and stores the URL of this image file in the avatar profile attribute of the user.

This way, arbitrarily large image files (the maximum is configurable) can be used as a user avatar without cluttering the profile.

Credits: The helpful comments in issue #4283 as well as the above-mentioned issues pointed me in the right direction.

UPDATE 2026-01-16: The original code no longer works as of authentik 2025.12. I updated this post to include the fix provided in the discussion below. Thanks to all who contributed, in particular to @krom, @WilliamSoderberg, and to @nicedevil007 for wrapping this up to a complete working policy script.

Procedure

• Include the attributes.avatar option in your AUTHENTIK_AVATARS environment variable (see here).

• Make sure the /media/ directory in your authentik-server container is writable by authentik and persistent. Avatar image files will be stored in a sub-directory /media/user-avatars/ (auto-created if not present) /media/public/user-avatars/ which needs to be created with appropriate permissions.

• Create a custom File prompt, e.g., default-user-settings-field-avatar, with field key attributes.avatar; adjust the Order (not visible in the screenshot) as appropriate (e.g., 205)
  

• Create a custom checkbox prompt, e.g., default-user-settings-field-avatar-reset, with field key attributes.avatar_reset; adjust the Order (e.g., to 206). The user can check this box to delete the current avatar file.

• Create a custom expression policy, e.g., default-user-settings-avatar-authorization with this expression the expression provided in @nicedevil007 's comment below. This is where the uploaded file is saved, any previous file is removed, and the new URL is prepared to be stored in the user profile. Make sure to configure AK_DOMAIN, MAX_UPLOAD_SIZE and ACCEPTED_FILE_TYPES to your needs.

• Update your default-user-settings prompt stage (or a new, custom prompt stage, if you prefer) so that the default-user-settings-field-avatar and default-user-settings-field-avatar-reset prompts are included in the Fields selection (make sure not to accidentally unselect the default profile fields) and the default-user-settings-avatar-authorization is included in the Validation Policies (along with the stock default-user-settings-authorization policy).
  

• Done! Now your users should be able to customize their own avatar images. (Don't forget to re-create your docker container after updating environment options.)

Open Questions/Issues

• I am not sure if I am simply missing something, and this would have been possible with much less effort (at this time). And maybe there are more efficient ways to achieve this.
• I have not quite thought through the security implications of exposing the user avatar via a world-readable URL, protected only by its random name (a UUID). My intuition is that anyone who can see the avatar would also be allowed to know its URL, as they could copy the image file anyway, even if its download was protected. But maybe the name should be generated in a more cryptographically secure way, and/or the avatar URL should be behind authentik's access control.
• This solution relies on some Python packages being available in expression policies, which might not be the same in future authentik versions.
• The default-user-settings-avatar-authorization should catch and reject too large files, but there seems to be an implicit limit where things start to go wrong. Specifically, I had problems with large (but still reasonably sized) files: After uploading a files of 1 – 2 MB, I get no error message, but the UI switches from direct display of profile fields to a button "Open settings", which then opens the profile on a separate page, and when I hit the "Continue" button, the upload seems to have failed (silently). I don't know where to begin debugging this. -- EDIT: This is solved, I forgot to increase the client_max_body_size setting in my nginx reverse proxy. 🙄
• Finally, I was not sure if this is the right place to put this. Issue Custom avatar pictures #2631 seems to be headed in a different direction, issue File Prompt Placeholder Not Working #4283 had already been closed. So, I put this here in the hope that someone might find it helpful. 😄

[thefeli73]

for me it did not in fact autocreate the user-avatars/ folder, i had to create it manually for this to work. Great guide otherwise :D

[Elara6331]

Thank you so much for this, it works very well! I just had to add the following if statement to the beginning of remove_old_avatar_file() to make this policy work during enrollment when there is no existing user yet:

if not request.user.is_authenticated:
  return

[masterwishx]

This works for normal usage, but when impersonation is used, it breaks things pretty badly.

can you explain ?

[dasunsrule32]

Yeah, enable it and try to impersonate. It's been awhile since I've checked it, but if I recall correctly, you can never leave impersonation with it enabled. You have to actually completely logout and back in.

[masterwishx]

Sorry but what this mean impersonate?

[masterwishx]

OK i got what you mean , Thanks

[masterwishx]

Yeah, enable it and try to impersonate. It's been awhile since I've checked it, but if I recall correctly, you can never leave impersonation with it enabled. You have to actually completely logout and back in.

yep i got access denied

[Aetherinox]

This guide works great. Only thing to note is as @thefeli73 said, the user-avatars folder is not automatically created and if you attempt to upload an avatar, it'll throw an error until you create the folder and assign proper perms / owner.

mkdir -p /authentik/media/user-avatars/
chown -R 1000:1000 /authentik/media/user-avatars/
chmod -R 644 /authentik/media/user-avatars/

Obviously adjust chown owner to whatever you need. I got the avatar upload to work with permission 644

And if you have multiple sources for avatars, stick the custom upload to the front, otherwise initials will have priority. Mine didn't work until I flipped the order.

attributes.avatar,gravatar,initials

[masterwishx]

cant add validation policies , after success got blank again

[masterwishx]

seems its added but not shown in update prompt stage

[wrenix]

Could we get an blueprint ?
For a more stable setup. Reproducible and so on.

[250king]

I am thinking is it possible that we can make a expression to upload the image to some storage service such as AWS S3?
But there still some problem need to solve: how to use the non-standard library?

[rissson]

import boto3
client = boto3.client("s3")

and go from there with https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html

[250king]

Is the library included in Authentik defaultly?
In fact, I am using Alibaba Cloud oss, so I need oss2 or requests.

[rissson]

requests is included, boto3 as well. You can check https://github.com/goauthentik/authentik/blob/main/poetry.lock for a list of included dependencies and versions.

[250king]

Thanks! In fact Alibaba Cloud OSS support S3 protocol. boto3 is enough. I will try to write a expression.

[UnInfamous]

Authentik's documentation in the Background surrounding AUTHENTIK_AVATARS=attributes.avatar,…, is no longer there.

I followed these steps and confirmed again that I followed this setup exactly (minus different names for the policy/promts), however, it does show "Avatar image" as seen below:

I don't see the image on the profile within Authentik. I can upload the file (and it successfully goes to /user-avatars/), also confirmed ordering attributes.avatar to be first of the list of types of avatar images. I've also tried different PNGs & JPGs. Other than adding Apps/Providers, I haven't really changed much of anything within Authentik.

I'm new to identity providers, so any help on what I might have missed would be great.

[nikolaioak]

It looks like the avatar settings were removed in this commit: 96554de. The instructions for avatar options are here now, but I don't see anything regarding the environment variable previously included in the install config section. I was going to give this method a stab today to see how it works, but the removal of the environment variable has me wondering if this method is no longer supported.

[nikolaioak]

Regardless this actually worked for me, set it up in a few minutes. Avatar is displaying as expected - potentially a bit warped based on the aspect ratio of the picture. I would verify you edited the authorization expression policy properly with your environment's details.

[wrenix]

Is there a blueprint to add the Prompt and so on for a automatic and reproduce able setup

[drashna]

the humanize python package appears to no longer be available in the 2025.8.0-rc5 preview.

[krom]

My temporary workaround for missing humanize module is there:

1. comment import of module

# from humanize import naturalsize

2. add own implementation of naturalsize

def naturalsize(value, binary=False, format="%.1f"):
    """
    Convert a size in bytes into a human-readable format.

    :param value: size in bytes
    :param binary: if True, use 1024-based units (KiB, MiB), otherwise 1000-based (KB, MB)
    :param format: number format string (default "%.1f")
    :return: string like "10.5 MB"
    """
    units = ["B", "KB", "MB", "GB", "TB", "PB", "EB"]
    if binary:
        step = 1024.0
        units = ["B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB"]
    else:
        step = 1000.0

    size = float(value)
    for unit in units:
        if abs(size) < step:
            return (format % size).rstrip("0").rstrip(".") + " " + unit
        size /= step
    return (format % size).rstrip("0").rstrip(".") + " " + units[-1]

[SolninjaA]

Thank you SO much.

[KiyoNetcat]

fyi this now seems to be outright broken on 2025.12
even after adjusting the paths in the user and script to account for the new storage changes, the avatar fails to load with a 404 error
looking at the application icons, apparently there's now a token query parameter for it to load the icon, and if that parameter is missing, it returns a 404 for those icons, despite their presence if you included the token.

[l-e-e-o]

I actually found that it sometimes can be useful to have the base64 version available as well. So, I stored the generated URL inattributes.avatar-url. This also makes it so the icon is shown in authentik as well. All modifications:

...

# 5. Delete old file and set new signed URL
        avatar_overwritten = True
        remove_old_avatar_file()
        prompt_data["attributes"]["avatar-url"] = generate_signed_url(avatar_filename)
        prompt_data["attributes"]["avatar-base64"] = avatar_base64

# Handle avatar reset
if "avatar_reset" in prompt_data.get("attributes", {}):
    del prompt_data["attributes"]["avatar_reset"]
    
    # If a new avatar was uploaded, the previous one is already deleted
    if not avatar_overwritten:
        remove_old_avatar_file()
        prompt_data["attributes"]["avatar"] = None
        prompt_data["attributes"]["avatar-url"] = None
        prompt_data["attributes"]["avatar-base64"] = None
        ak_message("User avatar has been deleted.")

return True

I then created three property mappings:

Data-URL Avatar Mapping (Scope: avatar)

return {"avatar": request.user.attributes.get("avatar", None)}

Base64 Avatar Mapping (Scope: avatar)

return {"avatar": request.user.attributes.get("avatar-base64", None)}

URL-based Avatar Mapping (Scope: avatar)

return {"avatar": request.user.attributes.get("avatar-url", None)}

This way I can just pick the right binding for each application/provider.

[masterwishx]

Do you need to change also : User settings - > Avatars?

[l-e-e-o]

Yeah I changed it to attributes.avatar,gravatar,initials and authentik is able to show the uploaded avatars.

[masterwishx]

Thanks, this is what I have already

[phil-lipp]

I actually found that it sometimes can be useful to have the base64 version available as well. So, I stored the generated URL inattributes.avatar-url. This also makes it so the icon is shown in authentik as well. All modifications:
...
This way I can just pick the right binding for each application/provider.

Indeed very handy - thank you so much @l-e-e-o!

[ZEROX7]

is it me or does that make authentik use much more ram? rasb pi 4 4gb crashes after 5min if i upload my avatar
removing my avatar fixes that

[VGHS-lucaruby]

Just checked my logs for you, I got around to finally fixing this on the 10th @ ~12:00. Seems that mostly only the cache increased. Though Authentik is now using the most RAM it has in the last year. This coincided with the instance updating to 2026.2.0 So this is more likely the cause for your RAM increase if you are using this version. Did also give a restart and the RAM increase stuck. Seems to be using ~500MB more now.

Edit: Just looked up the issues page and see this is a bug and fixed in 2026.2.1
#20537

[ZEROX7]

im running 2026.2.1 with no avatar uploaded

wehn i rember right i saw server and worker at least 500mb higher after i uploaded my avatar and waited 2min
and i dont know if it would get worse wehn other users on my authentik settup will upload avatars

[VGHS-lucaruby]

Decided to upgrade and test on my end for you.
Does seem to be something a little strange after uploading an avatar.

Don't have enough time to properly test but hopefully this can help you/someone investigate this a bit.
I would guess its something to do with 2026.2.x updates as this was not an issue with the same script on 2025.12.