Phân Phối Trực Tiếp Bằng Developer ID Nghĩa Là Gì

Có hai cách chính để đưa ứng dụng macOS đến tay người dùng. Một là thông qua Mac App Store (MAS), hai là phân phối trực tiếp (direct distribution) — cho người dùng tải về file .dmg (hoặc .app) mà bạn tự tạo từ website, GitHub hay nơi tương tự.

Phân phối trực tiếp có những lợi thế rõ ràng. Bạn không cần chờ App Store phê duyệt, không mất phí hoa hồng, và có thể phát hành bản cập nhật bất cứ lúc nào theo cách mình muốn. Đổi lại, những việc mà App Store từng làm thay — ký code, công chứng (notarization), và cập nhật tự động — giờ bạn phải tự lo liệu.

Nếu không chuẩn bị những điều này, cơ chế bảo mật Gatekeeper của macOS sẽ ngăn ứng dụng khởi chạy. Khi người dùng mở ứng dụng lần đầu, họ sẽ thấy cảnh báo kiểu “không thể mở ứng dụng này vì nó đến từ nhà phát triển chưa được xác định”, và hầu hết người dùng sẽ bỏ cuộc ngay tại đó. Để ứng dụng mở bằng cú đúp đơn giản như bất kỳ ứng dụng được phân phối đúng cách nào, bạn cần ký ứng dụng bằng chứng chỉ Developer ID và được Apple công chứng.

Series này đề cập đến quá trình cài đặt ban đầu đó. Một tin vui là hầu hết các thiết lập ở đây đều chỉ cần làm một lần và tái sử dụng cho mọi lần phát hành.

Những Gì Bạn Sẽ Xây Dựng Trong Series Này

Qua ba phần, bạn sẽ chuẩn bị được những thứ sau.

  • (Phần 1, bài này) Chứng chỉ Developer ID Application + thông tin xác thực để công chứng
  • (Phần 2) Khóa ký EdDSA cho cập nhật tự động Sparkle
  • (Phần 3) Repository công khai để lưu trữ update feed + hoàn thiện cài đặt build

Khi kết thúc series, bạn cần có sẵn những thứ sau đây. Bây giờ hãy lướt qua danh sách; mỗi phần sẽ điền vào từng mục một.

  • Chứng chỉ Developer ID Application trong macOS Keychain
  • Hồ sơ thông tin xác thực công chứng được lưu trong Keychain
  • Cặp khóa EdDSA để ký bản cập nhật Sparkle (khóa công khai + khóa riêng tư)
  • Sao lưu khóa riêng tư ở nơi an toàn
  • Repository GitHub công khai + GitHub Pages để lưu trữ update feed (appcast)
  • File cài đặt build (ExportOptions.plist) và cấu hình phía ứng dụng

Ứng Dụng Mẫu — FocusTimer

Series này sử dụng ứng dụng macOS giả tưởng FocusTimer (một ứng dụng đếm thời gian đơn giản để quản lý thời gian tập trung) làm ví dụ xuyên suốt. Tên FocusTimer, bundle identifier com.example.FocusTimer, domain example.com, tên chứng chỉ, Team ID, v.v. xuất hiện trong các lệnh và đường dẫn đều là giá trị mẫu. Khi thực hành, hãy thay thế bằng tên ứng dụng và thông tin tài khoản của bạn.

Bài viết này được viết dựa trên Xcode 26 và Sparkle 2.x (framework cập nhật tự động, xuất hiện ở Phần 2). Apple thường thay đổi bố cục màn hình và vị trí menu, vì vậy dù tên nút có hơi khác, hãy hiểu rằng luồng tổng thể vẫn giống nhau.

Điều Kiện Tiên Quyết — Công Cụ Dòng Lệnh

Trước tiên, hãy cài đặt hai công cụ dòng lệnh cần thiết cho tự động hóa build và phát hành. Phần này giả sử bạn đã cài trình quản lý gói macOS Homebrew.

brew install gh create-dmg
  • gh — CLI chính thức của GitHub. Bạn sẽ dùng nó sau này để tạo GitHub Releases.
  • create-dmg — Công cụ tạo file ảnh đĩa .dmg để phân phối. Nó cũng tạo ra màn hình hướng dẫn người dùng kéo ứng dụng vào thư mục Applications.

Bạn chưa dùng ngay bây giờ, nhưng script tự động hóa phát hành thường được thiết kế để kiểm tra sự tồn tại của các công cụ này trước và dừng ngay nếu thiếu, vì vậy hãy cài trước.

Bước 1 — Xác Nhận Tư Cách Thành Viên Apple Developer Program

Để cấp chứng chỉ Developer ID và công chứng ứng dụng, bạn cần tư cách thành viên Apple Developer Program. Với tài khoản cá nhân, đây là chương trình có phí, $99 mỗi năm.

