Giao diện

Hướng dẫn cài đặt Apple Auth ​

Hướng dẫn thiết lập xác thực Sign in with Apple trong Digiforce, bao gồm cấu hình Apple Developer và biến môi trường.

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

  • Digiforce đã cài đặt và chạy ổn định
  • Plugin @digiforce-nc/plugin-auth-apple đã được kích hoạt
  • Tài khoản Apple Developer Program (99 USD/năm)
  • Biến môi trường APP_BASE_URL đã được cấu hình

Bước 1: Cấu hình trên Apple Developer ​

Tạo App ID ​

  1. Truy cập Apple Developer → Certificates, Identifiers & Profiles
  2. Vào Identifiers → App IDs → Register
  3. Bật capability Sign in with Apple

Tạo Services ID ​

  1. Vào Identifiers → Services IDs → Register
  2. Đặt Identifier (ví dụ: com.example.digiforce.auth) — đây sẽ là clientId
  3. Bật Sign in with Apple → Configure:
    • Domains: app.example.com (domain Digiforce)
    • Return URLs: https://app.example.com/api/apple:redirect
  4. Save

Tạo Private Key ​

  1. Vào Keys → Register a New Key
  2. Bật Sign in with Apple → Associate với App ID
  3. Download file .p8 (chỉ tải được một lần!)
  4. Ghi nhớ Key ID

Tạo Client Secret (JWT) ​

Apple client secret là JWT ký bằng private key .p8:

bash
# Thông tin cần thiết:
# - Team ID: từ Apple Developer account
# - Key ID: từ key vừa tạo
# - Services ID: clientId
# - Private key: file .p8

Client secret JWT có thời hạn tối đa 6 tháng — cần renew định kỳ.

Bước 2: Cấu hình biến môi trường ​

Plugin Apple Auth yêu cầu biến APP_BASE_URL:

bash
APP_BASE_URL=https://app.example.com

Biến này dùng để xây dựng redirect URL. Nếu thiếu, plugin không thể tạo callback URL đúng.

Bước 3: Tạo authenticator trong Digiforce ​

  1. Vào Settings → Authentication → Add new
  2. Chọn loại Apple
  3. Đặt tên authenticator (ví dụ: apple-login)
  4. Điền thông số:
TrườngGiá trị
Client IDServices ID từ Apple (ví dụ: com.example.digiforce.auth)
Client SecretJWT secret tạo từ private key
Redirect URL(tùy chọn) URL redirect tùy chỉnh sau đăng nhập

Bước 4: Kiểm tra đăng nhập ​

  1. Mở cửa sổ ẩn danh
  2. Tại trang đăng nhập, nhấn Sign in with Apple
  3. Apple hiển thị popup xác nhận → chọn chia sẻ email (real hoặc relay)
  4. Sau khi xác nhận, quay về Digiforce với session

Lưu ý quan trọng ​

Apple chỉ gửi tên user lần đầu tiên ​

Apple chỉ gửi thông tin tên (firstName, lastName) trong user JSON khi user authorize lần đầu tiên. Các lần đăng nhập sau, Apple chỉ gửi code — không gửi tên.

Nếu lần đầu bị lỗi và không lưu được tên, user phải:

  1. Vào Apple ID Settings → Security → Apps Using Apple ID
  2. Xóa ứng dụng Digiforce
  3. Đăng nhập lại (Apple sẽ gửi tên)

Email relay ​

User có thể chọn "Hide My Email" — Apple tạo email relay dạng xxx@privaterelay.appleid.com. Email này vẫn forward về email thật của user.

userBindField chỉ hỗ trợ email ​

Plugin Apple Auth chỉ hỗ trợ userBindField: email. Binding theo username chưa được implement.