Autentikasi OIDC

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:

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.

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

Baca nilainya

Buka URL tersebut di browser, atau jalankan di server Overleaf:

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:

{
  "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:

Authentik: endpoint sebuah provider (instans uji)

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`

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/

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:

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.

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.

Contoh file variables.env

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

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

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.

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.

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

Salin URL

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

Petakan admin (opsional)

Authentik mengirimkan grup pengguna sebagai klaim groups, berupa array. Untuk menjadikan anggota grup Authentik Admins sebagai admin Overleaf:

OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins

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 yang telah diuji untuk goauthentik

variables.env

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

Ikhtisar

Instalasi

Konfigurasi

Pemeliharaan

Manajemen pengguna dan proyek

Dukungan

Konfigurasi

Menemukan nilai dengan dokumen discovery

Variabel Lingkungan

Langkah demi langkah: goauthentik

​Konfigurasi

​Menemukan nilai dengan dokumen discovery

​Variabel Lingkungan

​Langkah demi langkah: goauthentik

Konfigurasi

Menemukan nilai dengan dokumen discovery

Variabel Lingkungan

Langkah demi langkah: goauthentik