Tham số cấu hình Apple Auth

Tài liệu chi tiết tất cả tham số cấu hình của plugin @digiforce-nc/plugin-auth-apple.

Tham số bắt buộc

Tham số	Kiểu	Mặc định	Mô tả
clientId	string	—	Apple Services ID. Ví dụ: com.example.digiforce.auth. Tạo trong Apple Developer → Identifiers → Services IDs
clientSecret	string	—	JWT secret ký bằng Apple private key (.p8). Thời hạn tối đa 6 tháng, cần renew định kỳ

Tham số redirect

Tham số	Kiểu	Mặc định	Mô tả
redirectUrl	string	—	URL redirect tùy chỉnh sau đăng nhập thành công. Nếu không đặt, redirect về URL mặc định của ứng dụng

Yêu cầu APP_BASE_URL

Plugin bắt buộc biến môi trường APP_BASE_URL để xây dựng callback URL. Nếu thiếu, redirect URL sẽ sai và Apple trả lỗi.

APP_BASE_URL=https://app.example.com

Tham số scope và token

Tham số	Kiểu	Mặc định	Mô tả
scope	string	email name	Scope yêu cầu. Apple hỗ trợ: email, name. Cách nhau bằng dấu cách
idTokenSignedResponseAlg	string	RS256	Thuật toán ký id_token. Apple luôn dùng RS256

Tham số user binding

Tham số	Kiểu	Mặc định	Mô tả
fieldMap	array	[]	Mapping từ Apple claims sang local user fields
userBindField	string	email	Field dùng để liên kết user. Chỉ hỗ trợ email — binding theo username chưa được implement
public.autoSignup	boolean	true	Tự động tạo tài khoản nếu user chưa tồn tại

userBindField = email only

Khác với OIDC plugin hỗ trợ cả email và username, Apple plugin chỉ hỗ trợ email cho userBindField. Đặt giá trị username sẽ không hoạt động.

Apple claims có sẵn

Claims từ id_token của Apple:

Claim	Mô tả
sub	Apple user ID (duy nhất, không đổi)
email	Email user (real hoặc relay)
email_verified	Email đã verified hay chưa
is_private_email	User dùng "Hide My Email" hay không

Claims từ user JSON (chỉ có lần đầu authorize):

Field	Mô tả
name.firstName	Tên
name.lastName	Họ
email	Email (trùng với id_token)

Ví dụ fieldMap

[
  { "source": "email", "target": "email" },
  { "source": "sub", "target": "appleId" },
  { "source": "name", "target": "nickname" }
]

TIP

Trường name chỉ có giá trị ở lần authorize đầu tiên. Các lần sau, name sẽ là null.

Ví dụ cấu hình đầy đủ

{
  "clientId": "com.example.digiforce.auth",
  "clientSecret": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "scope": "email name",
  "idTokenSignedResponseAlg": "RS256",
  "userBindField": "email",
  "fieldMap": [
    { "source": "email", "target": "email" },
    { "source": "sub", "target": "appleId" }
  ],
  "public": {
    "autoSignup": true
  }
}

Callback URL

Callback URL được xây dựng từ APP_BASE_URL:

{APP_BASE_URL}/api/apple:redirect

URL này phải đăng ký trong Apple Developer → Services ID → Return URLs.

Renew Client Secret

Client secret JWT có thời hạn tối đa 6 tháng. Khi hết hạn:

1. Tạo JWT mới bằng private key .p8
2. Cập nhật clientSecret trong authenticator settings
3. Không cần tạo key mới — cùng .p8 key có thể ký nhiều JWT