> ## 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 認証

<Info>
  この機能は [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep) によって開発されました。ここでは設定に関するドキュメントを提供します。
</Info>

### 設定

内部的には、Overleaf の OIDC モジュールは [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect) ライブラリを使用しています。OpenID Connect の設定で問題が発生した場合は、`passport-openidconnect` の README を読んで、どのような設定が想定されているかを把握しておくとよいでしょう。

OIDC 認証モジュールを有効にするには、環境変数 `EXTERNAL_AUTH` が必要です。この環境変数は、どの外部認証方式を有効にするかを指定します。この変数の値はリストです。リストに `oidc` が含まれている場合、OIDC 認証が有効になります。

例：`EXTERNAL_AUTH=ldap oidc`

OIDC 認証方式を使用する場合、ユーザーは ID プロバイダー（IdP）の認証サイトにリダイレクトされます。IdP がユーザーの認証に成功すると、Overleaf のユーザーデータベースで、次のような構造の `thirdPartyIdentifiers` フィールドを含むレコードが検索されます：

```text theme={null}
thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]
```

`externalUserId` は IdP サーバーから返されるプロファイル内のユーザー ID（`OVERLEAF_OIDC_USER_ID_FIELD` 環境変数を参照）と一致する必要があり、`providerId` は OIDC プロバイダーの ID（`OVERLEAF_OIDC_PROVIDER_ID` を参照）と一致する必要があります。

一致するレコードが見つからない場合は、IdP のユーザープロファイル内のメールアドレスと一致するプライマリメールアドレスを持つユーザーがデータベースで検索されます：

* そのようなユーザーが見つかった場合、`thirdPartyIdentifiers` フィールドが更新されます。
* 一致するユーザーが見つからず、JIT アカウント作成が無効になっていない場合は、IdP プロファイルのメールアドレスと `thirdPartyIdentifiers` を使用して新しいユーザーが作成されます。

どちらの場合も、そのユーザーは外部の OIDC ユーザーと「リンク」された状態になります。ユーザーは `/user/settings` ページで OIDC プロバイダーとのリンクを解除できます。

#### ディスカバリードキュメントで値を確認する

すべての OpenID プロバイダー（OP）は、`<issuer>/.well-known/openid-configuration` でディスカバリードキュメントを公開しています。値は手入力せず、ここからコピーしてください。1 文字でも間違えるとログインできなくなります。

<Steps>
  <Step title="ディスカバリー URL を確認する">
    OP は、Overleaf 用に作成したクライアント（プロバイダー）のページにこの URL を表示します。Authentik では、**Applications > Providers** を開いてプロバイダーを選択し、**OpenID Configuration URL** と **OpenID Configuration Issuer** を探します。

    <Frame caption="Authentik：プロバイダーのディスカバリー URL と issuer（テスト環境）">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-provider.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=e3cb5603d959665472b53e39b58b2775" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-provider.png" />
    </Frame>

    URL は通常、次のような形式です。

    * Keycloak: `https://keycloak.example.com/realms/<realm>/.well-known/openid-configuration`
    * Authentik: `https://authentik.example.com/application/o/<application-slug>/.well-known/openid-configuration`
  </Step>

  <Step title="値を読み取る">
    ブラウザーで URL を開くか、Overleaf サーバー上で次のコマンドを実行します。

    ```shell theme={null}
    curl -s https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration \
      | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, end_session_endpoint}'
    ```

    Authentik の応答は次のようになります。

    ```json theme={null}
    {
      "issuer": "https://authentik.example.com/application/o/overleaf/",
      "authorization_endpoint": "https://authentik.example.com/application/o/authorize/",
      "token_endpoint": "https://authentik.example.com/application/o/token/",
      "userinfo_endpoint": "https://authentik.example.com/application/o/userinfo/",
      "end_session_endpoint": "https://authentik.example.com/application/o/overleaf/end-session/"
    }
    ```

    Authentik では、プロバイダーのページの下の方にもこれらの URL が表示されます。

    <Frame caption="Authentik：プロバイダーのエンドポイント（テスト環境）">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-endpoints.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=55d130cbbbf27fd11aebafa1ab3f090c" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-endpoints.png" />
    </Frame>
  </Step>

  <Step title="`variables.env` にコピーする">
    | ディスカバリードキュメントのフィールド | 環境変数 |
    | - | - |
    | `issuer` | `OVERLEAF_OIDC_ISSUER` |
    | `authorization_endpoint` | `OVERLEAF_OIDC_AUTHORIZATION_URL` |
    | `token_endpoint` | `OVERLEAF_OIDC_TOKEN_URL` |
    | `userinfo_endpoint` | `OVERLEAF_OIDC_USER_INFO_URL` |
    | `end_session_endpoint` | `OVERLEAF_OIDC_LOGOUT_URL` |

    ```dotenv theme={null}
    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/
    ```
  </Step>

  <Step title="Overleaf から OP に到達できることを確認する">
    Overleaf はコンテナ内部からトークンエンドポイントと userinfo エンドポイントを呼び出すため、ブラウザーからだけでなく、コンテナ内からも OP に到達できる必要があります。

    ```shell theme={null}
    docker exec sharelatex curl -sS -o /dev/null -w "%{http_code}\n" \
      https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration
    ```

    `200` と出力されれば問題ありません。
  </Step>
