Autentikasi SAML

Fitur ini dikembangkan oleh yu-i-i/overleaf-cep. Di sini kami menyediakan beberapa dokumen untuk konfigurasi Anda.

​

Konfigurasi

Secara internal, modul SAML Overleaf menggunakan pustaka passport-saml, dan sebagian besar opsi konfigurasi berikut diteruskan ke passport-saml. Jika Anda mengalami masalah saat mengonfigurasi SAML, ada baiknya membaca README untuk passport-saml untuk memahami konfigurasi yang diharapkannya.

Variabel lingkungan EXTERNAL_AUTH diperlukan untuk mengaktifkan modul autentikasi SAML. Variabel lingkungan ini menentukan metode autentikasi eksternal mana yang diaktifkan. Nilai variabel ini berupa daftar. Jika daftar tersebut menyertakan saml, autentikasi SAML akan diaktifkan.

Contoh: EXTERNAL_AUTH=ldap saml

Saat menggunakan metode autentikasi SAML, pengguna diarahkan ke situs autentikasi Identity Provider (IdP). Jika IdP berhasil mengautentikasi pengguna, database pengguna Overleaf diperiksa untuk mencari catatan yang berisi kolom samlIdentifiers dengan struktur sebagai berikut:

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

externalUserId harus cocok dengan nilai properti yang ditentukan oleh userIdAttribute dalam profil pengguna yang dikembalikan oleh server IdP.

Jika tidak ditemukan catatan yang cocok, database akan dicari untuk menemukan pengguna dengan alamat email utama yang cocok dengan email di profil pengguna IdP:

• Jika pengguna tersebut ditemukan, kolom hashedPassword dihapus untuk menonaktifkan autentikasi lokal, dan kolom samlIdentifiers ditambahkan.
• Jika tidak ditemukan pengguna yang cocok, pengguna baru akan dibuat dengan alamat email dan samlIdentifiers dari profil IdP.

Catatan: Saat ini, hanya satu IdP SAML yang didukung. Kolom providerId di samlIdentifiers ditetapkan ke '1'.

​

Variabel Lingkungan

• OVERLEAF_SAML_IDENTITY_SERVICE_NAME
  • Nama tampilan untuk layanan identitas, digunakan di halaman login (default: Log in with SAML IdP).
• OVERLEAF_SAML_USER_ID_FIELD
  • Nilai atribut ini akan digunakan oleh Overleaf sebagai ID pengguna eksternal, default-nya nameID.
• OVERLEAF_SAML_EMAIL_FIELD
  • Nama kolom Email di profil pengguna, default-nya nameID.
• OVERLEAF_SAML_FIRST_NAME_FIELD
  • Nama kolom firstName di profil pengguna, default-nya givenName.
• OVERLEAF_SAML_LAST_NAME_FIELD
  • Nama kolom lastName di profil pengguna, default-nya lastName
• OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN
  • Jika diatur ke true, kolom first_name dan last_name pengguna akan diperbarui saat login, dan formulir detail pengguna di halaman /user/settings akan dinonaktifkan.
• OVERLEAF_SAML_ENTRYPOINT (wajib)
  • URL entrypoint untuk layanan identitas SAML.
    • Contoh: https://idp.example.com/simplesaml/saml2/idp/SSOService.php
    • Contoh Azure: https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2
• OVERLEAF_SAML_ISSUER (wajib)
  • Nama Issuer.
• OVERLEAF_SAML_AUDIENCE
  • Audience respons saml yang diharapkan, default-nya nilai dari OVERLEAF_SAML_ISSUER.
• OVERLEAF_SAML_IDP_CERT (wajib)
  • Path ke file yang berisi sertifikat publik Identity Provider, digunakan untuk memvalidasi tanda tangan respons SAML yang masuk. Jika Identity Provider memiliki beberapa sertifikat penandatanganan yang valid, nilainya dapat berupa array JSON berisi path ke sertifikat-sertifikat tersebut.
    • Contoh (satu sertifikat): /var/lib/overleaf/certs/idp_cert.pem
    • Contoh (beberapa sertifikat): ["var/lib/overleaf/certs/idp_cert.pem", "/var/lib/overleaf/certs/idp_cert_old.pem"]
• OVERLEAF_SAML_PUBLIC_CERT
  • Path ke file yang berisi sertifikat penandatanganan publik yang disematkan dalam permintaan autentikasi agar IdP dapat memvalidasi tanda tangan SAML Request yang masuk. Ini diperlukan saat menyiapkan endpoint metadata ketika strategi dikonfigurasi dengan OVERLEAF_SAML_PRIVATE_KEY. Array JSON berisi path ke sertifikat dapat diberikan untuk mendukung rotasi sertifikat. Saat memberikan array sertifikat, entri pertama dalam array harus cocok dengan OVERLEAF_SAML_PRIVATE_KEY saat ini. Entri tambahan dalam array dapat digunakan untuk memublikasikan sertifikat yang akan datang ke IdP sebelum mengubah OVERLEAF_SAML_PRIVATE_KEY.
