Tích hợp trong 5 phút

Tám bước từ lúc đăng ký dịch vụ đến lần đăng nhập thành công đầu tiên. Nếu mới bắt đầu, hãy đọc từ đây.

Đây là toàn bộ quy trình thêm đăng nhập Tài khoản 놀아 vào dịch vụ của bạn. Hãy làm lần lượt từ trên xuống dưới. Nếu bị vướng ở đâu, hãy xem Từ điển mã lỗi trước.

Cần biết trước — PKCE là bắt buộc, không phải tùy chọn. Tài khoản 놀아 từ chối mọi yêu cầu ủy quyền (authorization request) không có code_challenge (pkce_required). Chỉ chấp nhận phương thức S256. Bước 5 bên dưới là phần chuẩn bị cho việc này.

BƯỚC 1

Đăng ký dịch vụ

Vào Tài khoản của tôi ▸ Đăng ký dịch vụ, rồi nhập tên dịch vụ và URL dịch vụ. URL dịch vụ phải là tên miền đang thực sự vận hành.

BƯỚC 2

Xác minh quyền sở hữu tên miền

Chọn một trong hai cách.

Cách	Việc cần làm
Tệp HTML	Tải tệp xác minh về từ Tài khoản của tôi rồi tải lên nguyên vẹn tại `https://ten-mien-cua-ban.com/nolaa-member-verification.html`.
DNS TXT	Đăng ký giá trị token được cấp thành bản ghi TXT (TXT record) tại `_nolaa-member-verification.ten-mien-cua-ban.com`.

Cách DNS cần thời gian để lan truyền. Nếu chưa được ngay, vài phút sau hãy bấm «Xác minh» lại.

BƯỚC 3

Đăng ký callback URL

Đây là địa chỉ người dùng được đưa về sau khi đăng nhập xong. Ví dụ: https://ten-mien-cua-ban.com/oauth/callback

Callback URL phải cùng host với URL dịch vụ và phải là đường dẫn con của URL dịch vụ. Ngoài ra, redirect_uri trong yêu cầu ủy quyền phải khớp chính xác từng ký tự với giá trị đã đăng ký ở đây. Chỉ lệch một dấu gạch chéo ở cuối cũng sẽ bị từ chối với invalid_redirect_uri.

BƯỚC 4

Lấy client_id và client_secret

Sau khi xác minh tên miền và đăng ký callback URL xong, hai giá trị này sẽ hiện trên thẻ dịch vụ trong Tài khoản của tôi.

Chỉ dùng client_secret ở phía máy chủ. Nếu đặt vào mã chạy trên trình duyệt (JS giao diện, gói ứng dụng di động), bất kỳ ai cũng có thể lấy ra xem. Việc đổi token phải luôn thực hiện trên máy chủ.

Khi cấp lại, secret cũ mất hiệu lực ngay lập tức. Khi bạn bấm «Cấp lại» trong Tài khoản của tôi, secret mới chỉ hiển thị trên màn hình đúng một lần, và từ lúc đó yêu cầu token dùng secret cũ sẽ bị từ chối với invalid_client. Nếu dịch vụ đang chạy thật, hãy chuẩn bị sẵn để đổi cấu hình máy chủ sang giá trị mới trước khi cấp lại.

BƯỚC 5

Tạo giá trị PKCE

Trước khi chuyển người dùng đi, hãy tạo code_verifier trên máy chủ và lưu vào phiên (session). code_challenge là giá trị băm (hash) SHA-256 của nó, được mã hóa bằng base64url.

// PHP
$verifier  = rtrim(strtr(base64_encode(random_bytes(32)), '+/', '-_'), '=');
$challenge = rtrim(strtr(base64_encode(hash('sha256', $verifier, true)), '+/', '-_'), '=');
$state     = bin2hex(random_bytes(16));
$_SESSION['nolaa_verifier'] = $verifier;
$_SESSION['nolaa_state']    = $state;

BƯỚC 6

Gắn nút đăng nhập

Bạn có thể sao chép mã nút và biểu tượng tại Tạo nút đăng nhập. Địa chỉ liên kết của nút có dạng như sau.

https://account.nola.kr/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=profile.basic%20profile.avatar
  &state=RANDOM_STATE
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256

state cũng là bắt buộc. Nếu thiếu, yêu cầu sẽ bị từ chối với invalid_request.

BƯỚC 7

Đổi code lấy token tại callback

Khi người dùng đồng ý, họ được đưa về callback URL kèm code và state. Hãy kiểm tra state có giống giá trị đã lưu hay không trước, rồi mới đổi token.

curl -X POST https://account.nola.kr/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=RECEIVED_CODE" \
  -d "redirect_uri=YOUR_REDIRECT_URI" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code_verifier=SAVED_VERIFIER"

authorization code có hiệu lực 10 phút và chỉ dùng được một lần.

BƯỚC 8

Lấy thông tin người dùng

curl https://account.nola.kr/oauth/userinfo \
  -H "Authorization: Bearer ACCESS_TOKEN"

Các giá trị trả về và những gì mỗi scope cung cấp được tổng hợp tại Tra cứu scope.

sub là giá trị khác nhau theo từng dịch vụ (định danh riêng theo dịch vụ, pairwise). Cùng một người dùng nhưng ở dịch vụ khác sẽ nhận sub khác. Hãy dùng sub làm khóa nhận diện người dùng, nhưng đừng nhầm nó là giá trị có thể đối chiếu với dịch vụ khác.

Hướng dẫn tích hợp OAuth 2.0 — toàn bộ luồng xử lý và làm mới token
Danh mục kiểm tra bảo mật — kiểm tra trước khi phát hành
Từ điển mã lỗi — khi bị vướng