immichにEntraIDログインする

今回の構成

ImmichはPodmanのコンテナで稼働
EntraID Freeのテナントを利用
Immichの名前解決とアクセスにはCloudflare One／WARPが必要
EntraIDは自分のテナントのユーザーだけが対象
LAN内の別アドレスではOAuthがうまく動作しないため、パスワードログインも残す

1
2
3
4
5
6
7
普段のアクセス
端末 → Cloudflare One／WARP → Immich
                              ↕ OIDC
                         Microsoft EntraID

LAN 内のアクセス
端末 →Immichのローカルアドレス → メールアドレス＋パスワード

Immich の設定画面では「OAuth」と表記されているが、ユーザー認証には OpenID Connect（OIDC）の利用になる。
Immich 公式：OAuth Authentication

プライベートなサーバーの認証

認証後にImmichのリダイレクト URI に戻るのはユーザーのブラウザになる。EntraIDからImmichへの直接の接続は必要ない。
ただ、ブラウザはEntraIDとImmichの両方に、Immich Server はEntraIDの認証エンドポイントにアクセスできる必要がある。
Microsoft 公式：OpenID Connect

このため、WARP接続中のブラウザから名前解決できて信頼できる証明書でHTTPS接続できることが前提になる。

EntraID のリダイレクト URI は localhost などの例外を除きHTTPSが必要になる。
Immich のドキュメントにローカルIPのHTTP例があっても、それをそのままEntraIDに適用できるとは限らないということで.localのようなケースはダメそう。 Microsoft 公式：リダイレクト URI の制約

EntraID にImmich用のアプリを登録

Microsoft Entra 管理センターで次の順に開く。

1
EntraID → アプリの登録 → 新規登録

項目	設定例
名前	`Immich`
サポートされているアカウントの種類	この組織ディレクトリ内のアカウントのみ（シングルテナント）
リダイレクト URI のプラットフォーム	Web
リダイレクト URI	`https://immich.example.com/auth/login`

登録後、概要画面から以下を控える。

アプリケーション（クライアント）ID
ディレクトリ（テナント）ID

リダイレクト URI の追加

アプリの「認証」で、Web のリダイレクト URI に以下を登録する。

1
2
3
https://immich.example.com/auth/login
https://immich.example.com/user-settings
https://immich.example.com/api/oauth/mobile-redirect

用途は順に

Web ログイン
既存アカウントへの OAuth のリンク
モバイルアプリへの認証結果の受け渡

モバイルでは HTTPS の中継先から app.immich:///oauth-callback に戻す。
Immich 公式：リダイレクト URI、モバイル用リダイレクト

ブラウザで実際に開くホスト名と、登録したURIをそろえる。別名でアクセスする場合は、そのURIも登録対象になる。

クライアントシークレットの作成

1
2
3
4
5
アプリの登録
 →Immich
 → 証明書とシークレット
 → クライアント シークレット 
 → 新しいクライアント シークレット

作成後に表示される 「値（Value）」 をImmichに設定する。「シークレット ID」ではないので注意。
値は作成直後にしか表示されないため、分からなくなった場合は新しいシークレットを作成する。
Microsoft 公式：クライアントシークレットの作成

利用するユーザーの割り当て

自分のユーザーだけに利用を限定するため、エンタープライズアプリケーション側で設定する。

1
2
3
4
5
EntraID
 → エンタープライズ アプリケーション
 → Immich
 → プロパティ 
 → 割り当てが必要ですか？ → はい

続いて、「ユーザーとグループ」から利用するユーザーを直接追加する。割り当てを必須にしたアプリには管理者による同意が必要になる。
Microsoft 公式：ユーザーとグループの割り当て

ただしGlobal Administrator は割り当て必須の制限の例外であることに注意。
管理者ユーザーでログインできただけでは、未割り当てユーザーの拒否を確認できない。アクセス制限の検証には通常ユーザーを使う必要がある。
Microsoft 公式：エンタープライズアプリケーションのプロパティ

OAuth profile does not have an email address：メールアドレスがない

このまま続けていて、エラーが発生したのでメモ。メールアドレスの設定をしておく必要がある。
発生したエラーは以下

1
OAuth profile does not have an email address

Immichの新規OAuthユーザー登録では、プロファイルの email が必要になる。
preferred_username がメールアドレスのような文字列でも、その値で email を代用する実装にはなっていない。
Immich ソース：認証サービス

まずImmichの Scope が openid email profile になっているか確認する。そのうえで、EntraIDのアプリ登録に email のオプション要求を追加する。

1
2
3
4
5
6
アプリの登録
  →Immich
  → トークン構成
  → オプションの要求を追加 
  → トークンの種類：ID
  → email を選択 → 追加

emailの要求

設定方法は Microsoft 公式：オプション要求の構成を参照。

現行の開発ブランチでは、ImmichはIDTokenに email があればそのclaimsを使い、なければUserInfoを問い合わせる。
どちらからもメールアドレスを取得できないと、新規登録に進めない。Immich ソース：OAuth リポジトリ

ということで、メールアドレスをちゃんと設定しておく必要がある。
EntraIDのユーザ設定でプロパティを見ると、連絡先情報項目に「メールアドレス」があることがわかる。
ここに使いたいメールアドレスを入れておく必要がある。

メールアドレス項目

Immichの OAuth を設定する

Immichの管理画面でAdministration → Settings のOAuth Authenticationで設定。
今回の構成で使う値は以下。

項目	設定値
Enabled	ON
Issuer URL	`https://login.microsoftonline.com/<TENANT-ID>/v2.0`
Client ID	アプリケーション（クライアント）ID
Client Secret	作成したシークレットの「値」
Scope	`openid email profile`
ID Token Signed Response Algorithm	`RS256`
Userinfo Signed Response Algorithm	`none`
Storage Label Claim	`preferred_username`
Button Text	`Login with EntraID`
Auto Register	ON
Auto Launch	OFF
Mobile Redirect URI Override	有効にして下記 URI を指定
Mobile Redirect URI	`https://immich.example.com/api/oauth/mobile-redirect`

設定項目と標準値は Immich 公式：OAuth の有効化を参照。画面によって署名アルゴリズムの項目名は異なる。

Issuer URL の <TENANT-ID> は実際のテナント ID に置き換える。EntraIDの管理画面を見ればわかるのでそちらを参照。
Discovery 文書の URL は次になる。

1
https://login.microsoftonline.com/<TENANT-ID>/v2.0/.well-known/openid-configuration

今回はシングルテナントなので、common や organizations ではなく、テナント ID を明示する。Microsoft 公式：OIDC の構成文書

OAuthで登録したユーザーをImmichの管理者にする

自動登録されたユーザは管理者になっていないので、管理者として使いたい場合は元の管理者ユーザでログインして管理者権限を付与する必要がある。
管理者でログインして「管理」→「ユーザー」→「対象のユーザー」→「編集」

ユーザ設定

OAuthで登録したユーザーのパスワードログイン

OAuthで登録したユーザーはパスワードログインが出来ない状態なので、ローカル環境からログインするためにパスワードログインできるように設定する。
元の管理者ユーザーでログインしたうえで「管理」→「ユーザー」→「対象のユーザー」→「パスワードをリセット」を実行すると、パスワードリセットしたうえでランダムパスワードが提示されるのでこれを使ってパスワードの再設定を行う。

ログイン画面

ログイン画面にOAuthログイン用の「Login with EntraID」を追加した形になりました。