Đăng ký ứng dụng Microsoft Graph

Quy trình cuộc họp của Teams đọc bản ghi cuộc họp, bản ghi và các tạo phẩm có liên quan từ Microsoft Graph bằng cách sử dụng xác thực chỉ ứng dụng (daemon) — không cần người dùng đăng nhập, không có sự đồng ý tương tác cho mỗi cuộc họp. Điều đó yêu cầu đăng ký ứng dụng Azure AD với quyền ứng dụng được quản trị viên đồng ý.

Hướng dẫn này đi qua:

1. Tạo đăng ký ứng dụng
2. Tạo bí mật khách hàng
3. Cấp quyền API Đồ thị mà quy trình cần
4. Sự đồng ý của quản trị viên về các quyền đó
5. (Tùy chọn) Xác định phạm vi ứng dụng cho những người dùng cụ thể bằng Chính sách truy cập ứng dụng

Bạn cần quyền quản trị viên của đối tượng (hoặc quản trị viên thay mặt bạn cấp sự đồng ý) để hoàn tất việc này. Đánh dấu các giá trị bạn thu thập — chúng đi vào ~/.hermes/.env ở cuối.

Điều kiện tiên quyết

• Người thuê Microsoft 365 có giấy phép Teams Premium hoặc Teams để tạo bản ghi và bản ghi cuộc họp
• Quyền truy cập của quản trị viên vào cổng Azure tại entra.microsoft.com
• Điểm cuối HTTPS có thể truy cập công khai dành cho thông báo thay đổi Biểu đồ (được thiết lập sau, trong bước trình nghe webhook)

Bước 1: Tạo Đăng ký ứng dụng

1. Đăng nhập vào entra.microsoft.com với tư cách quản trị viên đối tượng thuê.
2. Điều hướng đến Danh tính → Ứng dụng → Đăng ký ứng dụng.
3. Nhấp vào Đăng ký mới.
4. Điền vào:
   • Tên: ``Đường dẫn cuộc họp của Hermes Teams` (hoặc bất kỳ tên nào bạn có thể nhận ra).
   • Các loại tài khoản được hỗ trợ: Chỉ các tài khoản trong thư mục tổ chức này (Người thuê duy nhất).
   • URI chuyển hướng: để trống — không cần xác thực chỉ ứng dụng.
5. Nhấp vào Đăng ký.

Bạn sẽ đến trang tổng quan của ứng dụng. Sao chép hai giá trị:

• ID ứng dụng (ứng dụng khách) → MSGRAPH_CLIENT_ID
• ID thư mục (đối tượng thuê) → MSGRAPH_TENANT_ID

Bước 2: Tạo Bí mật khách hàng

1. Trong điều hướng bên trái, mở Chứng chỉ & bí mật.
2. Nhấp vào Bí mật khách hàng mới.
3. Mô tả: hermes-graph-secret. Hết hạn: chọn một giá trị phù hợp với chính sách xoay vòng của bạn (thông thường là 6-24 tháng).
4. Nhấp vào Thêm.
5. Sao chép ngay cột Giá trị — cột này chỉ hiển thị một lần. Giá trị đó là MSGRAPH_CLIENT_SECRET.

Cột Secret ID không phải là cột bí mật. Bạn muốn cột Giá trị.

Bước 3: Cấp quyền cho API đồ thị

Quy trình sử dụng một bộ quyền ứng dụng khả thi tối thiểu. Chỉ thêm những gì bạn cần; mỗi cái mở rộng những gì ứng dụng có thể đọc cho toàn bộ đối tượng thuê.

1. Trong điều hướng bên trái, hãy mở Quyền API.
2. Nhấp vào Thêm quyền → Microsoft Graph → Quyền ứng dụng.
3. Thêm các quyền từ bảng bên dưới phù hợp với những gì bạn muốn quy trình thực hiện.
4. Sau khi thêm, hãy nhấp vào Cấp sự đồng ý của quản trị viên cho <người thuê nhà của bạn>. Cột Trạng thái sẽ chuyển sang dấu kiểm màu xanh lục cho mọi quyền.

Bắt buộc đối với bản tóm tắt đầu tiên trong bảng điểm

Permission	What it lets the app do
OnlineMeetings.Read.All	Read Teams online meeting metadata (subject, participants, join URL).
OnlineMeetingTranscript.Read.All	Read meeting transcripts generated by Teams.

Cần thiết để ghi dự phòng (khi không có bản ghi)

Permission	What it lets the app do
OnlineMeetingRecording.Read.All	Download Teams meeting recordings for offline STT processing.
CallRecords.Read.All	Resolve meetings from call records when only the join URL is known.

Cần thiết để gửi bản tóm tắt gửi đi (Chỉ chế độ biểu đồ)

Nếu platforms.teams.extra.delivery_mode là graph, quy trình sẽ đăng các bản tóm tắt vào kênh Teams hoặc trò chuyện qua API Đồ thị. Hãy bỏ qua những điều này nếu bạn sử dụng chế độ phân phối incoming_webhook.

Permission	What it lets the app do
ChannelMessage.Send	Post messages into Teams channels on behalf of the app.
Chat.ReadWrite.All	Post messages into 1:1 and group chats (only if you set chat_id as the delivery target).

Không khuyến khích

• OnlineMeetings.ReadWrite.All / Chat.ReadWrite không có .All — rộng hơn nhu cầu của quy trình.
• Quyền được ủy quyền — quy trình sử dụng luồng chỉ dành cho ứng dụng (thông tin xác thực của khách hàng); quyền được ủy quyền sẽ không hoạt động nếu người dùng không đăng nhập.

Bước 4: (Khuyến nghị) Phạm vi ứng dụng với Chính sách truy cập ứng dụng

Theo mặc định, các quyền của ứng dụng như OnlineMeetings.Read.All cấp cho ứng dụng quyền truy cập vào mọi cuộc họp trong đối tượng thuê. Đối với các bản demo của đối tác và người thuê nhà phát triển thì điều đó là ổn; đối với sản xuất, bạn gần như chắc chắn muốn hạn chế những cuộc họp của người dùng mà ứng dụng có thể đọc.

Microsoft cung cấp Chính sách truy cập ứng dụng cho Teams chính xác cho việc này. Chính sách này chỉ dành cho PowerShell; không có giao diện người dùng cổng thông tin cho nó.

Từ quản trị viên PowerShell có cài đặt và kết nối mô-đun MicrosoftTeams (Connect-MicrosoftTeams):

# Create a policy scoped to the Hermes app
New-CsApplicationAccessPolicy `
  -Identity "Hermes-Meeting-Pipeline-Policy" `
  -AppIds "<MSGRAPH_CLIENT_ID>" `
  -Description "Restrict Hermes meeting pipeline to allow-listed users"

