Immich has supported OAuth/OIDC for a while now and with Authentik already running as the SSO provider for the homelab it made sense to wire them together. What looked like a twenty minute job turned into an afternoon once the certificate trust issues and a couple of Authentik provider gotchas got involved. This post documents what actually happened.

The Environment

The homelab internal domain is discworld.network. All internal services run behind Traefik on docker1, a Proxmox VM. TLS is handled by an internal CA so every container that makes outbound HTTPS calls needs the root cert in its trust store. Authentik is bound to a Samba AD LDAP source for user accounts. Immich is exposed internally at photos.ankh-morpork.discworld.network.

Setting Up the Authentik Provider

In the Authentik admin interface, navigate to Applications > Applications and create a new application. The wizard steps through everything in one flow.

For the provider type, select OAuth2/OpenID Connect. The important settings on the provider configuration step are:

• Add all three redirect URIs as Strict: https://photos.ankh-morpork.discworld.network/auth/login, https://photos.ankh-morpork.discworld.network/user-settings, and app.immich:///oauth-callback. That last one is required for the iOS and Android apps to work. If you expose Immich on multiple domains, add the equivalent URIs for each.
• Select a signing key. Without one, Authentik defaults to HS256 and Immich will reject the tokens.
• Leave the encryption key blank. This one caught me out. If an encryption key is set, Authentik issues a JWE token rather than a plain JWT, and Immich has no JWE decryption support. The error in the logs is JWE decryption is not configured which is accurate but not immediately obvious as a provider configuration problem.

After submitting, open the provider and note the Client ID, Client Secret, and the OpenID Configuration Issuer URL. The issuer URL ends with a trailing slash and it needs to be included.

Trusting the Internal CA in Immich

Immich is Node.js. When it fetches the OIDC discovery document from the Authentik issuer URL it makes an HTTPS connection, and that connection will fail if the CA that signed Authentik’s TLS certificate is not trusted. The internal CA root needs to be in the Node trust store.

The environment variable for this is NODE_EXTRA_CA_CERTS. Add the following to the immich-server service:

volumes:
  - /docker/traefik/discworld-root.crt:/usr/local/share/ca-certificates/discworld-root.crt:ro

environment:
  - NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/discworld-root.crt

This is the same root cert that gets mounted into every other container in the stack that makes internal HTTPS calls, so it fits the existing pattern.

Configuring OAuth in Immich

In Immich, go to Administration > Settings > OAuth Authentication and fill in:

• Issuer URL: the OpenID Configuration Issuer from the Authentik provider
• Client ID and Client Secret: from the Authentik provider
• Scope: openid email profile

Save and the button appears on the login page. Auto Launch is worth enabling once everything is confirmed working as it skips the Immich login page and redirects straight to Authentik. If you need to get back to the local login, ?autoLaunch=0 appended to the URL bypasses it.

The Email Problem

First login after getting TLS sorted gave a different error: OAuth profile does not have an email address. Immich requires an email claim in the OIDC token. Authentik pulls user attributes from LDAP, but the mail attribute on the Samba AD user object had never been populated.

The fix is straightforward:

samba-tool user edit <username>

This opens the full user object in the editor. Add or update the mail attribute, save, then force an LDAP sync in Authentik under Directory > LDAP Sources. After the sync, retry the login and Immich creates the user account with the email from the token.

Worth checking all user accounts that will use Immich before they try to log in. It is easier to populate the attribute in bulk than to debug it one user at a time.

Errors Worth Knowing About

Three errors came up during this setup:

TypeError: fetch failed on OAuth discovery means Immich cannot reach the Authentik OIDC endpoint. Almost always a TLS trust problem. Check NODE_EXTRA_CA_CERTS is set and pointing at the right cert.

invalid_client is a Client ID or Client Secret mismatch. Double-check what is configured in Immich against the Authentik provider. The secret is only shown once in Authentik so it is easy to have an incorrect copy.

JWE decryption is not configured means an encryption key is set on the Authentik provider. Remove it. Only the signing key should be set.

One Thing to Be Aware Of

Authentik only uses OIDC claims to populate Immich user fields at account creation time. Changes made in Samba AD afterwards, email updates, name changes, do not sync to Immich automatically. The Immich user record is written once on first login and then left alone. Updating it afterwards is a manual change inside Immich.