Giao diện

FAQ & Troubleshooting — Apple Auth ​

Các câu hỏi thường gặp và cách xử lý sự cố khi sử dụng plugin Sign in with Apple.

Lỗi "user_cancelled_authorize" ​

Triệu chứng: Apple redirect về Digiforce với error user_cancelled_authorize.

Nguyên nhân: User nhấn "Cancel" hoặc đóng popup Apple khi đang xác nhận đăng nhập.

Giải pháp: Đây là hành vi bình thường — không phải lỗi. Plugin nên hiển thị lại trang đăng nhập để user thử lại.

APP_BASE_URL không khớp với Apple Return URL ​

Triệu chứng: Apple báo lỗi "Invalid redirect_uri" hoặc callback về sai URL.

Nguyên nhân: Biến APP_BASE_URL không khớp với Return URL đã đăng ký trong Apple Developer.

Kiểm tra:

  1. Giá trị APP_BASE_URL trong environment:

    bash
    echo $APP_BASE_URL
# Phải là: https://app.example.com (không có trailing slash)

  2. Return URL trong Apple Developer → Services ID → Sign in with Apple → Configure:

    https://app.example.com/api/apple:redirect

  3. Đảm bảo protocol khớp: https vs http

  4. Đảm bảo domain khớp chính xác (không có www/ khác subdomain)

Giải pháp: Đồng bộ APP_BASE_URL với domain đã đăng ký tại Apple.

Apple chỉ gửi tên user một lần ​

Triệu chứng: User đăng nhập lần đầu bị lỗi, đăng nhập lại thành công nhưng không có tên (nickname).

Nguyên nhân: Apple chỉ gửi thông tin tên (firstName, lastName) trong user JSON ở lần authorize đầu tiên. Nếu lần đầu thất bại, tên sẽ mất.

Giải pháp cho user:

  1. Vào Settings → Apple ID → Sign-In & Security → Sign in with Apple (trên thiết bị Apple)
  2. Tìm ứng dụng Digiforce → Stop Using Apple ID
  3. Đăng nhập lại — Apple sẽ coi như lần đầu và gửi tên

Giải pháp cho admin: User có thể cập nhật tên thủ công trong profile Digiforce sau đó.

Email relay (Hide My Email) ​

Triệu chứng: Email user có dạng xxxx@privaterelay.appleid.com thay vì email thật.

Giải thích: User chọn "Hide My Email" khi authorize. Apple tạo email relay unique cho mỗi ứng dụng. Email gửi đến relay address sẽ được forward đến email thật.

Lưu ý:

  • Email relay vẫn hoạt động bình thường cho liên kết user
  • Nếu cần email thật, không có cách bắt buộc — đây là quyền riêng tư của user
  • Relay email ổn định — cùng user luôn có cùng relay email cho cùng ứng dụng

Client secret hết hạn ​

Triệu chứng: Đăng nhập Apple bắt đầu thất bại sau một thời gian hoạt động tốt.

Nguyên nhân: Apple client secret JWT có thời hạn tối đa 6 tháng.

Giải pháp:

  1. Tạo JWT mới từ private key .p8 (không cần tạo key mới)
  2. Cập nhật clientSecret trong authenticator settings
  3. Đặt lịch nhắc renew trước khi hết hạn

Không thấy nút "Sign in with Apple" trên trang login ​

Kiểm tra:

  1. Authenticator Apple đã được tạo và bật (enabled) chưa?
  2. Plugin @digiforce-nc/plugin-auth-apple đã kích hoạt chưa?
  3. clientId đã điền chưa? (nút chỉ hiển thị khi có cấu hình đầy đủ)

Lỗi form_post trên một số reverse proxy ​

Triệu chứng: Apple callback báo lỗi hoặc mất data.

Nguyên nhân: Một số reverse proxy (nginx, Cloudflare) có giới hạn kích thước POST body hoặc không forward form data đúng cách.

Giải pháp:

  • Nginx: tăng client_max_body_size
  • Đảm bảo proxy forward header Content-Type: application/x-www-form-urlencoded
  • Không strip POST body khi proxy