Nếu bạn đã đăng ký, chỉ cần xác nhận còn hiệu lực.

  1. Truy cập developer.apple.com/account
  2. Trong phần Membership details, xác nhận trạng thái là Active
  3. Trên cùng màn hình đó, ghi lại Team ID của bạn (trong ví dụ là ABCDE12345). Nó được dùng suốt các bước sau.

Nếu bạn chưa đăng ký, việc phê duyệt tư cách thành viên thường mất khoảng một ngày. Không thể cấp chứng chỉ trước khi được phê duyệt, vì vậy tốt nhất hãy xử lý việc này trước tiên.

Bước 2 — Cấp Chứng Chỉ Developer ID Application

Chứng chỉ Developer ID Application là chứng chỉ dùng để ký .app và .dmg bạn phân phối. macOS Gatekeeper nhận ra ứng dụng được ký bằng chứng chỉ này là “ứng dụng được tạo bởi nhà phát triển đã biết”.

Apple cũng có chứng chỉ Developer ID Installer riêng để ký các gói cài đặt .pkg. Vì series này phân phối qua .dmg, chúng ta chỉ đề cập đến chứng chỉ Application.

Quy Trình Cấp

Cách đơn giản nhất là thông qua Xcode.

  1. Mở Xcode → menu Xcode → Settings… (⌘,)
  2. Chọn tab Accounts → nhấp vào Apple ID của bạn trong danh sách bên trái
  3. Nhấp nút Manage Certificates… ở dưới cùng bên phải
  4. Trong cửa sổ mới mở ra, nhấp nút + ở dưới cùng bên trái
  5. Chọn Developer ID Application từ menu
  6. Sau một hoặc hai giây, chứng chỉ mới xuất hiện trong danh sách — nhấp Done

Chứng chỉ được cấp theo cách này sẽ tự động được lưu vào Keychain của macOS. Chứng chỉ và khóa riêng tư tương ứng được lưu cùng nhau thành một cặp, và khóa riêng tư này mới là thứ cho phép ký.

Xác Nhận Việc Cấp

Trong terminal, chạy lệnh sau để xác nhận chứng chỉ đã được cài đặt đúng.

security find-identity -v -p codesigning | grep "Developer ID Application"

Nếu một dòng như sau xuất hiện, nghĩa là thành công.

  1) A1B2C3D4E5F6...  "Developer ID Application: Gildong Hong (ABCDE12345)"

Chuỗi ký tự trong dấu ngoặc kép là tên chính thức của chứng chỉ. Gildong Hong là tên đã đăng ký trên tài khoản Apple, và ABCDE12345 trong ngoặc đơn là Team ID bạn đã ghi lại ở Bước 1. Tên này được dùng nguyên vẹn khi tự động hóa ký code sau này, vì vậy hãy kiểm tra kỹ một lần nữa.

Gia Hạn Chứng Chỉ

Chứng chỉ Developer ID có hiệu lực 5 năm. Khi gần hết hạn, nó sẽ được đánh dấu Expired trong danh sách Manage Certificates của Xcode. Khi đó, chỉ cần cấp chứng chỉ mới theo đúng quy trình như trên.

Tin vui là các ứng dụng đã được ký và phân phối bằng chứng chỉ cũ không bị vô hiệu hóa ngay khi nó hết hạn. Chỉ những build mới tạo ra từ đây trở đi mới cần ký bằng chứng chỉ mới. Vì vậy không cần lo lắng quá nhiều về việc hết hạn.

Bước 3 — Đăng Ký Mật Khẩu Dành Riêng Cho App Để Công Chứng

Công Chứng (notarization) Là Gì?

Công chứng là quy trình tải ứng dụng lên máy chủ Apple trước khi phân phối để quét phần mềm độc hại. Nếu vượt qua quét, Apple cấp “vé công chứng”, và vé đó phải được đính kèm vào ứng dụng để Gatekeeper mở ứng dụng mà không có cảnh báo. Nếu việc ký chứng minh “ai đã tạo ra nó”, thì công chứng là một quy trình riêng biệt chứng minh “Apple đã quét nó một lần”.

Việc nộp công chứng sử dụng lệnh notarytool của Apple, lệnh này yêu cầu mật khẩu Apple ID mỗi lần bạn nộp. Để tránh nhập mỗi lần, bạn tạo mật khẩu dành riêng cho app (app-specific password) và lưu vào Keychain trước.

3-1. Cấp Mật Khẩu Dành Riêng Cho App