</Steps>

<Warning>
  `issuer` は末尾のスラッシュも含めて正確にコピーしてください。Overleaf はこれを ID トークン内の issuer と 1 文字ずつ比較します。少しでも違いがあると、すべての OIDC ログインが次のエラーで失敗します。

  `{"message":{"message":"ID token not issued by expected OpenID provider."}}`

  Authentik では、issuer はアプリケーションごとに決まります（`.../application/o/<application-slug>/`）。authorize、token、userinfo の URL はすべてのアプリケーションで共通ですが、issuer は Authentik サーバーのアドレスではありません。
</Warning>

#### 環境変数

次の 5 つの必須変数の値は、OpenID プロバイダー（OP）の `.well-known/openid-configuration` エンドポイントを使用して確認できます（上記を参照）。

* `OVERLEAF_OIDC_ISSUER` <strong>（必須）</strong>
* `OVERLEAF_OIDC_AUTHORIZATION_URL` <strong>（必須）</strong>
* `OVERLEAF_OIDC_TOKEN_URL` <strong>（必須）</strong>
* `OVERLEAF_OIDC_USER_INFO_URL` <strong>（必須）</strong>
* `OVERLEAF_OIDC_LOGOUT_URL` <strong>（必須）</strong>

次の 2 つの必須変数の値は、OP の管理者から提供されます

* `OVERLEAF_OIDC_CLIENT_ID` <strong>（必須）</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>（必須）</strong>
* `OVERLEAF_OIDC_SCOPE`
  * デフォルト：`openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * OP の任意の ID。デフォルトは `oidc` です。
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * OP の名前。`/user/settings` ページの `Linked Accounts` セクションで使用されます。デフォルトは `OIDC Provider` です。
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * ログインページで使用される ID サービスの表示名（デフォルト：`Log in with $OVERLEAF_OIDC_PROVIDER_NAME`）。
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * OP の説明。`Linked Accounts` セクションで使用されます（デフォルト：`Log in with $OVERLEAF_OIDC_PROVIDER_NAME`）。
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * OP の説明内の `Learn more` の URL。デフォルトでは、説明に `Learn more` リンクは表示されません。
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * ユーザーのアカウントが OP とリンクされていない場合、`/user/settings` ページに OP を表示しません。デフォルトは `false` です。
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * この属性の値が、Overleaf で外部ユーザー ID として使用されます。デフォルトは `id` です。その他の妥当な値として、`email` と `username`（OIDC クレームの `preferred_username` に対応）があります。
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * OIDC 経由で認証するユーザーのジャストインタイム（JIT）アカウント作成を制限します。カンマ区切りのドメイン名のリストを設定すると、ユーザーのメールアドレスのドメインがリスト内のいずれかと一致する場合にのみ、新しいアカウントが作成されます。ドメインが一致しない場合は、管理者が OIDC ユーザーのメールアドレスを使用して、強力なランダムパスワードを設定するか、できれば `hashedPassword` フィールドをまったく持たない状態で、ユーザーアカウントを手動で作成する必要があります。ドメイン名の先頭に `*.` ワイルドカードを付けると、サブドメインにも一致させることができます。
    * 例：`name@example.com` や `name@math.example.com` のようなメールアドレスを持つユーザーに JIT アカウント作成を許可する場合：\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * 例：JIT アカウント作成を完全に無効にする場合：\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * `true` に設定すると、ログイン時にユーザーの `first_name` と `last_name` フィールドを更新し、`/user/settings` ページのユーザー詳細フォームを無効にします。
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` と `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * 両方の環境変数が設定されている場合、OP から返されたプロファイルに `OVERLEAF_OIDC_IS_ADMIN_FIELD` で指定された属性が含まれ、その値が `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` と一致するか、`OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` を含む配列（例：`groups` クレーム）である場合、ログイン処理で `user.isAdmin = true` に更新されます。それ以外の場合、`user.isAdmin` は `false` に設定されます。`OVERLEAF_OIDC_IS_ADMIN_FIELD` が `email` の場合は、属性 `emails[0].value` の値が一致の確認に使用されます。

OpenID プロバイダーのリダイレクト URL は `https://my-overleaf-instance.com/oidc/login/callback` です。

