> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OIDC 認証

> Kubernetes デプロイで、ユーザーが OpenID Connect プロバイダー経由でログインできるようにします。

OIDC ログインは、各 Ayakaleaf Pro Pod 内の **web** サービス（`authentication` モジュール）が処理します。バックグラウンドジョブや別の Pod はありません。プロバイダー側（クライアント、リダイレクト URI、管理者クレーム）は Toolkit と同じなので、まず [OIDC 認証](https://ayakaleaf-pro.mintlify.site/ja/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md) に従って OpenID プロバイダー（OP）を設定し、その値を以下の手順で Kubernetes に設定します。

### 各処理の実行場所

| | |
| - | - |
| サービス | web、すべての Ayakaleaf Pro Pod 内。設定は web の起動時に読み込まれます |
| Pod → OP | `OVERLEAF_OIDC_TOKEN_URL` と `OVERLEAF_OIDC_USER_INFO_URL`、ログインごと |
| ブラウザ → OP | `OVERLEAF_OIDC_AUTHORIZATION_URL`、ログアウト時は `OVERLEAF_OIDC_LOGOUT_URL` |
| OP → Overleaf | なし：OP はブラウザをリダイレクトで戻すだけです |
| ログイン状態 | Redis 内のセッション。すべてのレプリカで共有されます |
| 定期ジョブ | なし |

### 設定

**1. OP に Overleaf を登録する**

`OVERLEAF_SITE_URL` から組み立てた次のアドレスを OP で許可します。

| 用途 | URI |
| - | - |
| リダイレクト URI（ログイン） | `${OVERLEAF_SITE_URL}/oidc/login/callback` |
| ログアウト後のリダイレクト URI | `${OVERLEAF_SITE_URL}` |
| 既存アカウントのリンク後のログアウト後リダイレクト URI | `${OVERLEAF_SITE_URL}/user/settings` |

5 つの URL は、[ディスカバリードキュメントで値を確認する](https://ayakaleaf-pro.mintlify.site/ja/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md#finding-the-values-with-the-discovery-document) の説明に従って OP のディスカバリードキュメントから確認できます。

**2. ConfigMap に設定を追加する**

`overleaf-env`（`30-config.yaml`、[複数のレプリカ](https://ayakaleaf-pro.mintlify.site/ja/on-premises/configuration/kubernetes/horizontal-scaling.md) の場合は `60-config.yaml`）に追加します。

```yaml title="30-config.yaml (additions)" wrap theme={null}
  EXTERNAL_AUTH: oidc
  OVERLEAF_OIDC_PROVIDER_ID: authentik
  OVERLEAF_OIDC_PROVIDER_NAME: Authentik
  OVERLEAF_OIDC_IDENTITY_SERVICE_NAME: Log in with Authentik
  OVERLEAF_OIDC_ISSUER: https://authentik.example.com/application/o/overleaf/
  OVERLEAF_OIDC_AUTHORIZATION_URL: https://authentik.example.com/application/o/authorize/
  OVERLEAF_OIDC_TOKEN_URL: https://authentik.example.com/application/o/token/
  OVERLEAF_OIDC_USER_INFO_URL: https://authentik.example.com/application/o/userinfo/
  OVERLEAF_OIDC_LOGOUT_URL: https://authentik.example.com/application/o/overleaf/end-session/
  OVERLEAF_OIDC_CLIENT_ID: <Client ID>
  OVERLEAF_OIDC_USER_ID_FIELD: username
  OVERLEAF_OIDC_IS_ADMIN_FIELD: groups
  OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE: Admins
  OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN: "true"
```

`EXTERNAL_AUTH` にはスペース区切りのリストを指定します（例：`ldap oidc`）。すべての `OVERLEAF_OIDC_*` 設定については [環境変数](https://ayakaleaf-pro.mintlify.site/ja/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md#environment-variables) を参照してください。クライアントシークレット以外はすべて ConfigMap に設定します。

> [!WARNING]
>
> `"true"` と `"false"` は引用符で囲んでください。ConfigMap には文字列しか保持できません。`""` に設定したキーは、キーが存在しない場合と同じではありません。`OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS: ""` は初回ログイン時のアカウント作成を無効にしますが、キーを省略するとすべてのドメインが許可されます。

**3. クライアントシークレットを Secret に設定する**

```bash theme={null}
kubectl -n overleaf patch secret overleaf-secrets --type merge \
  -p '{"stringData":{"OVERLEAF_OIDC_CLIENT_SECRET":"<Client Secret>"}}'
```

**4. プライベート CA を信頼する（任意）**

OP の証明書が独自の CA によるものである場合は、その CA を `/var/lib/overleaf/certs` にマウントされる Secret `overleaf-certs` に追加し（[証明書とその他のファイル](https://ayakaleaf-pro.mintlify.site/ja/on-premises/configuration/kubernetes#証明書とその他のファイル) を参照）、Node.js にそのパスを指定します。

```yaml theme={null}
  NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem
```

**5. 適用して再起動する**

```bash theme={null}
kubectl apply -f 30-config.yaml
kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
kubectl -n overleaf rollout status deployment/overleaf
```

次に、すべての Pod がトークンエンドポイントに到達できることを確認します。これを呼び出すのはブラウザではなく Pod なので、ファイアウォールや DNS の問題はここでしか表面化しません。

```bash theme={null}
for p in $(kubectl -n overleaf get pod -l app=overleaf -o name); do   # app=overleaf-ha for several replicas
  kubectl -n overleaf exec "$p" -- curl -sS -o /dev/null -w "$p %{http_code}\n" \
    https://authentik.example.com/application/o/token/
done
```

何らかの HTTP ステータス（GET の場合は `405`）が返ればエンドポイントに到達できています。`000` の場合は到達できていません。

### 複数のレプリカ

追加の作業は不要です。ログインの `state` 値とログアウトに使用する ID トークンは Redis 上のセッションに保持されるため、コールバックはどのレプリカが受け取っても機能します。

### Kubernetes でのテスト結果

goauthentik を OP として使用し、Kubernetes 1.37 上で HAProxy の背後に 3 つのレプリカを配置した構成で、OIDC のエンドツーエンドテストに合格しました（35 ケース）。対象は、ログインと OP 経由のログアウト、グループ・メール・単一の値による管理者マッピングとマッピングなしの場合、ログインごとの名前と管理者フラグの更新、アカウントのリンクとリンク解除、OIDC アカウントのパスワードリセットとパスワード変更、停止されたアカウント、`OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`、`OVERLEAF_DISABLE_LOCAL_LOGIN`、そして OIDC とパブリックアクセスの併用です。

### Q\&A

> [accordion] ログインが「Unable to verify authorization request state」で失敗する
>
> \*\*回答：\*\*ブラウザがコールバック時にセッション Cookie を送り返していません。Kubernetes でよくある原因は次のとおりです。
>
> * `OVERLEAF_SECURE_COOKIE` が設定されているのに、ユーザーが通常の HTTP でサイトを開いているため、ブラウザが Cookie を保存しない。`OVERLEAF_SECURE_COOKIE` はどんな値でも（`"false"` であっても）セキュア Cookie を有効にします。代わりにキーを削除してください。
> * `OVERLEAF_SITE_URL` とは別のアドレスでサイトを開いている。
> * HTTPS の背後で、Ingress やロードバランサーが `X-Forwarded-Proto: https` を送っていない、またはそのアドレスが `OVERLEAF_TRUSTED_PROXY_IPS` に含まれていない。

> [accordion] ログインが失敗した理由はどこで確認できますか？
>
> **回答：**`kubectl logs` ではなく、そのリクエストを処理した Pod の web ログで確認できます。
>
> ```bash theme={null}
> kubectl -n overleaf exec deploy/overleaf -- grep -i oidc /var/log/overleaf/web.log | tail
> ```
>
> 複数のレプリカがある場合は、各 `overleaf-N` を確認してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.