> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/run-the-platform/vi/xac-thuc/azure-auth.md).

# Sử dụng Entra ID (Azure AD) cho xác thực

Hướng dẫn từng bước để cấu hình Microsoft Entra ID (Azure AD) làm nguồn ủy quyền OAuth2 trong VergeOS, bao gồm đăng ký ứng dụng, tích hợp nhóm và cấp phát người dùng.

VergeOS có thể được cấu hình để cho phép người dùng xác thực bằng thông tin xác thực Azure của công ty họ. Trang này sẽ hướng dẫn bạn qua quá trình cấu hình.

## Cấu hình nguồn ủy quyền Entra ID

1. Trong các dịch vụ Azure: đăng ký một ứng dụng web một tenant, đặt ***URI chuyển hướng*** thành URL của hệ thống VergeOS và tạo một client secret mới. **Azure Active Directory > Đăng ký ứng dụng > Đăng ký mới** ![azurereg1.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-bb5217dce60d2b5fbc13525b6c4d55fde916fd24%2Fazurereg1.png?alt=media)

   ![azurereg2.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-b0d802ab9f75bd8da9c880b685efdbf1c08482cb%2Fazurereg2.png?alt=media)
2. Tạo một client secret mới. **Đăng ký ứng dụng > Thông tin xác thực ứng dụng > Thêm chứng chỉ hoặc bí mật. Nhấp +Bí mật ứng dụng mới.**

   * Nhập một **mô tả và ngày hết hạn** cho client secret mới.
   * **Lấy các thông tin sau từ Azure** để dùng trong cấu hình nguồn ủy quyền trong VergeOS:
     * **Tenant ID** - **gợi ý:&#x20;*****Tất cả dịch vụ > Azure Active Directory > Tổng quan.*****&#x20;Tenant ID được liệt kê trong Thông tin cơ bản.**
     * **Client ID** - **gợi ý:&#x20;*****Đăng ký ứng dụng Azure > Mục đã cấu hình > Thông tin xác thực ứng dụng***
     * **Client Secret** - **gợi ý:&#x20;*****Đăng ký ứng dụng Azure > Mục đã cấu hình > Thông tin xác thực ứng dụng*****&#x20;Sử dụng trường "VALUE".**

   ![azureclientsecretadd.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-c610e7f4a2b6df1024f288adee4abc9a8b7e2645%2Fazureclientsecretadd.png?alt=media) ![azureclientsecret2.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-0984cccf8b287e22110087cb9a1a6dd3480b234b%2Fazureclientsecret2.png?alt=media)
3. Nhấp **Hệ thống** trên menu trên cùng.
4. Chọn **Nguồn xác thực**.
5. Nhấp **Mới** trên menu bên trái.
6. Nhập một ***Tên*** cho nguồn (chẳng hạn như "Azure"). Tên này sẽ xuất hiện trên nút đăng nhập của trang đăng nhập VergeOS. ![azureauthform.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-e9db0034056da44a679926f7e04c71f9a7a4ecfa%2Fazureauthform.png?alt=media)
7. Trong ***Trình điều khiển*** trường (danh sách thả xuống), chọn **Azure AD**.
8. Nhập ***Tenant ID*** đã lấy ở bước trước.
9. Trường ***URI chuyển hướng*** phải là URL đến hệ thống VergeOS của bạn (ví dụ: https\:/\[]/verge.io.mycompanyabc.com)
10. Nhập ***URL điểm cuối để người dùng đăng xuất mã phiên*** (https\:/\[]/login.microsoftonline.com/***TENANTID***/oauth2/v2.0/logout)
11. ***Phạm vi*** thường nên để ở giá trị mặc định: "OpenID profile email".
12. ***Phạm vi nhóm*** cần được thiết lập nếu người dùng sẽ được tự động tạo dựa trên tư cách thành viên nhóm; thông thường, mục này được đặt thành từ "groups" mà không có dấu câu.
13. Nhập ***Client ID*** đã lấy ở bước trước.
14. Nhập ***Client Secret*** đã lấy ở bước trước.
15. ***Các trường người dùng từ xa*** xác định danh sách các trường được dùng để tìm người dùng Azure ban đầu; trường này được tự động điền với (sub,preferred\_username,email nickname), một danh sách mặc định thường có thể hoạt động cho hầu hết các triển khai. **Lưu ý: Vì lý do bảo mật, không khuyến nghị xác định người dùng từ xa dựa trên các trường mà người dùng cuối có thể thay đổi trên hệ thống từ xa.**
16. Để chuyển tiếp tư cách thành viên nhóm từ Azure sang VergeOS, hãy chọn hộp kiểm ***Cập nhật tư cách thành viên nhóm*** . Nhóm phải được tạo trong VergeOS theo hướng dẫn bên dưới.
17. **Tính năng tự động tạo người dùng (tùy chọn)**: Người dùng có thể được tự động tạo khi đăng nhập lần đầu vào VergeOS; có thể chọn cho tất cả người dùng Entra ID -HOẶC- giới hạn cho người dùng trong các nhóm Entra ID được chỉ định.
    * ***Tự động tạo người dùng*** - Nếu tất cả người dùng nên được tự động tạo, hãy nhập `.*` tại đây.
    * ***Tự động tạo người dùng trong nhóm*** - Để chỉ tự động tạo người dùng là thành viên của các nhóm Entra ID được chỉ định, hãy nhập ID đối tượng của nhóm ở dạng biểu thức chính quy (regex).

{% hint style="info" %}
**Tự động tạo người dùng trong các nhóm**

