Skip to main content
Tính năng này được phát triển bởi yu-i-i/overleaf-cep. Tại đây chúng tôi cung cấp một số tài liệu để bạn cấu hình.

​
Cấu hình

Về mặt nội bộ, module SAML của Overleaf sử dụng thư viện passport-saml; hầu hết các tùy chọn cấu hình sau đây được truyền thẳng đến passport-saml. Nếu bạn gặp vấn đề khi cấu hình SAML, bạn nên đọc README của passport-saml để nắm được cấu hình mà thư viện này mong đợi. Biến môi trường EXTERNAL_AUTH là bắt buộc để bật module xác thực SAML. Biến môi trường này chỉ định những phương thức xác thực bên ngoài nào được kích hoạt. Giá trị của biến này là một danh sách. Nếu danh sách bao gồm saml thì xác thực SAML sẽ được kích hoạt. Ví dụ: EXTERNAL_AUTH=ldap saml Khi sử dụng phương thức xác thực SAML, người dùng sẽ được chuyển hướng đến trang xác thực của Nhà cung cấp định danh (IdP). Nếu IdP xác thực người dùng thành công, cơ sở dữ liệu người dùng Overleaf sẽ được kiểm tra để tìm bản ghi có trường samlIdentifiers với cấu trúc như sau:
externalUserId phải khớp với giá trị của thuộc tính được chỉ định bởi userIdAttribute trong hồ sơ người dùng do máy chủ IdP trả về. Nếu không tìm thấy bản ghi phù hợp, cơ sở dữ liệu sẽ được tìm kiếm để tìm người dùng có địa chỉ email chính khớp với email trong hồ sơ người dùng của IdP:
  • Nếu tìm thấy người dùng như vậy, trường hashedPassword sẽ bị xóa để vô hiệu hóa xác thực cục bộ, và trường samlIdentifiers sẽ được thêm vào.
  • Nếu không tìm thấy người dùng phù hợp, một người dùng mới sẽ được tạo với địa chỉ email và samlIdentifiers lấy từ hồ sơ IdP.
Lưu ý: Hiện tại chỉ hỗ trợ một IdP SAML. Trường providerId trong samlIdentifiers được cố định là '1'.

