Đăng nhập bằng Millida trên trang web của bạn

Millida có thể hoạt động như một nhà cung cấp danh tính: khách truy cập nhấp vào “Đăng nhập bằng Millida” trên trang của bạn, xác nhận chuyển dữ liệu và quay lại với trạng thái đã xác thực. Nó hoạt động qua OpenID Connect — giống như đăng nhập bằng Google, Apple hay Discord — nên bất kỳ thư viện OIDC có sẵn nào cũng dùng được.

Chỉ danh tính được chia sẻ: nickname Minecraft, tên, ảnh đại diện và — nếu bạn yêu cầu và người đó đồng ý — email, skin, Discord và Telegram đã liên kết, cùng uy tín trên nền tảng. Số dư, giao dịch và máy chủ không khả dụng cho ứng dụng.

Bạn cần làm gì

1. Tạo ứng dụng

Hồ sơ → API và webhook → tab Đăng nhập bằng Millida → “Tạo ứng dụng”.

Bạn sẽ cần:

• Tên — người dùng sẽ thấy tên này trên màn hình đăng nhập. Từ “Millida” bị cấm trong tên ứng dụng của người khác.
• Redirect URI — nơi trả người dùng về sau khi xác nhận. Chỉ chấp nhận https (khi phát triển, cho phép http://localhost). Địa chỉ được so khớp toàn bộ: thêm một dấu gạch chéo hay một tham số sẽ không còn khớp.
• Liên kết chính sách bảo mật — người dùng sẽ thấy trước khi chuyển dữ liệu cho bạn.

Sau khi tạo, bạn sẽ nhận được client_id và, với ứng dụng máy chủ, một client_secret. Secret chỉ hiển thị một lần — hãy lưu ngay.

Loại ứng dụng: server nếu bạn có backend lưu được secret; public nếu đó là SPA hoặc ứng dụng di động và không có chỗ nào giấu secret.

2. Chỉ định URL nhà cung cấp cho thư viện

https://id.millida.net

Thế là đủ: thư viện sẽ tự đọc https://id.millida.net/.well-known/openid-configuration và tìm các URL còn lại.

3. Đưa người dùng đến trang đăng nhập

https://id.millida.net/oauth/authorize
  ?response_type=code
  &client_id=your_client_id
  &redirect_uri=https://your-site.ru/auth/millida/callback
  &scope=openid profile email
  &state=random_string
  &nonce=random_string
  &code_challenge=base64url(sha256(code_verifier))
  &code_challenge_method=S256

PKCE là bắt buộc với mọi ứng dụng, kể cả ứng dụng máy chủ. Hãy lưu state trong session và xác minh khi quay lại — nếu không, phản hồi của người khác có thể bị chèn vào session của bạn.

4. Đổi code lấy token

POST https://id.millida.net/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=authorization_code&code=…&redirect_uri=…&code_verifier=…

Phản hồi chứa access_token, id_token và, nếu bạn yêu cầu offline_access, cả refresh_token.

5. Xác định ai đã đăng nhập

Phân tích id_token (xác minh chữ ký với JWKS, iss, aud, exp, nonce) hoặc gọi:

GET https://id.millida.net/oauth/userinfo
Authorization: Bearer <access_token>

Bạn có thể yêu cầu những dữ liệu nào

Nickname offline không có UUID — minecraft_uuid sẽ trống, còn minecraft_username được điền từ tài khoản. telegram_id trả về dưới dạng chuỗi: id chat Telegram không vừa với số chính xác trong JSON, và phân tích nó như số sẽ làm hỏng các chữ số cuối.

Chỉ yêu cầu những gì cần thiết để đăng nhập hoạt động: người dùng đọc từng mục thừa trên màn hình đồng ý và có thể đổi ý ngay tại đó.

Về mã định danh người dùng

sub khác nhau với mỗi ứng dụng cho cùng một người. Nó bất biến với trang của bạn, nhưng không khớp với sub ở các trang khác — bạn không thể đối chiếu khán giả giữa các ứng dụng bằng nó.

Hãy lưu sub làm khóa người dùng. Email không phù hợp cho việc này: nó có thể bị thay đổi.

Xác minh ứng dụng

Ứng dụng mới hoạt động ngay, nhưng bị đánh dấu là chưa xác minh trên màn hình đăng nhập. Khi trang đã sẵn sàng, hãy nhấp “Gửi để duyệt” trong bảng điều khiển — chúng tôi sẽ xem xét và gỡ nhãn.

Lỗi thường gặp

“redirect_uri does not match any registered address” — địa chỉ được so khớp như một chuỗi đầy đủ. Kiểm tra dấu gạch chéo cuối, scheme và cổng.

“Only code_challenge_method=S256 is supported” — PKCE là bắt buộc, plain không được chấp nhận.

“The authorization code has already been used” — code chỉ dùng một lần và tồn tại trong một phút. Việc đổi lặp lại bị coi là dấu hiệu rò rỉ và thu hồi toàn bộ quyền truy cập của ứng dụng.

Token ngừng hoạt động sau khi thu hồi — người dùng đã tắt ứng dụng trong cài đặt bảo mật của hồ sơ. Đây là hành vi dự kiến: hãy đưa họ đến trang đăng nhập lại.

Cách người dùng thu hồi quyền truy cập

Hồ sơ → Bảo mật → “Ứng dụng đã kết nối” → “Thu hồi”. Quyền truy cập dừng ngay lập tức, và mọi token đã cấp đều vô hiệu.