Nội dung

• 1. Giới thiệu & Điều kiện cấu hình
• 2. Quy trình cấu hình tổng quan
• 3. Bước 1: Khởi tạo OAuth Provider trên 1Office
• 4. Bước 2: Tạo App Registration trên Microsoft Azure Portal
• 5. Bước 3: Lấy Client ID, tạo Secret và cấp quyền API
• 6. Bước 4: Hoàn tất cấu hình OAuth Provider trên 1Office
• 7. Bước 5: Thêm Tài khoản gửi và xác thực kết nối
• 8. Bảng kiểm tra & Xử lý sự cố thường gặp (Troubleshooting)

1. Giới thiệu & Điều kiện cấu hình

Tính năng tích hợp Office 365 (OAuth 2.0) cho phép doanh nghiệp kết nối hòm thư Microsoft 365 / Outlook trực tiếp vào 1Office qua Microsoft Graph API hiện đại, thay thế hoàn toàn chuẩn Basic Auth (SMTP) cũ đã bị Microsoft ngừng hỗ trợ. Tính năng phục vụ gửi email thông báo hệ thống, thông báo duyệt đơn từ, quy trình tự động (Workflow) và gửi email chăm sóc khách hàng.

2. Quy trình cấu hình tổng quan

Quy trình tích hợp gồm 5 bước tuần tự:

1. Bước 1: Khởi tạo OAuth Provider trên 1Office (khai báo loại Microsoft, Grant Type, Tenant common).
2. Bước 2: Tạo mới App Registration trên Microsoft Azure Portal (lấy Redirect URI từ 1Office).
3. Bước 3: Lấy Application (Client) ID, tạo Client Secret và phân quyền API Microsoft Graph (Mail.Send, offline_access).
4. Bước 4: Hoàn tất cấu hình OAuth Provider trên 1Office (dán Client ID và Client Secret Value).
5. Bước 5: Thêm mới Tài khoản gửi và bấm Kết nối Microsoft để ủy quyền.

3. Bước 1: Khởi tạo OAuth Provider trên 1Office

Các bước thực hiện:

• Bước 1: Đăng nhập 1Office bằng tài khoản Quản trị viên.
• Bước 2: Truy cập biểu tượng Cài đặt (bánh răng cưa góc trên bên phải) → chọn Cài đặt tích hợp → chọn menu OAuth Provider.
• Bước 3: Bấm nút Thêm mới (+) để tạo một cấu hình OAuth Provider mới.

[Hình ảnh 1.1: Truy cập Danh sách OAuth Provider trên 1Office và bấm Tạo mới 1 OAuth provider]

• Bước 4: Tại form thiết lập OAuth Provider, điền các thông tin sau:
  • Loại Provider: Chọn biểu tượng Microsoft.
  • Tên hiển thị: Nhập tên gợi nhớ (Ví dụ: Microsoft Graph Mail hoặc Office 365 Hệ thống).
  • Phạm vi: Tích chọn Mail (gửi email hệ thống).
  • Grant Type: Chọn Authorization Code (User consent).
  • Tenant / Authority: Nhập chính xác: common.

[Hình ảnh 1.2: Thiết lập thông tin ban đầu cho Microsoft OAuth Provider]

4. Bước 2: Tạo App Registration trên Microsoft Azure Portal

Các bước thực hiện:

• Bước 1: Mở tab trình duyệt mới, đăng nhập vào cổng quản trị portal.azure.com.
• Bước 2: Tìm kiếm dịch vụ App registrations (Đăng ký ứng dụng) trên thanh tìm kiếm của Azure.
• Bước 3: Nhấp vào nút + New registration (Đăng ký mới).

[Hình ảnh 2.1: Truy cập App registrations trên Azure Portal và chọn New registration]

