> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/id/konfigurasi/overleaf-toolkit/authentication/saml-authentication.md).

# Autentikasi SAML

Fitur ini dikembangkan oleh [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Di sini kami menawarkan beberapa dokumen untuk konfigurasi Anda.

### Konfigurasi

Secara internal, modul SAML Overleaf menggunakan [passport-saml](https://github.com/node-saml/passport-saml) pustaka, 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 adalah sebuah daftar. Jika daftar tersebut mencakup `saml` maka autentikasi SAML akan diaktifkan.

Misalnya: `EXTERNAL_AUTH=ldap saml`

Saat menggunakan metode autentikasi SAML, pengguna diarahkan ke situs autentikasi Identity Provider (IdP). Jika IdP berhasil mengautentikasi pengguna, basis data pengguna Overleaf diperiksa untuk entri yang berisi sebuah `samlIdentifiers` bidang yang disusun sebagai berikut:

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

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

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

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

**Catatan:** Saat ini, hanya satu IdP SAML yang didukung.  `providerId` bidang di `samlIdentifiers` ditetapkan menjadi `'1'`.

#### Variabel Lingkungan

* `OVERLEAF_SAML_IDENTITY_SERVICE_NAME`
  * Nama tampilan untuk layanan identitas, digunakan pada halaman masuk (default: `Masuk dengan SAML IdP`).
* `OVERLEAF_SAML_USER_ID_FIELD`
  * Nilai atribut ini akan digunakan oleh Overleaf sebagai ID pengguna eksternal, default ke `nameID`.
* `OVERLEAF_SAML_EMAIL_FIELD`
  * Nama bidang Email dalam profil pengguna, defaultnya `nameID`.
* `OVERLEAF_SAML_FIRST_NAME_FIELD`
  * Nama bidang firstName dalam profil pengguna, defaultnya `givenName`.
* `OVERLEAF_SAML_LAST_NAME_FIELD`
  * Nama bidang lastName dalam profil pengguna, defaultnya `lastName`
* `OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN`
  * Jika disetel ke `true`, memperbarui bidang pengguna `first_name` dan `last_name` bidang saat login, dan nonaktifkan formulir detail pengguna pada `/user/settings` halaman.
* `OVERLEAF_SAML_ENTRYPOINT` **(diperlukan)**
  * URL titik masuk 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` **(diperlukan)**
  * Nama Issuer.
* `OVERLEAF_SAML_AUDIENCE`
  * Audience respons SAML yang diharapkan, defaultnya adalah nilai dari `OVERLEAF_SAML_ISSUER`.
* `OVERLEAF_SAML_IDP_CERT` **(diperlukan)**
  * Jalur 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, maka dapat berupa larik JSON berisi jalur 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`
  * Jalur ke file yang berisi sertifikat penandatanganan publik yang digunakan untuk disematkan dalam permintaan autentikasi agar IdP dapat memvalidasi tanda tangan dari SAML Request yang masuk. Ini diperlukan saat menyiapkan [endpoint metadata](https://github.com/yu-i-i/overleaf-cep/wiki/Extended-CE:-SAML-Authentication#metadata-for-the-identity-provider) saat strategi dikonfigurasi dengan sebuah `OVERLEAF_SAML_PRIVATE_KEY`. Sebuah larik JSON berisi jalur ke sertifikat dapat disediakan untuk mendukung rotasi sertifikat. Saat menyediakan larik sertifikat, entri pertama dalam larik harus cocok dengan `OVERLEAF_SAML_PRIVATE_KEY`. Entri tambahan dalam larik dapat digunakan untuk memublikasikan sertifikat yang akan datang ke IdP sebelum mengubah `OVERLEAF_SAML_PRIVATE_KEY`.
* `OVERLEAF_SAML_PRIVATE_KEY`
  * Jalur ke file yang berisi kunci privat berformat PEM yang cocok dengan `OVERLEAF_SAML_PUBLIC_CERT` yang digunakan untuk menandatangani permintaan autentikasi yang dikirim oleh passport-saml.
* `OVERLEAF_SAML_DECRYPTION_CERT`
  * Jalur ke file yang berisi sertifikat publik, digunakan untuk [endpoint metadata](https://github.com/yu-i-i/overleaf-cep/wiki/Extended-CE:-SAML-Authentication#metadata-for-the-identity-provider).
* `OVERLEAF_SAML_DECRYPTION_PVK`
  * Jalur ke file yang berisi kunci privat yang cocok dengan `OVERLEAF_SAML_DECRYPTION_CERT` yang akan digunakan untuk mencoba mendekripsi assertion terenkripsi apa pun yang diterima.
* `OVERLEAF_SAML_SIGNATURE_ALGORITHM`
  * Secara opsional tetapkan 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 untuk ditambahkan ke semua permintaan.
* `OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS`
  * Kamus JSON berisi parameter kueri tambahan untuk ditambahkan ke permintaan 'authorize'.
    * Contoh: `{"some_key": "some_value"}`
* `OVERLEAF_SAML_IDENTIFIER_FORMAT`
  * Format pengenal nama 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` variabel lingkungan didefinisikan. Jika `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` diperlukan, Anda juga harus mendefinisikan `OVERLEAF_SAML_ID_FIELD` variabel lingkungan, yang misalnya dapat diatur ke alamat email pengguna.
* `OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS`
  * Waktu dalam milidetik untuk pergeseran yang masih dapat diterima antara klien dan server saat memeriksa cap waktu validitas kondisi assertion OnBefore dan NotOnOrAfter. Menetapkan ke -1 akan menonaktifkan pemeriksaan kondisi ini sepenuhnya. Default adalah 0.
* `OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX`
  * `AttributeConsumingServiceIndex` atribut yang ditambahkan ke AuthnRequest untuk menginstruksikan IdP set atribut mana yang harus dilampirkan ke respons ([tautan](http://blog.aniljohn.com/2014/01/data-minimization-front-channel-saml-attribute-requests.html)).
* `OVERLEAF_SAML_AUTHN_CONTEXT`
  * Larik JSON berisi nilai format pengenal nama 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 penyedia layanan menentukan bahwa IdP harus memaksa autentikasi ulang pengguna, bahkan jika mereka memiliki sesi yang valid.
* `OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT`
  * Jika `true`, jangan minta 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 disetel ke `HTTP-POST`, akan meminta autentikasi dari IdP melalui binding HTTP POST, jika tidak defaultnya HTTP-Redirect.
* `OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO`
  * Jika `always`, maka InResponseTo akan divalidasi dari respons SAML yang masuk.
  * Jika `jangan pernah`, maka InResponseTo tidak akan divalidasi (default).
  * Jika `ifPresent`, maka InResponseTo hanya akan divalidasi jika ada dalam respons SAML yang masuk.
* `OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED` dan `OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED`
  * Saat disetel ke `true` (default), Overleaf mengharapkan SAML Assertion, masing-masing seluruh SAML Authentication Response, ditandatangani oleh IdP. Ketika kedua opsi `false`, setidaknya salah satu assertion atau respons harus ditandatangani.
* `OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS`
  * Menentukan waktu kedaluwarsa ketika Request ID yang dibuat untuk permintaan SAML tidak akan valid jika terlihat dalam respons SAML pada `InResponseTo` bidang tersebut. Default: 28800000 (8 jam).
* `OVERLEAF_SAML_LOGOUT_URL`
  * alamat dasar untuk 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 untuk ditambahkan ke permintaan 'logout'.
* `OVERLEAF_SAML_IS_ADMIN_FIELD` dan `OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE`
  * Saat kedua variabel lingkungan diatur, proses login memperbarui `user.isAdmin = true` jika profil yang dikembalikan oleh SAML IdP berisi atribut yang ditentukan oleh `OVERLEAF_SAML_IS_ADMIN_FIELD` dan nilainya cocok dengan `OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE` atau merupakan array yang berisi `OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE`, kalau tidak `user.isAdmin` diatur menjadi `false`. Jika salah satu dari variabel ini tidak diatur, maka status admin hanya diatur menjadi `true` saat pembuatan pengguna admin di Launchpad.

**Metadata untuk Identity Provider**

Versi Overleaf CE saat ini menyertakan sebuah endpoint untuk mengambil Metadata Service Provider: `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 ini adalah contoh metadata Service Provider yang sesuai:

<details>

<summary><strong>ol-meta.xml</strong></summary>

```
<?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>

```

</details>

Perhatikan sertifikat, `AssertionConsumerService.Location`, `SingleLogoutService.Location` dan `EntityDescriptor.entityID` dan atur sesuai kebutuhan dalam konfigurasi IdP Anda, atau kirim file metadata ke admin IdP.

<details>

<summary><strong>Contoh file variables.env (minimum)</strong></summary>

<pre><code>OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Mengaktifkan pembuatan thumbnail menggunakan ImageMagick
ENABLE_CONVERSIONS=true

# Menonaktifkan persyaratan konfirmasi email
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Atur untuk TLS melalui nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

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

OVERLEAF_LEFT_FOOTER=[{"text": "Hubungi tim dukungan Anda", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Halo, saya ada di sisi kanan", "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=Sistem ini dijalankan oleh departemen 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
<strong>OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
</strong>OVERLEAF_SAML_SIGNATURE_ALGORITHM=
</code></pre>

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/id/konfigurasi/overleaf-toolkit/authentication/saml-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.