Guide for Immich Oauth2 setup

[SPK44]

This setup uses immich.example.com:2283 as the expected domain name you are hosting immich on, and idm.example-auth.com:8544 for your kanidm instance. Replace with the appropriate URLs for your setup

Kanidm Setup

kanidm system oauth2 create immich "Immich" https://immich.example.com:2283
kanidm system oauth2 add-redirect-url immich https://immich.example.com:2283/auth/login
kanidm system oauth2 add-redirect-url immich https://immich.example.com:2283/user-settings
kanidm system oauth2 add-redirect-url immich app.immich:///oauth-callback
kanidm group create immich_users
kanidm group create immich_admins
kanidm group add-members immich_users immich_admins
kanidm group add-members immich_admins my_user
kanidm system oauth2 update-scope-map immich immich_users email profile openid
kanidm system oauth2 update-claim-map-join immich 'immich_role' csv
kanidm system oauth2 update-claim-map immich immich_role immich_admins admin
kanidm system oauth2 show-basic-secret immich

The final command will provide a secret to be input in the next step.

I'm not familiar or interested enough to setup a storage quota claim, but I assume it would be similar to the role claim, just with the GB quota, if you want that.

Immich Setup

Login as an admin, then click on the profile pic and "Administration".

Expand "Authentication Settings" and "Oauth", then enable "Oauth"

Here are the fields that need to be filled out, some might be defaults,

ISSUER_URL: https://idm.example-auth.com:8544/oauth2/openid/immich
CLIENT_ID: immich
CLIENT_SECRET: <the value from the kanidm step above>
TOKEN_ENDPOINT_AUTH_METHOD: client_secret_post
SCOPE: openid email profile
ID_TOKEN_SIGNED_RESPONSE_ALG: ES256
STORAGE LABEL CLAIM: preferred_username
ROLE CLAIM: immich_role

Note about HTTPS

It seems like the Immich project doesn't have a way to serve itself over an HTTPS connection, nor do they want to add the ability to do that. The answer seems to be using a reverse proxy. This isn't a problem for my setup, since I use oauth-proxy for external access anyway. (Side note, this article explains how to get the mobile app to work with a similar setup). If you just want to fulfill the HTTPS requirement for kanidm, then the official Immich docs provide more specific instructions and an nginx example configuration.

[willquill]

I just followed this today, 2025-12-19, and it worked! Thank you so much!

A few notes for anyone else doing this:

• For my use case, I wasn't going from "no oauth" to "Kanidm oauth". I was migrating from an existing oauth configuration that used Authentik. I'm migrating all services from Authentik to Kanidm.
• I recommend before starting this that you go to /admin/system-settings in Immich and click Export as JSON. Then if you get locked out of Immich with a failed oauth configuration, you can restart your Immich docker service using the backed up config file method.
• I'm still on an older Immich version, v1.135.3, and I did not have a "role claim" option. So there was nothing for me to configure there. When I upgrade Immich, I'll be sure to populate that correctly.
• The first time I did this and logged out of Immich, I went to login and I got an error that said something about a user already being mapped to my ID or something. Fortunately, I still had password access enabled, so I logged in with that, went to my user settings, and then went to OAuth > Unlink OAuth. Then I logged out and was able to successfully log in with OAuth. EDIT: I only had to do this because I was replacing a previous OAuth configuration, as noted in my first bullet point

I use Traefik to get to both Kanidm and Immich, and the HTTPS certificates for both Kanidm and Immich are provided by Traefik's ACME resolver with a DNS challenge.

[Weissnix4711]

thanks. just a little addition from my own experience:

• CLIENT_SECRET shouldn't strictly be necessary because immich can be a public client (supposedly). but for me it would internal error. no idea, don't really care.
• TOKEN_ENDPOINT_AUTH_METHOD client_secret_post works just fine.

[SPK44]

Thanks for the notes!

I also tried setting this up first without CLIENT_SECRET, but ran into the same problem you did.
As for the TOKEN_ENDPOINT_AUTH_METHOD, you are correct. I've updated the original guide to suggest that.