Chuyển đến nội dung chính
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 OIDC của Overleaf sử dụng thư viện passport-openidconnect. Nếu bạn gặp vấn đề khi cấu hình OpenID Connect, bạn nên đọc README của passport-openidconnect để 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 OIDC. 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 oidc thì xác thực OIDC sẽ được kích hoạt. Ví dụ: EXTERNAL_AUTH=ldap oidc Khi sử dụng phương thức xác thực OIDC, 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 thirdPartyIdentifiers với cấu trúc như sau:
externalUserId phải khớp với ID người dùng trong hồ sơ do máy chủ IdP trả về (xem biến môi trường OVERLEAF_OIDC_USER_ID_FIELD), và providerId phải khớp với ID của nhà cung cấp OIDC (xem OVERLEAF_OIDC_PROVIDER_ID). 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 thirdPartyIdentifiers sẽ được cập nhật.
  • Nếu không tìm thấy người dùng phù hợp và tính năng tạo tài khoản JIT không bị tắt, một người dùng mới sẽ được tạo với địa chỉ email và thirdPartyIdentifiers lấy từ hồ sơ IdP.
Trong cả hai trường hợp, người dùng được coi là đã được ‘liên kết’ với người dùng OIDC bên ngoài. Người dùng có thể hủy liên kết với nhà cung cấp OIDC trên trang /user/settings.

Tìm các giá trị bằng tài liệu discovery

Mọi Nhà cung cấp OpenID (OP) đều công bố một tài liệu discovery tại <issuer>/.well-known/openid-configuration. Hãy sao chép các giá trị từ tài liệu này thay vì gõ tay; chỉ cần sai một ký tự là đủ khiến việc đăng nhập thất bại.
1

Tìm URL discovery

OP của bạn hiển thị URL này trên trang của client (provider) mà bạn đã tạo cho Overleaf. Trong Authentik, mở Applications > Providers, chọn provider và tìm OpenID Configuration URL và OpenID Configuration Issuer:

Authentik: URL discovery và issuer của một provider (phiên bản thử nghiệm)

URL thường có dạng như sau:
  • 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

Đọc các giá trị

Mở URL trong trình duyệt, hoặc chạy lệnh sau trên máy chủ Overleaf:
Phản hồi của Authentik có dạng như sau:
Authentik cũng liệt kê các URL này ở phía dưới trang provider:

Authentik: các endpoint của một provider (phiên bản thử nghiệm)

3

Sao chép chúng vào variables.env

4

Kiểm tra Overleaf có thể kết nối tới OP

Overleaf gọi các endpoint token và userinfo từ bên trong container của nó, vì vậy OP phải truy cập được từ đó, chứ không chỉ từ trình duyệt của bạn:
Lệnh này phải in ra 200.
Hãy sao chép issuer chính xác, bao gồm cả dấu gạch chéo ở cuối. Overleaf so sánh từng ký tự của nó với issuer trong ID token; bất kỳ khác biệt nào cũng khiến mọi lần đăng nhập OIDC thất bại với lỗi:{"message":{"message":"ID token not issued by expected OpenID provider."}}Trong Authentik, issuer thuộc về application (.../application/o/<application-slug>/). Đó không phải là địa chỉ của máy chủ Authentik, mặc dù các URL authorize, token và userinfo được dùng chung cho tất cả các application.

Biến môi trường

Giá trị của năm biến bắt buộc sau đây có thể được tìm thấy thông qua endpoint .well-known/openid-configuration của Nhà cung cấp OpenID (OP) của bạn, xem ở trên.
  • OVERLEAF_OIDC_ISSUER (bắt buộc)
  • OVERLEAF_OIDC_AUTHORIZATION_URL (bắt buộc)
  • OVERLEAF_OIDC_TOKEN_URL (bắt buộc)
  • OVERLEAF_OIDC_USER_INFO_URL (bắt buộc)
  • OVERLEAF_OIDC_LOGOUT_URL (bắt buộc)