​
Biến môi trường

  • OVERLEAF_SAML_IDENTITY_SERVICE_NAME
    • Tên hiển thị của dịch vụ định danh, được dùng trên trang đăng nhập (mặc định: Log in with SAML IdP).
  • OVERLEAF_SAML_USER_ID_FIELD
    • Giá trị của thuộc tính này sẽ được Overleaf dùng làm ID người dùng bên ngoài, mặc định là nameID.
  • OVERLEAF_SAML_EMAIL_FIELD
    • Tên của trường Email trong hồ sơ người dùng, mặc định là nameID.
  • OVERLEAF_SAML_FIRST_NAME_FIELD
    • Tên của trường firstName trong hồ sơ người dùng, mặc định là givenName.
  • OVERLEAF_SAML_LAST_NAME_FIELD
    • Tên của trường lastName trong hồ sơ người dùng, mặc định là lastName
  • OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN
    • Nếu được đặt thành true, các trường first_name và last_name của người dùng sẽ được cập nhật khi đăng nhập, và biểu mẫu thông tin người dùng trên trang /user/settings sẽ bị tắt.
  • OVERLEAF_SAML_ENTRYPOINT (bắt buộc)
    • URL điểm vào (entrypoint) của dịch vụ định danh SAML.
      • Ví dụ: https://idp.example.com/simplesaml/saml2/idp/SSOService.php
      • Ví dụ với Azure: https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2
  • OVERLEAF_SAML_ISSUER (bắt buộc)
    • Tên Issuer (bên phát hành).
  • OVERLEAF_SAML_AUDIENCE
    • Audience mong đợi trong phản hồi SAML, mặc định là giá trị của OVERLEAF_SAML_ISSUER.
  • OVERLEAF_SAML_IDP_CERT (bắt buộc)
    • Đường dẫn đến tệp chứa chứng chỉ công khai của Nhà cung cấp định danh, được dùng để xác thực chữ ký của các phản hồi SAML gửi đến. Nếu Nhà cung cấp định danh có nhiều chứng chỉ ký hợp lệ, giá trị này có thể là một mảng JSON chứa đường dẫn đến các chứng chỉ.
      • Ví dụ (một chứng chỉ): /var/lib/overleaf/certs/idp_cert.pem
      • Ví dụ (nhiều chứng chỉ): ["var/lib/overleaf/certs/idp_cert.pem", "/var/lib/overleaf/certs/idp_cert_old.pem"]
  • OVERLEAF_SAML_PUBLIC_CERT
    • Đường dẫn đến tệp chứa chứng chỉ ký công khai được nhúng vào các yêu cầu xác thực để IdP có thể xác thực chữ ký của SAML Request gửi đến. Biến này là bắt buộc khi thiết lập endpoint metadata trong trường hợp strategy được cấu hình với OVERLEAF_SAML_PRIVATE_KEY. Có thể cung cấp một mảng JSON chứa đường dẫn đến các chứng chỉ để hỗ trợ xoay vòng chứng chỉ. Khi cung cấp một mảng chứng chỉ, mục đầu tiên trong mảng phải khớp với OVERLEAF_SAML_PRIVATE_KEY hiện tại. Các mục bổ sung trong mảng có thể được dùng để công bố trước các chứng chỉ sắp tới cho IdP trước khi thay đổi OVERLEAF_SAML_PRIVATE_KEY.
  • OVERLEAF_SAML_PRIVATE_KEY
    • Đường dẫn đến tệp chứa khóa riêng định dạng PEM tương ứng với OVERLEAF_SAML_PUBLIC_CERT, được dùng để ký các yêu cầu xác thực do passport-saml gửi đi.
  • OVERLEAF_SAML_DECRYPTION_CERT
    • Đường dẫn đến tệp chứa chứng chỉ công khai, được dùng cho endpoint metadata.
  • OVERLEAF_SAML_DECRYPTION_PVK
    • Đường dẫn đến tệp chứa khóa riêng tương ứng với OVERLEAF_SAML_DECRYPTION_CERT, sẽ được dùng để giải mã mọi assertion được mã hóa nhận được.
  • OVERLEAF_SAML_SIGNATURE_ALGORITHM
    • Tùy chọn đặt thuật toán chữ ký để ký các yêu cầu; các giá trị hợp lệ là ‘sha1’ (mặc định), ‘sha256’ (khuyến nghị), ‘sha512’ (bảo mật nhất, hãy kiểm tra xem IdP của bạn có hỗ trợ không).
  • OVERLEAF_SAML_ADDITIONAL_PARAMS
    • Từ điển JSON chứa các tham số truy vấn bổ sung sẽ được thêm vào tất cả các yêu cầu.
  • OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS
    • Từ điển JSON chứa các tham số truy vấn bổ sung sẽ được thêm vào các yêu cầu ‘authorize’.
      • Ví dụ: {"some_key": "some_value"}
  • OVERLEAF_SAML_IDENTIFIER_FORMAT
    • Định dạng định danh tên (name identifier) sẽ yêu cầu từ nhà cung cấp định danh (mặc định: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress). Nếu sử dụng urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, hãy đảm bảo biến môi trường OVERLEAF_SAML_EMAIL_FIELD đã được định nghĩa. Nếu cần dùng urn:oasis:names:tc:SAML:2.0:nameid-format:transient, bạn cũng phải định nghĩa biến môi trường OVERLEAF_SAML_USER_ID_FIELD, chẳng hạn có thể đặt thành địa chỉ email của người dùng.
  • OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS
    • Độ lệch thời gian (tính bằng mili giây) có thể chấp nhận giữa client và server khi kiểm tra tính hợp lệ của các mốc thời gian trong điều kiện assertion OnBefore và NotOnOrAfter. Đặt thành -1 sẽ tắt hoàn toàn việc kiểm tra các điều kiện này. Mặc định là 0.
  • OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX
    • Thuộc tính AttributeConsumingServiceIndex được thêm vào AuthnRequest để chỉ cho IdP biết tập thuộc tính nào cần đính kèm vào phản hồi (liên kết).
  • OVERLEAF_SAML_AUTHN_CONTEXT
    • Mảng JSON chứa các giá trị định dạng định danh tên để yêu cầu ngữ cảnh xác thực. Mặc định: ["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"].
  • OVERLEAF_SAML_FORCE_AUTHN
    • Nếu là true, yêu cầu SAML ban đầu từ nhà cung cấp dịch vụ sẽ chỉ định rằng IdP phải buộc người dùng xác thực lại, ngay cả khi họ đang có một phiên hợp lệ.
  • OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT
    • Nếu là true, không yêu cầu một ngữ cảnh xác thực cụ thể. Ví dụ, bạn có thể đặt giá trị này thành true để cho phép các ngữ cảnh bổ sung như đăng nhập không cần mật khẩu (urn:oasis:names:tc:SAML:2.0:ac:classes:X509). Việc hỗ trợ các ngữ cảnh bổ sung phụ thuộc vào IdP của bạn.
  • OVERLEAF_SAML_AUTHN_REQUEST_BINDING
    • Nếu được đặt thành HTTP-POST, sẽ yêu cầu xác thực từ IdP qua binding HTTP POST; nếu không, mặc định là HTTP-Redirect.
  • OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO
    • Nếu là always, InResponseTo sẽ được xác thực trong các phản hồi SAML gửi đến.
    • Nếu là never, InResponseTo sẽ không được xác thực (mặc định).
    • Nếu là ifPresent, InResponseTo chỉ được xác thực nếu có mặt trong phản hồi SAML gửi đến.
  • OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED và OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED
    • Khi được đặt thành true (mặc định), Overleaf yêu cầu các SAML Assertion, hoặc tương ứng là toàn bộ SAML Authentication Response, phải được IdP ký. Khi cả hai tùy chọn đều là false, ít nhất một trong hai (các assertion hoặc phản hồi) phải được ký.
  • OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS
    • Xác định thời gian hết hạn, sau đó một Request ID được tạo cho yêu cầu SAML sẽ không còn hợp lệ nếu xuất hiện trong trường InResponseTo của phản hồi SAML. Mặc định: 28800000 (8 giờ).
  • OVERLEAF_SAML_LOGOUT_URL
    • Địa chỉ cơ sở để gọi các yêu cầu đăng xuất (mặc định: entryPoint).
      • Ví dụ: https://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php
  • OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS
    • Từ điển JSON chứa các tham số truy vấn bổ sung sẽ được thêm vào các yêu cầu ‘logout’.
  • OVERLEAF_SAML_IS_ADMIN_FIELD và OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE
    • Khi cả hai biến môi trường này đều được đặt, quá trình đăng nhập sẽ cập nhật user.isAdmin = true nếu hồ sơ do IdP SAML trả về chứa thuộc tính được chỉ định bởi OVERLEAF_SAML_IS_ADMIN_FIELD và giá trị của nó khớp với OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE hoặc là một mảng có chứa OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE; nếu không, user.isAdmin sẽ được đặt thành false. Nếu một trong hai biến này không được đặt, trạng thái quản trị viên chỉ được đặt thành true khi tạo người dùng quản trị trong Launchpad.
