SAML 認証

この機能は yu-i-i/overleaf-cep によって開発されました。ここでは設定に関するドキュメントを提供します。

設定

内部的には、Overleaf の SAML モジュールは passport-saml ライブラリを使用しており、以下の設定オプションのほとんどは passport-saml にそのまま渡されます。SAML の設定で問題が発生した場合は、passport-saml の README を読んで、どのような設定が想定されているかを把握しておくとよいでしょう。 SAML 認証モジュールを有効にするには、環境変数 EXTERNAL_AUTH が必要です。この環境変数は、どの外部認証方式を有効にするかを指定します。この変数の値はリストです。リストに saml が含まれている場合、SAML 認証が有効になります。例：EXTERNAL_AUTH=ldap saml SAML 認証方式を使用する場合、ユーザーは ID プロバイダー（IdP）の認証サイトにリダイレクトされます。IdP がユーザーの認証に成功すると、Overleaf のユーザーデータベースで、次のような構造の samlIdentifiers フィールドを含むレコードが検索されます：

samlIdentifiers: [
  {
    externalUserId: "...",
    providerId: "1",
    userIdAttribute: "..."
  }
]

externalUserId は、IdP サーバーから返されるユーザープロファイル内で userIdAttribute によって指定されたプロパティの値と一致する必要があります。一致するレコードが見つからない場合は、IdP のユーザープロファイル内のメールアドレスと一致するプライマリメールアドレスを持つユーザーがデータベースで検索されます：

そのようなユーザーが見つかった場合、ローカル認証を無効にするために hashedPassword フィールドが削除され、samlIdentifiers フィールドが追加されます。
一致するユーザーが見つからない場合は、IdP プロファイルのメールアドレスと samlIdentifiers を使用して新しいユーザーが作成されます。

注：現在、サポートされている SAML IdP は 1 つのみです。samlIdentifiers の providerId フィールドは '1' に固定されています。

環境変数

OVERLEAF_SAML_IDENTITY_SERVICE_NAME
- ログインページで使用される ID サービスの表示名（デフォルト：Log in with SAML IdP）。
OVERLEAF_SAML_USER_ID_FIELD
- この属性の値が、Overleaf で外部ユーザー ID として使用されます。デフォルトは nameID です。
OVERLEAF_SAML_EMAIL_FIELD
- ユーザープロファイル内のメールアドレスフィールドの名前。デフォルトは nameID です。
OVERLEAF_SAML_FIRST_NAME_FIELD
- ユーザープロファイル内の firstName フィールドの名前。デフォルトは givenName です。
OVERLEAF_SAML_LAST_NAME_FIELD
- ユーザープロファイル内の lastName フィールドの名前。デフォルトは lastName です
OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN
- true に設定すると、ログイン時にユーザーの first_name と last_name フィールドを更新し、/user/settings ページのユーザー詳細フォームを無効にします。
OVERLEAF_SAML_ENTRYPOINT （必須）
- SAML ID サービスのエントリポイント URL。
  - 例：https://idp.example.com/simplesaml/saml2/idp/SSOService.php
  - Azure の例：https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2
OVERLEAF_SAML_ISSUER （必須）
- Issuer 名。
OVERLEAF_SAML_AUDIENCE
- SAML レスポンスで想定される Audience。デフォルトは OVERLEAF_SAML_ISSUER の値です。
OVERLEAF_SAML_IDP_CERT （必須）
- ID プロバイダーの公開証明書を含むファイルへのパス。受信した SAML レスポンスの署名を検証するために使用されます。ID プロバイダーに有効な署名証明書が複数ある場合は、証明書へのパスの JSON 配列を指定できます。
  - 例（証明書が 1 つの場合）：/var/lib/overleaf/certs/idp_cert.pem
  - 例（証明書が複数の場合）：["var/lib/overleaf/certs/idp_cert.pem", "/var/lib/overleaf/certs/idp_cert_old.pem"]
