Skip to content

docs: add Immich OIDC integration guide #98

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
demsking wants to merge 1 commit into
base: main
Choose a base branch
from
+84 −0
Open

docs: add Immich OIDC integration guide #98

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 84 additions & 0 deletions src/content/docs/docs/integrations/immich.mdx
View file
Open in desktop

@steveiliop56 steveiliop56 Jun 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add the link to the astro.config.mjs file so that it can be displayed in the documentation ; ). Check the example with Beszel https://github.com/tinyauthapp/docs/blob/main/astro.config.mjs#L125-L134.

Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
---
title: Immich
description: Use the Tinyauth OpenID Connect provider to authenticate users with Immich.
---

import { Tabs, TabItem } from '@astrojs/starlight/components';

[Immich](https://immich.app/) is a self-hosted photo and video backup solution. By integrating Tinyauth as an OpenID Connect provider, you can centralize authentication and offer single sign-on (SSO) for your Immich users.

## Requirements

- A running instance of Immich
- A Tinyauth instance
- HTTPS configured for both services

:::caution
You will need to run Tinyauth with HTTPS to use it as an OpenID Connect provider.
:::

## Tinyauth Configuration

First, generate an OIDC client for Immich in Tinyauth:

<Tabs>
<TabItem label="Docker">
```sh
docker run -i -t --rm ghcr.io/steveiliop56/tinyauth:v5 oidc create immich
```
</TabItem>
<TabItem label="Binary">
```sh
./tinyauth oidc create immich
```
</TabItem>
</Tabs>
Comment on lines +24 to +35

@steveiliop56 steveiliop56 Jun 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any chance we could also add the browser form?

  <TabItem label="Browser">
    <CreateOidcClientTool />
  </TabItem>

Make sure to import it with import CreateOidcClientTool from "../../../../components/create-oidc-client-tool.astro";.


From the output, keep the generated client ID and client secret.

Now, configure Tinyauth using environment variables:

```sh
TINYAUTH_OIDC_PRIVATEKEYPATH=/path/to/private/key.pem
TINYAUTH_OIDC_PUBLICKEYPATH=/path/to/public/key.pem
TINYAUTH_OIDC_CLIENTS_IMMICH_CLIENTID=client-id
TINYAUTH_OIDC_CLIENTS_IMMICH_CLIENTSECRET=ta-client-secret
TINYAUTH_OIDC_CLIENTS_IMMICH_TRUSTEDREDIRECTURIS=https://immich.example.com/auth/login,https://immich.example.com/user-settings,https://immich.example.com/api/oauth/mobile-redirect

@coderabbitai coderabbitai Bot Jun 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Check Immich's official documentation or codebase for OAuth mobile redirect URI configuration

# Search for OAuth/OIDC redirect configuration in Immich docs
rg -i -C5 'oauth.*redirect|redirect.*uri|app\.immich' --type=md

# Look for mobile OAuth implementation or configuration examples
rg -i -C5 'mobile.*oauth|oauth.*mobile|app\.immich:\/\/\/' --type=md

Repository: tinyauthapp/docs

Length of output: 213

🌐 Web query:

Immich OAuth mobile redirect URI app.immich:/// configuration

💡 Result:

The official OAuth redirect URI for the Immich mobile application is app.immich:///oauth-callback [1][2]. The three forward slashes are required to ensure the path is correctly parsed by the mobile operating systems [3]. If your OAuth provider does not support custom schemes like app.immich:///, Immich provides a mechanism to use a standard HTTP/HTTPS URL as an override [1][2]. To configure this alternative: 1. Use the built-in Immich endpoint, which is located at /api/oauth/mobile-redirect [1][2]. This endpoint is specifically designed to forward requests to the required app.immich:///oauth-callback scheme [1][2]. 2. Whitelist this HTTP/HTTPS endpoint (e.g., https://your-immich-domain.com/api/oauth/mobile-redirect) in your OAuth provider settings [1][2]. 3. In your Immich OAuth settings, enable the Mobile Redirect URI Override option and enter the full URL of this endpoint into the Mobile Redirect URI field [1][4].

Citations:

🏁 Script executed:

#!/bin/bash
set -euo pipefail
# Show the relevant portion of the docs around the cited lines
nl -ba src/content/docs/docs/integrations/immich.mdx | sed -n '35,75p'

Repository: tinyauthapp/docs

Length of output: 103

🏁 Script executed:

#!/bin/bash
set -euo pipefail
# Print relevant range with line numbers using cat -n if available; fallback to sed-only
if command -v cat >/dev/null 2>&1 && cat -n src/content/docs/docs/integrations/immich.mdx >/dev/null 2>&1; then
  cat -n src/content/docs/docs/integrations/immich.mdx | sed -n '35,75p'
else
  sed -n '35,75p' src/content/docs/docs/integrations/immich.mdx
fi

Repository: tinyauthapp/docs

Length of output: 2091

Add the primary mobile redirect URI to TINYAUTH_OIDC_CLIENTS_IMMICH_TRUSTEDREDIRECTURIS

src/content/docs/docs/integrations/immich.mdx documents that the mobile app’s redirect URI is app.immich:///oauth-callback (primary) and only uses https://immich.example.com/api/oauth/mobile-redirect as a fallback override. But the trusted redirect allowlist example only includes the override URL (line 46) and omits app.immich:///oauth-callback—so the common/default mobile flow will fail unless the override path is used.

Either include app.immich:///oauth-callback in the trusted list alongside the override, or change the note/example to match an “override-only” setup.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/content/docs/docs/integrations/immich.mdx` at line 46, The example
trusted-redirects env var TINYAUTH_OIDC_CLIENTS_IMMICH_TRUSTEDREDIRECTURIS is
missing the primary mobile URI (app.immich:///oauth-callback) and only shows the
fallback override; update the example by adding app.immich:///oauth-callback to
the comma-separated list alongside
https://immich.example.com/api/oauth/mobile-redirect, or alternatively change
the explanatory note to explicitly state this example is for an "override-only"
setup—edit the line containing TINYAUTH_OIDC_CLIENTS_IMMICH_TRUSTEDREDIRECTURIS
in immich.mdx accordingly.

TINYAUTH_OIDC_CLIENTS_IMMICH_NAME=Immich
```

:::note
Immich uses multiple redirect URIs depending on your clients:
- Web login: `https://immich.example.com/auth/login`
- Account linking in web UI: `https://immich.example.com/user-settings`
- Mobile app: `app.immich:///oauth-callback`

If your OAuth provider cannot accept the `app.immich:///oauth-callback` custom scheme, Immich supports using `https://immich.example.com/api/oauth/mobile-redirect` as a mobile redirect override.

@steveiliop56 steveiliop56 Jun 10, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tinyauth shouldn't have any issues with the app.immich one but let's just use the generic https://immich.example.com/api/oauth/mobile-redirect to avoid any confusion.

:::

Restart your Tinyauth instance after applying the configuration.

## Immich Configuration

In Immich, go to *Administration* -> *Settings* -> *Authentication Settings* and enable OAuth. Use the following values:

| Field | Value |
| - | - |
| Enabled | `true` |
| Issuer URL | Your Tinyauth URL, for example `https://tinyauth.example.com` |
| Client ID | The client ID generated in the previous step |
| Client Secret | The client secret generated in the previous step |
| Scope | `openid email profile` |
| Button Text | Optional, e.g. `Login with Tinyauth` |
| Auto Register | Optional, usually `true` for first login provisioning |
| Auto Launch | Optional, enable only if you want to skip the default Immich login page |

:::note
Immich performs OIDC discovery from the issuer URL. You can provide either:
- `https://tinyauth.example.com`
- `https://tinyauth.example.com/.well-known/openid-configuration`
:::

Save the settings, then open the Immich login page and use the OAuth button to test the flow.

If authentication is successful, users are redirected to Tinyauth, sign in there, and are returned to Immich as authenticated users.