• Bước 4: Tại trang Register an application, thiết lập các trường thông tin:
  • Name: Đặt tên ứng dụng (Ví dụ: 1Office Mail Sender).
  • Supported account types: Chọn tùy chọn thứ 3:
    “Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox)”.
  • Redirect URI (optional):
    Dropdown chọn loại: Web.
    Nhập chính xác đường dẫn Callback của 1Office:
    https://.1office.vn/app/oauth/callback/microsoft
    (Thay bằng đúng tên miền tenant của đơn vị bạn, ví dụ: https://acme.1office.vn/app/oauth/callback/microsoft).
• Bước 5: Bấm nút Register ở cuối trang để hoàn tất tạo ứng dụng.

[Hình ảnh 2.2: Khai báo Name, Account Types và Redirect URI trên Azure Portal]

5. Bước 3: Lấy Client ID, tạo Secret và cấp quyền API

5.1. Lấy Application (Client) ID:

• Tại menu bên trái của App vừa tạo, chọn mục Overview.
• Tìm trường Application (client) ID và bấm biểu tượng Copy để lưu lại.

[Hình ảnh 3.1: Sao chép Application (client) ID tại trang Overview]

5.2. Khởi tạo Client Secret:

• Ở menu bên trái, chọn mục Certificates & secrets → Chọn tab Client secrets → Bấm + New client secret.
• Nhập mô tả tại ô Description và chọn thời hạn hết hạn tại ô Expires (khuyến nghị 180 ngày hoặc 24 tháng theo chính sách bảo mật) → Bấm Add.

[Hình ảnh 3.2: Thêm mới một Client Secret]

• Sau khi bấm Add, tại danh sách hiển thị, hãy sao chép ngay chuỗi tại cột Value.

[Hình ảnh 3.3: Sao chép chuỗi tại cột Value của Client Secret]

5.3. Cấp quyền API (API Permissions):

• Tại menu bên trái, chọn mục API permissions → Bấm nút + Add a permission.
• Tại cửa sổ Request API permissions, bấm chọn Microsoft Graph.
• Bấm chọn ô Delegated permissions (Ủy quyền người dùng).

[Hình ảnh 3.4 & 3.5 & 3.6: Chọn API permissions → Microsoft Graph → Delegated permissions]

• Tìm kiếm và tích chọn chính xác 2 quyền sau:
  • Tìm Mail.Send → mở rộng nhóm Mail → tích chọn Mail.Send (Send mail as a user).
  • Tìm offline_access → mở rộng nhóm OpenId permissions → tích chọn offline_access (Duy trì quyền truy cập để hệ thống tự cấp refresh token).
• Bấm nút Add permissions ở góc dưới để lưu lại quyền.
• Kiểm tra danh sách Configured permissions, đảm bảo đủ 3 quyền: User.Read, Mail.Send, và offline_access.

[Hình ảnh 3.7 & 3.8 & 3.9: Tích chọn Mail.Send, offline_access và kiểm tra danh sách quyền]

6. Bước 4: Hoàn tất cấu hình OAuth Provider trên 1Office

Các bước thực hiện:

• Bước 1: Quay trở lại tab 1Office đang mở ở Bước 1.
• Bước 2: Dán các thông tin đã lấy được từ Azure vào form:
  • Client ID: Dán chuỗi Application (client) ID từ Bước 5.1.
  • Client Secret: Dán chuỗi Value từ Bước 5.2.
  • Đảm bảo ô Tenant: vẫn có giá trị là common.
• Bước 3: Bấm nút Cập nhật (hoặc Lưu) để lưu lại cấu hình OAuth Provider.

7. Bước 5: Thêm Tài khoản gửi và kết nối Microsoft

7.1. Khởi tạo tài khoản email gửi:

• Trên 1Office, truy cập menu: Cài đặt → Cài đặt tích hợp → Tài khoản gửi.
• Bấm nút Thêm mới (+).
• Tại ô Loại tài khoản / Dịch vụ, nhấp chọn: Office 365 (OAuth 2.0).
• Nhập các thông tin chi tiết:
  • Tên hiển thị: Tên đại diện người gửi hiển thị với người nhận thư (Ví dụ: Ban Chăm Sóc Khách Hàng, Hệ thống 1Office).
  • Email gửi: Nhập chính xác địa chỉ email Microsoft 365 sẽ dùng để gửi thư (Ví dụ: cskh@doanhnghiep.com).
• Bấm nút Cập nhật để tạo bản ghi.

[Hình ảnh 5.1 & 5.2 & 5.3: Thêm mới tài khoản gửi → Chọn Office 365 OAuth 2.0 → Điền tên và email]

7.2. Xác thực ủy quyền kết nối (OAuth Consent):

• Tại danh sách tài khoản gửi, nhấp vào bản ghi email vừa tạo để mở lại form chi tiết.
• Tại khu vực Thông tin kết nối, nhấp vào nút: KẾT NỐI MICROSOFT.

[Hình ảnh 5.4: Nhấp nút KẾT NỐI MICROSOFT để tiến hành ủy quyền]

• Cửa sổ đăng nhập Microsoft mở ra:
  • Đăng nhập bằng đúng tài khoản email Microsoft 365 đã khai báo ở trên.
  • Khi xuất hiện màn hình yêu cầu cấp quyền (Permissions requested), nhấp nút Accept (Chấp nhận).
• Sau khi ủy quyền thành công, màn hình trên 1Office sẽ chuyển sang trạng thái có dấu tích xanh: Đã kết nối: .
• Nhấp nút KIỂM TRA KẾT NỐI để hệ thống gửi thử một email thử nghiệm, đảm bảo hòm thư hoạt động ổn định.

[Hình ảnh 5.5: Hệ thống hiển thị trạng thái Đã kết nối thành công]

8. Bảng kiểm tra & Xử lý sự cố thường gặp (Troubleshooting)