> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/on-premises/vi/cau-hinh/overleaf-toolkit/authentication/oidc-authentication.md).

# Xác thực OIDC

Tính năng này được phát triển bởi [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Ở đây chúng tôi cung cấp một số tài liệu cho cấu hình của bạn.

### Cấu hình

Về mặt nội bộ, mô-đun OIDC của Overleaf sử dụng [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect) thư viện. Nếu bạn gặp sự cố khi cấu hình OpenID Connect, đáng để đọc README của `passport-openidconnect` để nắm được cách cấu hình mà nó mong đợi.

Biến môi trường `EXTERNAL_AUTH` là bắt buộc để bật mô-đun 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 Danh tính (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 một bản ghi chứa `thirdPartyIdentifiers` trường được cấu trúc như sau:

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

Trường `externalUserId` phải khớp với ID người dùng trong hồ sơ do máy chủ IdP trả về (xem `OVERLEAF_OIDC_USER_ID_FIELD` biến môi trường), 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 khớ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 IdP:

* Nếu tìm thấy người dùng như vậy, thì `thirdPartyIdentifiers` trường sẽ được cập nhật.
* Nếu không tìm thấy người dùng khớp và việc tạo tài khoản JIT không bị vô hiệu hóa, một người dùng mới sẽ được tạo với địa chỉ email và `thirdPartyIdentifiers` từ hồ sơ IdP.

Trong cả hai trường hợp, người dùng được coi là đã 'liên kết' với người dùng OIDC bên ngoài. Người dùng có thể được hủy liên kết khỏi nhà cung cấp OIDC trên `/user/settings` trang.

#### Các 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 bằng cách sử dụng `.well-known/openid-configuration` điểm cuối của Nhà cung cấp OpenID (OP) của bạ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 sẽ được 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 `Tài khoản đã liên kết` phần của `/user/settings` trang, mặc định là `Nhà cung cấp OIDC`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Tên hiển thị cho dịch vụ danh tính, đượ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ả của OP, được dùng trong `Tài khoản đã liên kết` mục (mặc định: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * `Tìm hiểu thêm` URL trong mô tả OP, mặc định: không có `Tìm hiểu thêm` liên kết trong phần mô tả.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Không hiển thị OP trên `/user/settings` trang, 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 `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ể là `email` và `tên người dùng` (tương ứng với `preferred_username` claim OIDC).
* `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 danh sách tên miền phân tách bằng dấu phẩy, một tài khoản mới chỉ được tạo nếu tên miền của địa chỉ email người dùng khớp với một trong các tên miền đã liệt kê. Nếu tên miền không khớp, quản trị viên phải tạo thủ công tài khoản người dù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, không có `hashedPassword` trường này. Tên miền có thể bao gồm một ký tự đại diện ở đầu `*.` để khớp với các tên miền phụ.
    * 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ụ: Để vô hiệu hóa 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ập nhật thông tin người dùng `first_name` và `last_name` trường khi đăng nhập, và vô hiệu hóa biểu mẫu thông tin người dùng trên `/user/settings` trang.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` và `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Khi cả hai biến môi trường đề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ó khớp với `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`, nếu không thì `user.isAdmin` đượ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` đượ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`.

<details>

<summary>Tệp variables.env mẫu</summary>

{% code title="variables.env" overflow="wrap" %}

```dotenv
OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Bật tạo hình thu nhỏ bằng ImageMagick
ENABLE_CONVERSIONS=true

# Tắt yêu cầu xác nhận email
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Thiết lập TLS qua nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Phiên bản Overleaf của chúng tôi
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com

OVERLEAF_LEFT_FOOTER=[{"text": "Liên hệ đội hỗ trợ của bạn", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Xin chào, tôi ở bên phải", "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=Hệ thống này do department x vận hành

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## OIDC cho 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
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://overleaf-pro.ayaka.space/on-premises/vi/cau-hinh/overleaf-toolkit/authentication/oidc-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.