OVERLEAF_SAML_PUBLIC_CERT
- 認証リクエストに埋め込む公開署名証明書を含むファイルへのパス。IdP が受信した SAML リクエストの署名を検証するために使用されます。ストラテジーが OVERLEAF_SAML_PRIVATE_KEY で設定されている場合にメタデータエンドポイントをセットアップする際に必要です。証明書のローテーションをサポートするために、証明書へのパスの JSON 配列を指定することもできます。証明書の配列を指定する場合、配列の最初のエントリは現在の OVERLEAF_SAML_PRIVATE_KEY と一致する必要があります。配列の追加エントリは、OVERLEAF_SAML_PRIVATE_KEY を変更する前に、今後使用する証明書を IdP に公開するために使用できます。
OVERLEAF_SAML_PRIVATE_KEY
- passport-saml が送信する認証リクエストの署名に使用される、OVERLEAF_SAML_PUBLIC_CERT に対応する PEM 形式の秘密鍵を含むファイルへのパス。
OVERLEAF_SAML_DECRYPTION_CERT
- メタデータエンドポイントで使用される公開証明書を含むファイルへのパス。
OVERLEAF_SAML_DECRYPTION_PVK
- 受信した暗号化アサーションの復号に使用される、OVERLEAF_SAML_DECRYPTION_CERT に対応する秘密鍵を含むファイルへのパス。
OVERLEAF_SAML_SIGNATURE_ALGORITHM
- リクエストの署名に使用する署名アルゴリズムを任意で設定します。有効な値は ‘sha1’（デフォルト）、‘sha256’（推奨）、‘sha512’（最も安全。IdP がサポートしているか確認してください）です。
OVERLEAF_SAML_ADDITIONAL_PARAMS
- すべてのリクエストに追加するクエリパラメーターの JSON 辞書。
OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS
- ‘authorize’ リクエストに追加するクエリパラメーターの JSON 辞書。
  - 例：{"some_key": "some_value"}
OVERLEAF_SAML_IDENTIFIER_FORMAT
- ID プロバイダーに要求する名前識別子の形式（デフォルト：urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress）。urn:oasis:names:tc:SAML:2.0:nameid-format:persistent を使用する場合は、OVERLEAF_SAML_EMAIL_FIELD 環境変数が定義されていることを確認してください。urn:oasis:names:tc:SAML:2.0:nameid-format:transient が必要な場合は、OVERLEAF_SAML_USER_ID_FIELD 環境変数も定義する必要があります。この変数には、たとえばユーザーのメールアドレスを設定できます。
OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS
- OnBefore および NotOnOrAfter のアサーション条件の有効期間タイムスタンプを確認する際に許容される、クライアントとサーバー間の時刻のずれ（ミリ秒単位）。-1 に設定すると、これらの条件の確認が完全に無効になります。デフォルトは 0 です。
OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX
- AuthnRequest に追加する AttributeConsumingServiceIndex 属性。レスポンスにどの属性セットを付加するかを IdP に指示します（リンク）。
OVERLEAF_SAML_AUTHN_CONTEXT
- 認証コンテキストを要求するための名前識別子形式の値の JSON 配列。デフォルト：["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"]。
OVERLEAF_SAML_FORCE_AUTHN
- true の場合、サービスプロバイダーからの最初の SAML リクエストで、ユーザーが有効なセッションを持っていても IdP が再認証を強制するよう指定します。
OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT
- true の場合、特定の認証コンテキストを要求しません。たとえば、これを true に設定すると、パスワードレスログイン（urn:oasis:names:tc:SAML:2.0:ac:classes:X509）などの追加のコンテキストを許可できます。追加のコンテキストのサポートは IdP によって異なります。
OVERLEAF_SAML_AUTHN_REQUEST_BINDING
- HTTP-POST に設定すると、HTTP POST バインディングを介して IdP に認証を要求します。それ以外の場合のデフォルトは HTTP-Redirect です。
OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO
- always の場合、受信した SAML レスポンスの InResponseTo が検証されます。
- never の場合、InResponseTo は検証されません（デフォルト）。
- ifPresent の場合、受信した SAML レスポンスに InResponseTo が存在する場合にのみ検証されます。
OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED と OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED
- true（デフォルト）に設定すると、Overleaf は SAML アサーション、または SAML 認証レスポンス全体がそれぞれ IdP によって署名されていることを想定します。両方のオプションが false の場合でも、アサーションまたはレスポンスの少なくとも一方は署名されている必要があります。
OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS
- SAML リクエスト用に生成されたリクエスト ID が、SAML レスポンスの InResponseTo フィールドで確認された際に無効とみなされるまでの有効期間を定義します。デフォルト：28800000（8 時間）。
OVERLEAF_SAML_LOGOUT_URL
- ログアウトリクエストの送信先となるベースアドレス（デフォルト：entryPoint）。
  - 例：https://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php
OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS
- ‘logout’ リクエストに追加するクエリパラメーターの JSON 辞書。
OVERLEAF_SAML_IS_ADMIN_FIELD と OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE
- 両方の環境変数が設定されている場合、SAML IdP から返されたプロファイルに OVERLEAF_SAML_IS_ADMIN_FIELD で指定された属性が含まれ、その値が OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE と一致するか、OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE を含む配列である場合、ログイン処理で user.isAdmin = true に更新されます。それ以外の場合、user.isAdmin は false に設定されます。いずれかの変数が設定されていない場合、管理者ステータスが true に設定されるのは Launchpad での管理者ユーザー作成時のみです。

