> ## 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.

# Autentikasi OIDC

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

### Konfigurasi

Secara internal, modul OIDC Overleaf menggunakan pustaka [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect). Jika Anda mengalami masalah saat mengonfigurasi OpenID Connect, ada baiknya membaca README untuk `passport-openidconnect` untuk memahami konfigurasi yang diharapkannya.

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

Contoh: `EXTERNAL_AUTH=ldap oidc`

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

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

`externalUserId` harus cocok dengan ID pengguna dalam profil yang dikembalikan oleh server IdP (lihat variabel lingkungan `OVERLEAF_OIDC_USER_ID_FIELD`), dan `providerId` harus cocok dengan ID penyedia OIDC (lihat `OVERLEAF_OIDC_PROVIDER_ID`).

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 `thirdPartyIdentifiers` akan diperbarui.
* Jika tidak ditemukan pengguna yang cocok dan pembuatan akun JIT tidak dinonaktifkan, pengguna baru akan dibuat dengan alamat email dan `thirdPartyIdentifiers` dari profil IdP.

Dalam kedua kasus, pengguna dikatakan 'tertaut' dengan pengguna OIDC eksternal. Tautan pengguna dengan penyedia OIDC dapat dilepas di halaman `/user/settings`.

#### Menemukan nilai dengan dokumen discovery

Setiap OpenID Provider (OP) menerbitkan dokumen discovery di `<issuer>/.well-known/openid-configuration`. Salin nilai-nilainya dari dokumen tersebut alih-alih mengetiknya secara manual; satu karakter yang salah saja sudah cukup untuk menggagalkan login.

<Steps>
  <Step title="Temukan URL discovery">
    OP Anda menampilkannya di halaman client (provider) yang Anda buat untuk Overleaf. Di Authentik, buka **Applications > Providers**, pilih provider, lalu cari **OpenID Configuration URL** dan **OpenID Configuration Issuer**:

    <Frame caption="Authentik: URL discovery dan issuer sebuah provider (instans uji)">
      <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-nya biasanya terlihat seperti ini:

    * 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="Baca nilainya">
    Buka URL tersebut di browser, atau jalankan di server 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}'
    ```

    Respons dari Authentik terlihat seperti ini:

    ```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 juga mencantumkan URL-URL ini di bagian bawah halaman provider:

    <Frame caption="Authentik: endpoint sebuah provider (instans uji)">
      <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="Salin ke `variables.env`">
    | Field di dokumen discovery | Variabel lingkungan |
    | - | - |
    | `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="Pastikan Overleaf dapat menjangkau OP">
    Overleaf memanggil endpoint token dan userinfo dari dalam kontainernya, sehingga OP harus dapat dijangkau dari sana, bukan hanya dari browser Anda:

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

    Perintah ini seharusnya menampilkan `200`.
  </Step>
</Steps>

<Warning>
  Salin `issuer` persis apa adanya, termasuk garis miring di akhir. Overleaf membandingkannya karakter demi karakter dengan issuer di ID token; perbedaan sekecil apa pun membuat setiap login OIDC gagal dengan:

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

  Di Authentik, issuer adalah milik aplikasi (`.../application/o/<application-slug>/`). Issuer bukan alamat server Authentik, meskipun URL authorize, token, dan userinfo digunakan bersama oleh semua aplikasi.
</Warning>

#### Variabel Lingkungan

Nilai dari lima variabel wajib berikut dapat ditemukan menggunakan endpoint `.well-known/openid-configuration` dari OpenID Provider (OP) Anda, lihat di atas.

* `OVERLEAF_OIDC_ISSUER` <strong>(wajib)</strong>
* `OVERLEAF_OIDC_AUTHORIZATION_URL` <strong>(wajib)</strong>
* `OVERLEAF_OIDC_TOKEN_URL` <strong>(wajib)</strong>
* `OVERLEAF_OIDC_USER_INFO_URL` <strong>(wajib)</strong>
* `OVERLEAF_OIDC_LOGOUT_URL` <strong>(wajib)</strong>

Nilai dari dua variabel wajib berikut akan diberikan oleh admin OP Anda

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(wajib)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(wajib)</strong>
* `OVERLEAF_OIDC_SCOPE`
  * Default: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * ID bebas untuk OP, default-nya `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * Nama OP, digunakan di bagian `Linked Accounts` pada halaman `/user/settings`, default-nya `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Nama tampilan untuk layanan identitas, digunakan di halaman login (default: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * Deskripsi OP, digunakan di bagian `Linked Accounts` (default: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * URL `Learn more` dalam deskripsi OP; default: tidak ada tautan `Learn more` dalam deskripsi.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Jangan tampilkan OP di halaman `/user/settings` jika akun pengguna tidak tertaut dengan OP; default `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * Nilai atribut ini akan digunakan oleh Overleaf sebagai ID pengguna eksternal, default-nya `id`. Nilai lain yang masuk akal adalah `email` dan `username` (sesuai dengan klaim OIDC `preferred_username`).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Membatasi pembuatan akun Just-in-Time (JIT) untuk pengguna yang melakukan autentikasi melalui OIDC. Jika diatur ke daftar nama domain yang dipisahkan koma, akun baru hanya akan dibuat jika domain alamat email pengguna cocok dengan salah satu domain dalam daftar. Jika domain tidak cocok, admin harus membuat akun pengguna secara manual menggunakan alamat email pengguna OIDC, dengan kata sandi acak yang kuat atau, sebaiknya, tanpa kolom `hashedPassword` sama sekali. Nama domain dapat menyertakan wildcard `*.` di awal untuk mencocokkan subdomain.
    * Contoh: Untuk mengizinkan pembuatan akun JIT bagi pengguna dengan alamat email seperti `name@example.com` dan `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Contoh: Untuk menonaktifkan pembuatan akun JIT sepenuhnya:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_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_OIDC_IS_ADMIN_FIELD` dan `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Ketika kedua variabel lingkungan diatur, proses login akan memperbarui `user.isAdmin = true` jika profil yang dikembalikan oleh OP berisi atribut yang ditentukan oleh `OVERLEAF_OIDC_IS_ADMIN_FIELD` dan nilainya cocok dengan `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` atau berupa array yang berisi `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` (misalnya klaim `groups`); jika tidak, `user.isAdmin` diatur ke `false`. Jika `OVERLEAF_OIDC_IS_ADMIN_FIELD` adalah `email`, nilai atribut `emails[0].value` digunakan untuk pemeriksaan kecocokan.

URL pengalihan (redirect URL) untuk OpenID Provider Anda adalah `https://my-overleaf-instance.com/oidc/login/callback`.

