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

Konfigurasi

Secara internal, modul OIDC Overleaf menggunakan pustaka 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:
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.
1

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:

Authentik: URL discovery dan issuer sebuah provider (instans uji)

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
2

Baca nilainya

Buka URL tersebut di browser, atau jalankan di server Overleaf:
Respons dari Authentik terlihat seperti ini:
Authentik juga mencantumkan URL-URL ini di bagian bawah halaman provider:

Authentik: endpoint sebuah provider (instans uji)

3

Salin ke variables.env

4

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:
Perintah ini seharusnya menampilkan 200.
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.

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 (wajib)
  • OVERLEAF_OIDC_AUTHORIZATION_URL (wajib)
  • OVERLEAF_OIDC_TOKEN_URL (wajib)
  • OVERLEAF_OIDC_USER_INFO_URL (wajib)
  • OVERLEAF_OIDC_LOGOUT_URL (wajib)
Nilai dari dua variabel wajib berikut akan diberikan oleh admin OP Anda
  • OVERLEAF_OIDC_CLIENT_ID (wajib)
  • OVERLEAF_OIDC_CLIENT_SECRET (wajib)
  • 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.
variables.env

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

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.

Authentik: Client ID dan Client Secret provider baru

Authentik hanya menampilkan client secret saat Anda membuat provider. Setelah itu, formulir edit hanya menawarkan Modify, yang mengganti secret dengan yang baru.
2

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/.
3

Salin URL

Ikuti Menemukan nilai dengan dokumen discovery di atas untuk mengisi kelima URL.
4

Petakan admin (opsional)

Authentik mengirimkan grup pengguna sebagai klaim groups, berupa array. Untuk menjadikan anggota grup Authentik Admins sebagai admin Overleaf:
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.
variables.env

Tanya Jawab

Jawaban: Periksa hal-hal berikut:
  • Versi. Sebelum v6.3.0, Overleaf tidak membaca klaim kustom seperti groups, sehingga hanya OVERLEAF_OIDC_IS_ADMIN_FIELD=email yang berfungsi. Tingkatkan ke v6.3.0 atau yang lebih baru.
  • Klaim harus ada di respons UserInfo. Overleaf membaca klaim dari OVERLEAF_OIDC_USER_INFO_URL, bukan dari ID token. Jika OP Anda hanya menambahkan klaim ke ID token, tambahkan juga ke UserInfo, misalnya dengan Add to userinfo pada mapper Keycloak.
  • Nilainya harus sama persis, termasuk huruf besar-kecilnya, misalnya Admins.
Status admin diperiksa ulang setiap kali login: pengguna yang dijadikan administrator di panel admin akan kehilangan status tersebut pada login berikutnya jika klaimnya tidak cocok.
Jawaban: Tidak. GitHub mendukung OAuth 2.0 tetapi tidak mendukung OpenID Connect untuk login pengguna: GitHub tidak mengembalikan ID token, yang diwajibkan oleh Overleaf, sehingga login gagal dengan ID token not present in token response.Agar pengguna dapat login dengan akun GitHub mereka, gunakan penyedia identitas seperti goauthentik atau Keycloak, dengan GitHub sebagai sumber loginnya, lalu hubungkan Overleaf ke penyedia tersebut dengan OIDC.
Jawaban: Ya. GitLab, termasuk GitLab self-managed, adalah penyedia OpenID Connect. Di GitLab, buat aplikasi di bawah Applications (di pengaturan pengguna, grup, atau Admin area Anda) dengan:
  • Redirect URI: https://my-overleaf-instance.com/oidc/login/callback
  • Scopes: openid, profile dan email
Lalu baca endpoint dari https://gitlab.com/.well-known/openid-configuration, atau dari path yang sama di GitLab Anda, seperti yang dijelaskan di Menemukan nilai dengan dokumen discovery. Untuk gitlab.com, issuer-nya adalah https://gitlab.com, tanpa garis miring di akhir.
Jawaban: Sebelum mengalihkan ke OP, Overleaf menyimpan nilai state acak di sesi pengguna, dan memeriksanya saat OP mengalihkan kembali. Error ini berarti sesi pada callback bukan sesi yang memulai login.Unable to verify authorization request state berarti browser tidak mengirimkan kembali cookie sesi pada callback. Pastikan bahwa:
  • Pengguna membuka Overleaf di alamat OVERLEAF_SITE_URL. Callback selalu menuju OVERLEAF_SITE_URL, sehingga login yang dimulai dari alamat lain, seperti http://192.168.1.20 sementara OVERLEAF_SITE_URL adalah https://overleaf.example.com, kehilangan sesinya.
  • OVERLEAF_SECURE_COOKIE tidak diatur saat Overleaf disajikan melalui HTTP biasa. Browser membuang cookie secure pada HTTP. Nilai apa pun akan mengaktifkannya, termasuk false, jadi hapus barisnya.
Invalid authorization request state berarti login yang lebih baru menggantikan nilai yang tersimpan, misalnya setelah login dari dua tab sekaligus atau menekan tombol kembali di browser selama login. Tutup tab lainnya dan mulai login lagi dari halaman login Overleaf.
Terakhir diubah pada 2 November 2026