# Grant the policy to specific users whose meetings the pipeline may read
Grant-CsApplicationAccessPolicy `
  -PolicyName "Hermes-Meeting-Pipeline-Policy" `
  -Identity "alice@example.com"

Grant-CsApplicationAccessPolicy `
  -PolicyName "Chính sách Hermes-Meeting-Pipeline" `
  -Danh tính "bob@example.com"

Việc nhân giống có thể mất tới 30 phút sau khi cấp. Xác minh với:

Test-CsApplicationAccessPolicy -Identity "alice@example.com" -AppId "<MSGRAPH_CLIENT_ID>"

Nếu không có chính sách này, bất kỳ cuộc họp nào của người dùng đều có thể đọc được — đó là quyền cấp phép về mặt kỹ thuật. Đừng bỏ qua bước này đối với người thuê sản xuất.

Bước 5: Viết thông tin xác thực vào tệp Env của bạn

Đặt ba giá trị bạn đã thu thập vào ~/.hermes/.env:

MSGRAPH_TENANT_ID=<directory-tenant-id>
MSGRAPH_CLIENT_ID=<application-client-id>
MSGRAPH_CLIENT_SECRET=<client-secret-value>

Đặt quyền truy cập tệp để chỉ bạn mới có thể đọc được bí mật:

chmod 600 ~/.hermes/.env

Bước 6: Xác minh luồng Token

Hermes gửi bản thử nghiệm khói xác thực đồ thị. Từ bản cài đặt Hermes của bạn:

python -c "
import asyncio
from tools.microsoft_graph_auth import MicrosoftGraphTokenProvider
provider = MicrosoftGraphTokenProvider.from_env()
token = asyncio.run(provider.get_access_token())
print('Token acquired, length:', len(token))
print(provider.inspect_token_health())
"

Một lần chạy thành công sẽ in ra một chuỗi mã thông báo dài và một lệnh tình trạng hiển thị được lưu trong bộ nhớ đệm: True và giá trị expires_in_seconds gần 3600. Các lỗi tạo ra MicrosoftGraphTokenError với mã lỗi Azure — phổ biến nhất là:

Azure error	Meaning	Fix
AADSTS7000215: Invalid client secret	Secret value mismatched or expired.	Generate a new secret in step 2; update .env.
AADSTS700016: Application not found	Wrong MSGRAPH_CLIENT_ID or wrong tenant.	Double-check the values from step 1 are from the same app.
AADSTS90002: Tenant not found	Typo in MSGRAPH_TENANT_ID.	Copy the Directory (tenant) ID from the app overview again.
insufficient_claims at call time (not token time)	Token acquires but Graph returns 401/403.	You skipped step 3 admin-consent, or added permissions but haven't re-consented. Revisit API permissions and click Grant admin consent again.

Xoay bí mật của khách hàng

Bí mật của khách hàng Azure có thời hạn sử dụng khó khăn. Trước khi của bạn hết hạn:

1. Tạo bí mật khách hàng thứ hai ở bước 2 mà không xóa bí mật đầu tiên.
2. Cập nhật MSGRAPH_CLIENT_SECRET trong ~/.hermes/.env với giá trị mới.
3. Khởi động lại cổng để nhận được bí mật mới: ``khởi động lại cổng hermes`.
4. Xác minh bằng thử nghiệm khói ở trên.
5. Xóa bí mật cũ khỏi cổng Azure.

Các bước tiếp theo

Khi thông tin xác thực được xác minh rõ ràng, hãy tiếp tục với:

• Thiết lập trình nghe Webhook — thiết lập nền tảng cổng msgraph_webhook để nhận thông báo thay đổi Biểu đồ.
• Cấu hình đường dẫn — định cấu hình thời gian chạy đường dẫn cuộc họp Teams và toán tử CLI.
• Gửi đi — gửi bản tóm tắt trở lại kênh Nhóm hoặc trò chuyện.

Các trang đó nằm dọc theo các PR có thêm thời gian chạy tương ứng. Việc thiết lập thông tin xác thực này là điều kiện tiên quyết độc lập và có thể hoàn thành trước một cách an toàn.