<Accordion title="Contoh file 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>

## Langkah demi langkah: goauthentik

Panduan ini menjelaskan penyiapan yang telah diuji dengan [goauthentik](https://goauthentik.io/). Ganti `https://overleaf.example.com` dengan `OVERLEAF_SITE_URL` Anda dan `https://authentik.example.com` dengan alamat Authentik Anda.

<Steps>
  <Step title="Buat provider">
    Di Authentik, buka **Applications > Providers**, klik **New Provider**, pilih **OAuth2/OpenID Provider**, lalu klik **Next**.

    * **Client Type**: `Confidential`.
    * **Redirect URIs** (di bawah **Protocol settings**): tambahkan `https://overleaf.example.com/oidc/login/callback` dengan mode pencocokan `Strict`.
    * Salin **Client ID** dan **Client Secret** sekarang ke `OVERLEAF_OIDC_CLIENT_ID` dan `OVERLEAF_OIDC_CLIENT_SECRET`.

    <Frame caption="Authentik: Client ID dan Client Secret provider baru">
      <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 hanya menampilkan client secret saat Anda membuat provider. Setelah itu, formulir edit hanya menawarkan **Modify**, yang mengganti secret dengan yang baru.
    </Warning>
  </Step>

  <Step title="Buat aplikasi">
    Buka **Applications > Applications**, buat aplikasi baru, beri nama dan slug, misalnya `overleaf`, lalu pilih provider-nya. Slug tersebut menjadi bagian dari issuer: `https://authentik.example.com/application/o/overleaf/`.
  </Step>

  <Step title="Salin URL">
    Ikuti [Menemukan nilai dengan dokumen discovery](#menemukan-nilai-dengan-dokumen-discovery) di atas untuk mengisi kelima URL.
  </Step>

  <Step title="Petakan admin (opsional)">
    Authentik mengirimkan grup pengguna sebagai klaim `groups`, berupa array. Untuk menjadikan anggota grup Authentik `Admins` sebagai admin Overleaf:

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

    <Warning>
      Status admin diperbarui pada setiap login OIDC. Jika field atau nilainya salah, setiap admin yang login melalui OIDC akan kehilangan hak admin, termasuk admin yang dibuat di launchpad. Uji pemetaan ini terlebih dahulu dengan akun admin kedua.
    </Warning>
  </Step>
</Steps>

<Accordion title="variables.env yang telah diuji untuk goauthentik">
  ```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.