Giá trị của hai biến bắt buộc sau đây sẽ do quản trị viên OP của bạn cung cấp
  • OVERLEAF_OIDC_CLIENT_ID (bắt buộc)
  • OVERLEAF_OIDC_CLIENT_SECRET (bắt buộc)
  • OVERLEAF_OIDC_SCOPE
    • Mặc định: openid profile email
  • OVERLEAF_OIDC_PROVIDER_ID
    • ID tùy ý của OP, mặc định là oidc.
  • OVERLEAF_OIDC_PROVIDER_NAME
    • Tên của OP, được dùng trong phần Linked Accounts của trang /user/settings, mặc định là OIDC Provider.
  • OVERLEAF_OIDC_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 $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_DESCRIPTION
    • Mô tả về OP, được dùng trong phần Linked Accounts (mặc định: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_INFO_LINK
    • URL Learn more trong phần mô tả OP; mặc định: không có liên kết Learn more trong phần mô tả.
  • OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED
    • Không hiển thị OP trên trang /user/settings nếu tài khoản của người dùng chưa được liên kết với OP, mặc định là false.
  • OVERLEAF_OIDC_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à id. Các giá trị hợp lý khác có thể dùng là email và username (tương ứng với claim OIDC preferred_username).
  • OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS
    • Giới hạn việc tạo tài khoản Just-in-Time (JIT) cho người dùng xác thực qua OIDC. Nếu được đặt thành một danh sách tên miền phân tách bằng dấu phẩy, tài khoản mới sẽ chỉ được tạo nếu tên miền trong địa chỉ email của người dùng khớp với một trong các tên miền được liệt kê. Nếu tên miền không khớp, quản trị viên phải tạo tài khoản người dùng thủ công bằng địa chỉ email của người dùng OIDC, với một mật khẩu ngẫu nhiên mạnh hoặc tốt hơn là hoàn toàn không có trường hashedPassword. Tên miền có thể bắt đầu bằng ký tự đại diện *. để khớp với các tên miền con.
      • Ví dụ: Để cho phép tạo tài khoản JIT cho người dùng có địa chỉ email như name@example.com và name@math.example.com:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com
      • Ví dụ: Để tắt hoàn toàn việc tạo tài khoản JIT:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=
  • OVERLEAF_OIDC_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ị vô hiệu hóa.
  • OVERLEAF_OIDC_IS_ADMIN_FIELD và OVERLEAF_OIDC_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 OP trả về chứa thuộc tính được chỉ định bởi OVERLEAF_OIDC_IS_ADMIN_FIELD và giá trị của nó hoặc khớp với OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE, hoặc là một mảng chứa OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE (ví dụ claim groups); nếu không, user.isAdmin sẽ được đặt thành false. Nếu OVERLEAF_OIDC_IS_ADMIN_FIELD là email thì giá trị của thuộc tính emails[0].value sẽ được dùng để kiểm tra khớp.
URL chuyển hướng cho Nhà cung cấp OpenID của bạn là https://my-overleaf-instance.com/oidc/login/callback.
variables.env

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

Trong Authentik, mở Applications > Providers, nhấp New Provider, chọn OAuth2/OpenID Provider và nhấp Next.
  • Client Type: Confidential.
  • Redirect URIs (trong Protocol settings): thêm https://overleaf.example.com/oidc/login/callback với chế độ khớp Strict.
  • Sao chép ngay Client ID và Client Secret vào OVERLEAF_OIDC_CLIENT_ID và OVERLEAF_OIDC_CLIENT_SECRET.

Authentik: Client ID và Client Secret của một provider mới

Authentik chỉ hiển thị client secret khi bạn tạo provider. Về sau, biểu mẫu chỉnh sửa chỉ cung cấp Modify, thao tác này sẽ thay secret bằng một secret mới.
2

Tạo application

Mở Applications > Applications, tạo một application mới, đặt tên và slug cho nó, ví dụ overleaf, rồi chọn provider. Slug sẽ trở thành một phần của issuer: https://authentik.example.com/application/o/overleaf/.
3

Sao chép các URL

Làm theo phần Tìm các giá trị bằng tài liệu discovery ở trên để điền năm URL.
4

Ánh xạ quản trị viên (tùy chọn)

Authentik gửi các nhóm của người dùng dưới dạng claim groups, là một mảng. Để 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 OIDC. Nếu trường hoặc giá trị sai, mọi quản trị viên đăng nhập qua OIDC sẽ mất quyền quản trị, kể cả quản trị viên được tạo trong launchpad. 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

Hỏi & Đáp

Trả lời: Hãy kiểm tra những điều sau:
  • Phiên bản. Trước v6.3.0, Overleaf không đọc các claim tùy chỉnh như groups, nên chỉ OVERLEAF_OIDC_IS_ADMIN_FIELD=email hoạt động. Hãy nâng cấp lên v6.3.0 trở lên.
  • Claim phải có trong phản hồi UserInfo. Overleaf đọc claim từ OVERLEAF_OIDC_USER_INFO_URL, không phải từ ID token. Nếu OP của bạn chỉ thêm claim vào ID token, hãy thêm nó vào cả UserInfo, ví dụ bằng tùy chọn Add to userinfo trên một mapper của Keycloak.
  • Giá trị phải khớp chính xác, kể cả chữ hoa chữ thường, ví dụ Admins.
Trạng thái quản trị viên được kiểm tra lại mỗi lần đăng nhập: một người dùng được đặt làm quản trị viên trong trang quản trị sẽ mất quyền này ở lần đăng nhập tiếp theo nếu claim không khớp.
Trả lời: Không. GitHub hỗ trợ OAuth 2.0 nhưng không hỗ trợ OpenID Connect cho việc đăng nhập người dùng: GitHub không trả về ID token, thứ mà Overleaf yêu cầu, nên đăng nhập sẽ thất bại với lỗi ID token not present in token response.Để cho phép người dùng đăng nhập bằng tài khoản GitHub, hãy dùng một nhà cung cấp danh tính như goauthentik hoặc Keycloak, với GitHub là nguồn đăng nhập, rồi kết nối Overleaf với nhà cung cấp đó qua OIDC.
Trả lời: Có. GitLab, bao gồm cả GitLab tự quản lý, là một nhà cung cấp OpenID Connect. Trong GitLab, hãy tạo một ứng dụng trong mục Applications (trong phần cài đặt người dùng, nhóm hoặc Admin area) với:
  • Redirect URI: https://my-overleaf-instance.com/oidc/login/callback
  • Scopes: openid, profile và email
Sau đó, hãy đọc các endpoint từ https://gitlab.com/.well-known/openid-configuration, hoặc từ cùng đường dẫn đó trên GitLab của bạn, như mô tả trong Tìm các giá trị bằng tài liệu discovery. Với gitlab.com, issuer là https://gitlab.com, không có dấu gạch chéo ở cuối.
Trả lời: Trước khi chuyển hướng tới OP, Overleaf lưu một giá trị state ngẫu nhiên trong phiên của người dùng và kiểm tra giá trị đó khi OP chuyển hướng trở lại. Các lỗi này có nghĩa là phiên tại callback không phải là phiên đã bắt đầu quá trình đăng nhập.Unable to verify authorization request state có nghĩa là trình duyệt đã không gửi lại cookie phiên tại callback. Hãy kiểm tra rằng:
  • Người dùng mở Overleaf tại địa chỉ của OVERLEAF_SITE_URL. Callback luôn đi tới OVERLEAF_SITE_URL, vì vậy một lần đăng nhập bắt đầu từ địa chỉ khác, chẳng hạn http://192.168.1.20 trong khi OVERLEAF_SITE_URL là https://overleaf.example.com, sẽ mất phiên của nó.
  • OVERLEAF_SECURE_COOKIE không được đặt khi Overleaf được phục vụ qua HTTP thông thường. Trình duyệt sẽ bỏ các cookie bảo mật trên HTTP. Bất kỳ giá trị nào cũng bật tùy chọn này, kể cả false, vì vậy hãy xóa dòng đó đi.
Invalid authorization request state có nghĩa là một lần đăng nhập mới hơn đã thay thế giá trị đã lưu, ví dụ sau khi đăng nhập từ hai tab cùng lúc hoặc quay lại trong trình duyệt khi đang đăng nhập. Hãy đóng các tab khác và bắt đầu đăng nhập lại từ trang đăng nhập Overleaf.
Lần sửa đổi cuối 2 tháng 11, 2026