@digiforce-nc/plugin-auth-apple

Plugin xác thực qua Sign in with Apple — cho phép user đăng nhập bằng Apple ID. Sử dụng openid-client và jsonwebtoken để xử lý luồng OAuth 2.0 với đặc thù form_post response mode của Apple.

Plugin này làm gì?

AppleAuth kế thừa BaseAuth, triển khai luồng Authorization Code của Apple với response_mode: form_post. Apple gửi authorization code và thông tin user (nếu lần đầu) qua HTTP POST thay vì query string — đây là đặc thù riêng của Apple so với OIDC thông thường.

#	Đặc thù	Chi tiết
1	form_post response	Apple POST form data (không redirect query) — cần gateway middleware
2	User info chỉ lần đầu	Apple gửi tên user trong `user` JSON chỉ khi authorize lần đầu
3	State trong cookie	State (CSRF) lưu trong cookie `digiforce_apple`
4	id_token decode	Claims lấy từ decode JWT id_token, không qua userinfo endpoint
5	External redirect	Hỗ trợ `redirectUrl` tùy chỉnh sau đăng nhập thành công

Luồng xác thực

Cấu hình

Tham số	Kiểu	Mô tả
`clientId`	`string`	Apple Services ID (ví dụ: `com.example.app.auth`)
`clientSecret`	`string`	JWT secret tạo từ Apple private key
`redirectUrl`	`string`	URL redirect tùy chỉnh sau đăng nhập (optional)
`scope`	`string`	Scope yêu cầu (mặc định: `email name`)
`idTokenSignedResponseAlg`	`string`	Thuật toán ký id_token (mặc định: `RS256`)
`fieldMap`	`object`	Mapping từ Apple claims sang local user fields
`userBindField`	`string`	Field dùng để liên kết user (ví dụ: `email`)
`public.autoSignup`	`boolean`	Tự tạo tài khoản nếu user chưa tồn tại

Lưu ý về Apple client secret

Apple client secret là JWT ngắn hạn (tối đa 6 tháng), tạo từ:

Key ID — từ Apple Developer Console
Team ID — Apple Developer Team
Private Key — file .p8 tải từ Apple

API endpoints

Endpoint	Quyền	Mô tả
`apple:getAuthUrl`	Public	Trả về Apple authorize URL (response_mode: form_post)
`apple:redirect`	Public	Callback nhận POST form từ Apple (code + user)

Thành phần client

Thành phần	Mô tả
`AppleButton`	Nút "Sign in with Apple" theo Apple design guidelines
`Options`	Form cấu hình Apple auth trong Settings → Authentication

Dependencies

Package	Vai trò
`openid-client`	OIDC client, xử lý discovery và token exchange
`jsonwebtoken`	Decode và verify JWT id_token
`@digiforce-nc/auth`	Base auth framework (peer)
`@digiforce-nc/server`	Server framework (peer)
`@digiforce-nc/client`	Client framework (peer)