<Accordion title="variables.env ファイルのサンプル">
  ```dotenv title="variables.env" wrap theme={null}
  OVERLEAF_APP_NAME="Our Overleaf Instance"

  ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

  # Enables Thumbnail generation using ImageMagick
  ENABLE_CONVERSIONS=true

  # Disables email confirmation requirement
  EMAIL_CONFIRMATION_DISABLED=true

  ## Nginx
  # NGINX_WORKER_PROCESSES=4
  # NGINX_WORKER_CONNECTIONS=768

  ## Set for TLS via nginx-proxy
  # OVERLEAF_BEHIND_PROXY=true
  # OVERLEAF_SECURE_COOKIE=true

  OVERLEAF_SITE_URL=http://my-overleaf-instance.com
  OVERLEAF_NAV_TITLE=Our Overleaf Instance
  # OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
  OVERLEAF_ADMIN_EMAIL=support@example.com

  OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:support@example.com"}]
  OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]

  OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
  OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
  OVERLEAF_EMAIL_SMTP_PORT=587
  OVERLEAF_EMAIL_SMTP_SECURE=false
  # OVERLEAF_EMAIL_SMTP_USER=
  # OVERLEAF_EMAIL_SMTP_PASS=
  # OVERLEAF_EMAIL_SMTP_NAME=
  OVERLEAF_EMAIL_SMTP_LOGGER=false
  OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
  OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
  OVERLEAF_CUSTOM_EMAIL_FOOTER=This system is run by department x

  OVERLEAF_PROXY_LEARN=true
  NAV_HIDE_POWERED_BY=true

  #################
  ## OIDC for CE ##
  #################

  EXTERNAL_AUTH=oidc

  OVERLEAF_OIDC_PROVIDER_ID=oidc
  OVERLEAF_OIDC_ISSUER=https://keycloak.provider.com/realms/example
  OVERLEAF_OIDC_AUTHORIZATION_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/auth
  OVERLEAF_OIDC_TOKEN_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/token
  OVERLEAF_OIDC_USER_INFO_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/userinfo
  OVERLEAF_OIDC_LOGOUT_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/logout
  OVERLEAF_OIDC_CLIENT_ID=Overleaf-OIDC
  OVERLEAF_OIDC_CLIENT_SECRET=DoNotUseThisATGgaAcTgCcATgGATTACAagGtTCaGcGTAG
  OVERLEAF_OIDC_IDENTITY_SERVICE_NAME='Log in with Keycloak OIDC Provider'
  OVERLEAF_OIDC_PROVIDER_NAME=OIDC Keycloak Provider
  OVERLEAF_OIDC_PROVIDER_INFO_LINK=https://openid.net
  OVERLEAF_OIDC_IS_ADMIN_FIELD=email
  OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=overleaf.admin@example.com
  OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false
  ```
</Accordion>

## ステップバイステップ: goauthentik

ここでは、[goauthentik](https://goauthentik.io/) で動作確認済みのセットアップ手順を説明します。`https://overleaf.example.com` はご自身の `OVERLEAF_SITE_URL` に、`https://authentik.example.com` はご自身の Authentik のアドレスに置き換えてください。

<Steps>
  <Step title="プロバイダーを作成する">
    Authentik で **Applications > Providers** を開き、**New Provider** をクリックして **OAuth2/OpenID Provider** を選択し、**Next** をクリックします。

    * **Client Type**：`Confidential`。
    * **Redirect URIs**（**Protocol settings** の下）：`https://overleaf.example.com/oidc/login/callback` をマッチングモード `Strict` で追加します。
    * この時点で **Client ID** と **Client Secret** をコピーし、`OVERLEAF_OIDC_CLIENT_ID` と `OVERLEAF_OIDC_CLIENT_SECRET` に設定します。

    <Frame caption="Authentik：新しいプロバイダーの Client ID と Client Secret">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-create.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=f127a92eaf3063714e9af515fe97c263" alt="" width="1120" height="808" data-path="images/on-premises/oidc-authentik-create.png" />
    </Frame>

    <Warning>
      Authentik がクライアントシークレットを表示するのは、プロバイダーの作成中だけです。後から編集フォームで選択できるのは **Modify** のみで、これはシークレットを新しいものに置き換えます。
    </Warning>
  </Step>

  <Step title="アプリケーションを作成する">
    **Applications > Applications** を開いて新しいアプリケーションを作成し、名前とスラッグ（例：`overleaf`）を付けて、プロバイダーを選択します。スラッグは issuer の一部になります：`https://authentik.example.com/application/o/overleaf/`。
  </Step>

  <Step title="URL をコピーする">
    上記の[ディスカバリードキュメントで値を確認する](#ディスカバリードキュメントで値を確認する)に従って、5 つの URL を入力します。
  </Step>

  <Step title="管理者をマッピングする（任意）">
    Authentik は、ユーザーのグループを配列である `groups` クレームとして送信します。Authentik のグループ `Admins` のメンバーを Overleaf の管理者にするには、次のように設定します。

    ```dotenv theme={null}
    OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
    OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
    ```

    <Warning>
      管理者フラグは OIDC ログインのたびに更新されます。フィールドまたは値が誤っていると、launchpad で作成した管理者を含め、OIDC でログインしたすべての管理者が管理者権限を失います。まず 2 つ目の管理者アカウントでマッピングをテストしてください。
    </Warning>
  </Step>
</Steps>

<Accordion title="goauthentik 用の動作確認済み variables.env">
  ```dotenv title="variables.env" wrap theme={null}
  EXTERNAL_AUTH=oidc
  OVERLEAF_OIDC_PROVIDER_ID=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_CLIENT_SECRET=<Client Secret>
  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
  ```
</Accordion>


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