Metadata cho Nhà cung cấp định danh Phiên bản hiện tại của Overleaf CE có một endpoint để lấy Metadata của Nhà cung cấp dịch vụ (Service Provider): http://my-overleaf-instance.com/saml/meta Nhà cung cấp định danh cần được cấu hình để nhận diện máy chủ Overleaf là một “Service Provider”. Hãy tham khảo tài liệu của máy chủ SAML của bạn để biết hướng dẫn cách thực hiện. Dưới đây là ví dụ về metadata phù hợp của Service Provider:
Hãy ghi lại các chứng chỉ, AssertionConsumerService.Location, SingleLogoutService.Location và EntityDescriptor.entityID rồi thiết lập cho phù hợp trong cấu hình IdP của bạn, hoặc gửi tệp metadata cho quản trị viên IdP.

​
Hướng dẫn từng bước: goauthentik

Phần này hướng dẫn một cấu hình đã được kiểm thử với goauthentik. Hãy thay https://overleaf.example.com bằng OVERLEAF_SITE_URL của bạn và https://authentik.example.com bằng địa chỉ Authentik của bạn.
1

Tạo provider và application

Trong Authentik, mở Applications > Applications và nhấp New Application. Trình hướng dẫn sẽ tạo application cùng với provider của nó.1. Đặt tên và slug cho application, ví dụ overleaf, rồi nhấp Next:

Authentik: tên và slug của application

2. Chọn SAML Provider và nhấp Next:

Authentik: chọn provider SAML

3. Điền thông tin provider:
  • Authorization Flow: default-provider-authorization-implicit-consent
  • ACS URL: https://overleaf.example.com/saml/login/callback
  • Audience: một tên cho Overleaf, ví dụ overleaf. Overleaf gửi tên này dưới dạng OVERLEAF_SAML_ISSUER.

Authentik: provider SAML của application

4. Mở Advanced protocol settings và đặt:
  • Signing Certificate: một chứng chỉ, ví dụ authentik Self-signed Certificate
  • Sign assertions và Sign responses: bật cả hai
  • Service Provider Binding: Post

Authentik: ký và binding của một provider đã kiểm thử (phiên bản thử nghiệm)

5. Nhấp Next cho đến trang cuối cùng và gửi application.
2

Sao chép các giá trị từ trang provider

Mở lại provider. Mọi thứ Overleaf cần đều có trên trang tổng quan của nó:

Authentik: tổng quan của một provider SAML (phiên bản thử nghiệm)

EntityID/Issuer trong SAML Configuration là tên của chính Authentik. Đừng đặt nó vào OVERLEAF_SAML_ISSUER, hãy dùng Audience.
3

Cài đặt chứng chỉ ký

Nhấp Download trong Download signing certificate và lưu tệp dưới tên data/overleaf/certs/idp_cert.pem trong thư mục Toolkit của bạn. Container nhìn thấy tệp này là /var/lib/overleaf/certs/idp_cert.pem:
4

Ánh xạ các thuộc tính

Authentik gửi các thuộc tính của nó dưới những tên sau:
Các nhóm được gửi dưới dạng http://schemas.xmlsoap.org/claims/Group, là một danh sách. Để các thành viên của nhóm Authentik Admins trở thành quản trị viên Overleaf:
Cờ quản trị viên được cập nhật ở mỗi lần đăng nhập SAML. Nếu trường hoặc giá trị sai, mọi quản trị viên đăng nhập qua SAML sẽ mất quyền quản trị. Hãy thử nghiệm việc ánh xạ bằng một tài khoản quản trị viên thứ hai trước.
variables.env
Lần sửa đổi cuối 6 tháng 10, 2026