• OVERLEAF_SAML_PRIVATE_KEY
  • Path ke file yang berisi kunci privat berformat PEM yang cocok dengan OVERLEAF_SAML_PUBLIC_CERT, digunakan untuk menandatangani permintaan autentikasi yang dikirim oleh passport-saml.
• OVERLEAF_SAML_DECRYPTION_CERT
  • Path ke file yang berisi sertifikat publik, digunakan untuk endpoint metadata.
• OVERLEAF_SAML_DECRYPTION_PVK
  • Path ke file yang berisi kunci privat yang cocok dengan OVERLEAF_SAML_DECRYPTION_CERT yang akan digunakan untuk mencoba mendekripsi assertion terenkripsi yang diterima.
• OVERLEAF_SAML_SIGNATURE_ALGORITHM
  • Secara opsional mengatur algoritma tanda tangan untuk menandatangani permintaan; nilai yang valid adalah ‘sha1’ (default), ‘sha256’ (disarankan), ‘sha512’ (paling aman, periksa apakah IdP Anda mendukungnya).
• OVERLEAF_SAML_ADDITIONAL_PARAMS
  • Kamus JSON berisi parameter kueri tambahan yang akan ditambahkan ke semua permintaan.
• OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS
  • Kamus JSON berisi parameter kueri tambahan yang akan ditambahkan ke permintaan ‘authorize’.
    • Contoh: {"some_key": "some_value"}
• OVERLEAF_SAML_IDENTIFIER_FORMAT
  • Format name identifier yang diminta dari identity provider (default: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress). Jika menggunakan urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, pastikan variabel lingkungan OVERLEAF_SAML_EMAIL_FIELD telah didefinisikan. Jika urn:oasis:names:tc:SAML:2.0:nameid-format:transient diperlukan, Anda juga harus mendefinisikan variabel lingkungan OVERLEAF_SAML_USER_ID_FIELD, yang misalnya dapat diatur ke alamat email pengguna.
• OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS
  • Selisih waktu (skew) dalam milidetik yang dapat diterima antara klien dan server saat memeriksa validitas timestamp kondisi assertion OnBefore dan NotOnOrAfter. Mengatur ke -1 akan menonaktifkan pemeriksaan kondisi ini sepenuhnya. Default-nya adalah 0.
• OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX
  • Atribut AttributeConsumingServiceIndex yang ditambahkan ke AuthnRequest untuk menginstruksikan IdP set atribut mana yang harus dilampirkan ke respons (tautan).
• OVERLEAF_SAML_AUTHN_CONTEXT
  • Array JSON berisi nilai format name identifier untuk meminta konteks autentikasi. Default: ["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"].
• OVERLEAF_SAML_FORCE_AUTHN
  • Jika true, permintaan SAML awal dari service provider menetapkan bahwa IdP harus memaksa autentikasi ulang pengguna, meskipun pengguna memiliki sesi yang valid.
• OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT
  • Jika true, jangan meminta konteks autentikasi tertentu. Misalnya, Anda dapat mengatur ini ke true untuk mengizinkan konteks tambahan seperti login tanpa kata sandi (urn:oasis:names:tc:SAML:2.0:ac:classes:X509). Dukungan untuk konteks tambahan bergantung pada IdP Anda.
• OVERLEAF_SAML_AUTHN_REQUEST_BINDING
  • Jika diatur ke HTTP-POST, autentikasi akan diminta dari IdP melalui binding HTTP POST; jika tidak, default-nya HTTP-Redirect.
• OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO
  • Jika always, InResponseTo akan divalidasi dari respons SAML yang masuk.
  • Jika never, InResponseTo tidak akan divalidasi (default).
  • Jika ifPresent, InResponseTo hanya akan divalidasi jika ada dalam respons SAML yang masuk.
• OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED dan OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED
  • Jika diatur ke true (default), Overleaf mengharapkan SAML Assertions, atau masing-masing seluruh SAML Authentication Response, ditandatangani oleh IdP. Jika kedua opsi bernilai false, setidaknya salah satu dari assertion atau respons harus ditandatangani.
• OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS
  • Menentukan waktu kedaluwarsa setelah Request ID yang dibuat untuk permintaan SAML tidak lagi valid jika terlihat dalam respons SAML di kolom InResponseTo. Default: 28800000 (8 jam).
• OVERLEAF_SAML_LOGOUT_URL
  • Alamat dasar yang dipanggil dengan permintaan logout (default: entryPoint).
    • Contoh: https://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php
• OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS
  • Kamus JSON berisi parameter kueri tambahan yang akan ditambahkan ke permintaan ‘logout’.
• OVERLEAF_SAML_IS_ADMIN_FIELD dan OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE
  • Ketika kedua variabel lingkungan diatur, proses login akan memperbarui user.isAdmin = true jika profil yang dikembalikan oleh IdP SAML berisi atribut yang ditentukan oleh OVERLEAF_SAML_IS_ADMIN_FIELD dan nilainya cocok dengan OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE atau berupa array yang berisi OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE; jika tidak, user.isAdmin diatur ke false. Jika salah satu dari variabel ini tidak diatur, status admin hanya diatur ke true saat pembuatan pengguna admin di Launchpad.

Metadata untuk Identity Provider

Versi Overleaf CE saat ini menyertakan endpoint untuk mengambil Service Provider Metadata: http://my-overleaf-instance.com/saml/meta

Identity Provider perlu dikonfigurasi untuk mengenali server Overleaf sebagai “Service Provider”. Lihat dokumentasi server SAML Anda untuk petunjuk cara melakukannya.

Berikut adalah contoh metadata Service Provider yang sesuai:

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>

Perhatikan sertifikat, AssertionConsumerService.Location, SingleLogoutService.Location, dan EntityDescriptor.entityID, lalu atur sesuai kebutuhan di konfigurasi IdP Anda, atau kirimkan file metadata kepada admin IdP.

Contoh file variables.env (minimum)

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=[e-mail]

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

OVERLEAF_EMAIL_FROM_ADDRESS=[e-mail]
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=

​

Langkah demi langkah: goauthentik

Panduan ini menjelaskan penyiapan yang telah diuji dengan goauthentik. Ganti https://overleaf.example.com dengan OVERLEAF_SITE_URL Anda dan https://authentik.example.com dengan alamat Authentik Anda.

1. Buat provider dan aplikasi

   Di Authentik, buka Applications > Applications dan klik New Application. Wizard akan membuat aplikasi beserta provider-nya sekaligus.

   1. Beri aplikasi nama dan slug, misalnya overleaf, lalu klik Next:

   

   Authentik: nama dan slug aplikasi

   2. Pilih SAML Provider dan klik Next:

   

   Authentik: memilih provider SAML

   3. Isi data provider:

   • Authorization Flow: default-provider-authorization-implicit-consent
   • ACS URL: https://overleaf.example.com/saml/login/callback
   • Audience: nama untuk Overleaf, misalnya overleaf. Overleaf mengirimkannya sebagai OVERLEAF_SAML_ISSUER.

   

   Authentik: provider SAML untuk aplikasi

   4. Buka Advanced protocol settings dan atur:

   • Signing Certificate: sebuah sertifikat, misalnya authentik Self-signed Certificate
   • Sign assertions dan Sign responses: keduanya aktif
   • Service Provider Binding: Post

   

   Authentik: penandatanganan dan binding provider yang telah diuji (instans uji)

   5. Klik Next hingga halaman terakhir dan kirimkan aplikasi.

2. Salin nilai dari halaman provider

   Buka kembali provider tersebut. Semua yang dibutuhkan Overleaf ada di halaman ikhtisarnya:

   

   Authentik: ikhtisar provider SAML (instans uji)

   Di halaman provider	Variabel lingkungan
   SAML Endpoint	OVERLEAF_SAML_ENTRYPOINT dan OVERLEAF_SAML_LOGOUT_URL
   Audience	OVERLEAF_SAML_ISSUER
   Download signing certificate (sebuah file)	OVERLEAF_SAML_IDP_CERT, lihat langkah berikutnya

   EntityID/Issuer di bawah SAML Configuration adalah nama Authentik itu sendiri. Jangan memasukkannya ke OVERLEAF_SAML_ISSUER; gunakan Audience.

3. Pasang sertifikat penandatanganan

   Klik Download di bawah Download signing certificate dan simpan file sebagai data/overleaf/certs/idp_cert.pem di direktori Toolkit Anda. Kontainer melihatnya sebagai /var/lib/overleaf/certs/idp_cert.pem:

   OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
   
4. Petakan atribut

   Authentik mengirimkan atributnya dengan nama-nama berikut:

   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
   

   Grup dikirim sebagai http://schemas.xmlsoap.org/claims/Group, berupa daftar. Untuk menjadikan anggota grup Authentik Admins sebagai admin Overleaf:

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

   Status admin diperbarui pada setiap login SAML. Jika field atau nilainya salah, setiap admin yang login melalui SAML akan kehilangan hak admin. Uji pemetaan ini terlebih dahulu dengan akun admin kedua.

variables.env yang telah diuji untuk goauthentik

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