ID プロバイダー用のメタデータ 現在のバージョンの Overleaf CE には、サービスプロバイダーのメタデータを取得するためのエンドポイントが含まれています：http://my-overleaf-instance.com/saml/meta ID プロバイダーは、Overleaf サーバーを「サービスプロバイダー」として認識するように設定する必要があります。設定方法については、お使いの SAML サーバーのドキュメントを参照してください。以下は、適切なサービスプロバイダーのメタデータの例です：

ol-meta.xml

<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
                  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                  entityID="MyOverleaf"
                  ID="_b508c83b7dda452f5b269383fb391107116f8f57">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true" WantAssertionsSigned="true">
    <KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    <KeyDescriptor use="encryption">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes256-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes128-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
    </KeyDescriptor>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                         Location="https://my-overleaf-instance.com/saml/logout/callback"/>
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <AssertionConsumerService index="1"
                              isDefault="true"
                              Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                              Location="https://my-overleaf-instance.com/saml/login/callback"/>
  </SPSSODescriptor>
</EntityDescriptor>

証明書、AssertionConsumerService.Location、SingleLogoutService.Location、EntityDescriptor.entityID を控えておき、IdP の設定で適切に設定するか、メタデータファイルを IdP の管理者に送付してください。

variables.env ファイルのサンプル（最小構成）

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

#################
##     SAML    ##
#################

EXTERNAL_AUTH=saml
OVERLEAF_SAML_ISSUER=MyOverleaf
OVERLEAF_SAML_IDENTITY_SERVICE_NAME='Log in with SAML Provider'
OVERLEAF_SAML_EMAIL_FIELD=Email
OVERLEAF_SAML_FIRST_NAME_FIELD=DisplayName
OVERLEAF_SAML_LAST_NAME_FIELD=DisplayName
OVERLEAF_SAML_ENTRYPOINT=http://localhost:18000/login/saml/authorize/admin/SAML_Overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_SIGNATURE_ALGORITHM=

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

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

プロバイダーとアプリケーションを作成する

Authentik で Applications > Applications を開き、New Application をクリックします。ウィザードによって、アプリケーションとそのプロバイダーが同時に作成されます。1. アプリケーションに名前とスラッグ（例：overleaf）を付け、Next をクリックします。

2. SAML Provider を選択し、Next をクリックします。

3. プロバイダーの設定を入力します。

Authorization Flow：default-provider-authorization-implicit-consent
ACS URL：https://overleaf.example.com/saml/login/callback
Audience：Overleaf を表す名前（例：overleaf）。Overleaf はこれを OVERLEAF_SAML_ISSUER として送信します。

4. Advanced protocol settings を開き、次のように設定します。

Signing Certificate：証明書（例：authentik Self-signed Certificate）
Sign assertions と Sign responses：両方ともオン
Service Provider Binding：Post

Authentik：動作確認済みプロバイダーの署名とバインディング（テスト環境）

5. 最後のページまで Next をクリックし、アプリケーションを送信します。

プロバイダーのページから値をコピーする

もう一度プロバイダーを開きます。Overleaf に必要な情報はすべて概要ページにあります。

プロバイダーのページ上の項目	環境変数
SAML Endpoint	`OVERLEAF_SAML_ENTRYPOINT` と `OVERLEAF_SAML_LOGOUT_URL`
Audience	`OVERLEAF_SAML_ISSUER`
Download signing certificate（ファイル）	`OVERLEAF_SAML_IDP_CERT`（次の手順を参照）

SAML Configuration の下にある EntityID/Issuer は Authentik 自体の名前です。これを OVERLEAF_SAML_ISSUER に設定せず、Audience を使用してください。

署名証明書をインストールする

Download signing certificate の下にある Download をクリックし、Toolkit ディレクトリ内の data/overleaf/certs/idp_cert.pem としてファイルを保存します。コンテナからは /var/lib/overleaf/certs/idp_cert.pem として参照されます。

OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem

属性をマッピングする

Authentik は次の名前で属性を送信します。

OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username

グループはリストとして http://schemas.xmlsoap.org/claims/Group で送信されます。Authentik のグループ Admins のメンバーを Overleaf の管理者にするには、次のように設定します。

OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins

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

goauthentik 用の動作確認済み variables.env

variables.env

EXTERNAL_AUTH=saml
OVERLEAF_SAML_IDENTITY_SERVICE_NAME=Log in with Authentik
OVERLEAF_SAML_ENTRYPOINT=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_LOGOUT_URL=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_ISSUER=overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED=true
OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED=true
OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins
OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN=true

概要

インストール

設定

メンテナンス

ユーザーとプロジェクトの管理

サポート

設定

環境変数

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

​設定

​環境変数

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

設定

環境変数

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