Mật khẩu dành riêng cho app là mật khẩu 16 ký tự chỉ dùng cho một mục đích cụ thể, thay cho mật khẩu Apple ID chính của bạn.

  1. Truy cập appleid.apple.com → đăng nhập bằng Apple ID đã đăng ký Apple Developer Program (trong ví dụ là [email protected])
  2. Vào Sign-In and Security → chọn App-Specific Passwords
  3. Nhấp nút + → nhập tên cho mật khẩu (ví dụ: focustimer-notarize)
  4. Nhấp Create → nhập mật khẩu Apple ID của bạn một lần nữa
  5. Mật khẩu 16 ký tự có dạng abcd-efgh-ijkl-mnop xuất hiện trên màn hình.

Khi bạn đóng màn hình này, bạn không thể xem lại mật khẩu nữa. Trước khi chuyển sang bước tiếp theo, hãy sao chép tạm vào trình quản lý mật khẩu hoặc nơi tương tự.

3-2. Lưu Vào Hồ Sơ notarytool

Lưu mật khẩu bạn nhận được dưới dạng hồ sơ Keychain. Trong lệnh bên dưới, hãy thay giá trị --password bằng mật khẩu thực tế bạn vừa nhận trước khi chạy.

xcrun notarytool store-credentials "focustimer-notarize" \
  --apple-id "[email protected]" \
  --team-id "ABCDE12345" \
  --password "abcd-efgh-ijkl-mnop"
  • Đối số đầu tiên "focustimer-notarize" — tên đặt cho hồ sơ này. Từ nay, bạn sẽ tải thông tin xác thực bằng tên này khi công chứng.
  • --apple-id — email của tài khoản Apple Developer Program
  • --team-id — Team ID từ Bước 1
  • --password — mật khẩu dành riêng cho app được cấp ở 3-1

Nếu xuất hiện đầu ra sau, nghĩa là thành công.

Credentials saved to Keychain.

Bây giờ thông tin xác thực đã được lưu trong Keychain, bạn không cần mật khẩu dành riêng cho app gốc nữa. (Tuy nhiên, nếu bạn có kế hoạch build trên các máy tính khác, tiện hơn nếu giữ nó trong trình quản lý mật khẩu.)

3-3. Xác Nhận

Kiểm tra xem hồ sơ đã lưu có thực sự hoạt động không.

xcrun notarytool history --keychain-profile "focustimer-notarize"

Nếu thông báo Successfully received submission history. xuất hiện, mọi thứ đều ổn. Lịch sử nộp bên dưới có thể trống (điều này bình thường vì bạn chưa công chứng gì cả) hoặc có thể chứa các bản ghi trước đó.

Bẫy Quan Trọng — Tài Khoản Apple ID và GitHub Khác Nhau

Đây là điểm mà người thiết lập phân phối trực tiếp lần đầu thường vướng mắc nhất.

  • Tài khoản Apple Developer Program — dùng để cấp chứng chỉ và công chứng (ví dụ: [email protected])
  • Tài khoản GitHub — dùng ở Phần 3 để lưu trữ file cập nhật (ví dụ: [email protected])

Trong nhiều trường hợp, hai tài khoản này có email khác nhau. Đặc biệt, --apple-id của notarytool store-credentials phải là email tài khoản Apple Developer. Nếu bạn nhập email tài khoản GitHub, xác thực sẽ thất bại — và thông báo lỗi không thân thiện nên rất khó tìm ra nguyên nhân.

Nếu email của hai tài khoản dễ nhầm lẫn, chúng tôi khuyên bạn nên ghi chú xem tài khoản nào là dành cho Apple và tài khoản nào là dành cho GitHub. Sự phân biệt này xuất hiện lặp đi lặp lại trong suốt series.

Tổng Kết Phần 1

Nếu bạn đã làm theo đến đây, bây giờ bạn có:

  • ✅ Công cụ dòng lệnh để tự động hóa phát hành (gh, create-dmg)
  • ✅ Tư cách thành viên Apple Developer Program đang hoạt động
  • ✅ Chứng chỉ Developer ID Application được lưu trong Keychain
  • ✅ Hồ sơ thông tin xác thực công chứng được lưu trong Keychain (focustimer-notarize)

Với điều này, bạn đã sẵn sàng để ký và công chứng ứng dụng. Nhưng hầu như không có ứng dụng nào chỉ giao cho người dùng một lần rồi xong. Bạn phải tiếp tục phát hành các phiên bản mới sửa lỗi và thêm tính năng. Trên App Store, cập nhật tự động được xử lý cho bạn, nhưng với phân phối trực tiếp, đây cũng là thứ bạn phải tự thiết lập.

Ở phần tiếp theo, chúng ta sẽ tạo khóa ký EdDSA cho Sparkle, framework cập nhật tự động de facto tiêu chuẩn cho các ứng dụng macOS. Đây là cơ chế xác minh dành riêng cho file cập nhật — một lớp riêng biệt, tách biệt với chứng chỉ.