* Trường **Phạm vi nhóm** phải được định nghĩa. (Trường Phạm vi nhóm được định nghĩa ở trên)
* **Cấu hình token** phải được thiết lập trong Entra ID (hướng dẫn bên dưới).
* Entra ID **các nhóm** được chỉ định để Tự động tạo **phải được tạo ở phía VergeOS** (hướng dẫn bên dưới).
* Để tự động tạo dựa trên nhóm, ***Tự động tạo người dùng*** **trường phải để trống**
* Có thể nhập nhiều ID nhóm cụ thể theo định dạng: (ID)|(ID)|(ID)
  {% endhint %}

18. **Tùy chọn (khuyến nghị bật):**

* ***Cập nhật người dùng từ xa:*** - sau khi người dùng được xác định trong Entra ID, cập nhật người dùng VergeOS *Tên người dùng từ xa* thành ID duy nhất tương ứng của Azure.

{% hint style="success" %}
**Việc bật Cập nhật người dùng từ xa sẽ cho phép hệ thống VergeOS lưu ID duy nhất của Azure trong bản ghi người dùng VergeOS (sau khi ban đầu xác định người dùng Entra ID bằng các trường được định nghĩa trong Các trường người dùng từ xa), để mã định danh duy nhất sau đó có thể được dùng để tìm người dùng Entra ID; điều này thường được khuyến nghị vì các trường như địa chỉ email có thể thay đổi.**
{% endhint %}

* ***Cập nhật địa chỉ email người dùng:*** - Cập nhật địa chỉ email người dùng VergeOS để khớp với địa chỉ email trong Entra ID.
* ***Cập nhật tên hiển thị người dùng:*** - Cập nhật tên hiển thị của người dùng VergeOS để khớp với tên hiển thị trong Entra ID.
* ***Cập nhật tư cách thành viên nhóm:*** - Cập nhật các nhóm mà người dùng VergeOS là thành viên. (Cần có Phạm vi nhóm để chức năng này hoạt động.)

19. **Các trường tùy chọn bổ sung:** Xem [**Nguồn xác thực (Chung)**](https://docs.verge.io/run-the-platform/vi/xac-thuc/auth-sources-general.md) để biết thông tin về các trường tùy chọn bổ sung.

## Thêm nhóm Azure vào VergeOS

Tích hợp với các nhóm Azure yêu cầu một token trên đăng ký ứng dụng Entra ID và việc tạo nhóm trong VergeOS:

### Thiết lập cấu hình token trong Entra ID

1. Đi tới **trang đăng ký ứng dụng** cho App đã tạo ở trên.
2. Nhấp vào **Cấu hình token** trên menu bên trái và nhấp **+Thêm khai báo nhóm**.
3. Chọn các **loại nhóm**.
4. Đặt **ID, Access và SAML thành sAMAccountName**.

![azure-editgroupsclaim.pn](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-24b1f0220d3e8fb693bfde10d1a6b8bc186f1012%2Fazure-editgroupsclaim.png?alt=media)

### Các bước thêm nhóm Azure

1. Đi tới **Hệ thống > Nhóm.**
2. Nhấp **Mới** trên menu bên trái.
3. Nhập nhóm ***Tên*** để khớp với tên nhóm trong Entra ID.
4. Tùy chọn, một ***Email*** có thể được nhập cho nhóm. Địa chỉ email này được dùng để gửi cảnh báo đăng ký và/hoặc báo cáo được gán cho nhóm.
5. Sao chép **Object Id** tương ứng từ trang Groups/All Groups trong Entra ID vào ***trường Identifier*** .
6. Nhấp **Gửi** (ở cuối trang) để lưu nhóm mới.

![azure-groupspage.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-82bed5065e0cf17ab7b46e6fd3b73037e16cfc40%2Fazure-groupspage.png?alt=media)

![azure-creategroup.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-df56aab13c11b1297fa9c58d855f1404cd45c165%2Fazure-creategroup.png?alt=media)

## Thêm người dùng thủ công từ Azure

Sau khi nguồn xác thực Azure được tạo, người dùng có thể được tạo thủ công trong VergeOS để sử dụng nguồn ủy quyền này cho xác thực đăng nhập. Việc tạo thủ công người dùng chỉ cần thiết khi người dùng không được cấu hình để tự động tạo.

### Thêm người dùng VergeOS sẽ dùng xác thực Entra ID

Khi tạo người dùng mới, hãy dùng cấu hình sau:

* ***Nguồn ủy quyền:*** Chọn nguồn Entra ID từ danh sách thả xuống
* ***Tên người dùng:*** tên duy nhất trong hệ thống VergeOS; thông thường nên dùng tên principal Azure.
* ***Tên người dùng từ xa:*** dùng giá trị của một trong các trường được định nghĩa là *các trường người dùng từ xa* đây là các trường được tìm kiếm trong Azure (ví dụ: tên người dùng, email)
* ***Tên hiển thị:*** (tùy chọn) Nếu *Cập nhật tên hiển thị người dùng* được bật trên nguồn xác thực Entra ID, tên hiển thị sẽ tự động đồng bộ từ Entra ID.
* ***Địa chỉ email:*** (tùy chọn) Nếu *Cập nhật địa chỉ email người dùng* được bật trên nguồn xác thực Entra ID, địa chỉ email sẽ tự động đồng bộ từ Entra ID.

![azure-newuser.png](https://1198484664-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpODKGSQETqL1gSqyxIq3%2Fuploads%2Fgit-blob-542e4c78a054f2f87e170465de77547161eb9ae2%2Fazure-newuser.png?alt=media)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/run-the-platform/vi/xac-thuc/azure-auth.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
