Đăng nhập bằng Tino — OAuth 2.0 và OpenID Connect

Ứng dụng của bạn đăng nhập khách bằng tài khoản Tino và gọi API Tino thay khách qua OAuth 2.0 Authorization Code + PKCE (S256), kèm OpenID Connect. Issuer là https://api.tino.vn; trang đăng nhập và đồng ý là https://auth.tino.vn/oauth/consent.

Cập nhật: 2026-10-27. Nguồn sự thật cho endpoint, quyền và claim: tài liệu discovery https://api.tino.vn/.well-known/openid-configuration.

Tổng quan

Mọi endpoint đều có trong tài liệu discovery: đọc https://api.tino.vn/.well-known/openid-configuration (hoặc /.well-known/oauth-authorization-server, cùng nội dung) thay vì ghi cứng địa chỉ.

Không có implicit flow, hybrid flow, client credentials hay password grant.

Luồng đăng nhập

1. Ứng dụng chuyển trình duyệt của khách tới https://auth.tino.vn/oauth/consent kèm client_id, scope, code_challenge.
2. Khách đăng nhập (nếu chưa), chọn tài khoản (nếu trình duyệt có từ hai tài khoản), đồng ý cấp quyền.
3. Tino chuyển trình duyệt về redirect_uri của ứng dụng với ?code=…&state=….
4. Ứng dụng gọi POST https://api.tino.vn/oauth/token với code + code_verifier.
5. Tino trả access_token, id_token (khi có openid), refresh_token (khi có offline_access).
6. Ứng dụng gọi https://api.tino.vn/v1/<route> với Authorization: Bearer <access_token>.

Trình duyệt chỉ mang code về ứng dụng; ứng dụng tự gọi api.tino.vn để đổi code lấy token, kèm code_verifier chứng minh cùng một lượt đăng nhập.

Đăng ký ứng dụng

Tino tạo ứng dụng cho bạn và cấp client_id (cùng client_secret nếu ứng dụng có server). Client công khai (CLI, ứng dụng chạy trên máy khách, MCP client) cũng tự đăng ký được qua POST https://api.tino.vn/oauth/register (RFC 7591), xem Đăng nhập từ CLI.

Khi xin ứng dụng, gửi Tino: tên và logo (https) hiện trên trang đồng ý, danh sách redirect URI, các quyền cần (mục Gọi API của Tino), và ứng dụng có giữ được secret ở server không.

Quy tắc redirect URI:

• So khớp nguyên chuỗi với URI đã đăng ký (kể cả đường dẫn và query); không nhận URI có #fragment.
• Phải là https://. Riêng khi phát triển trên máy: http://localhost hoặc http://127.0.0.1.
• URI loopback đăng ký không kèm cổng khớp với mọi cổng (RFC 8252 mục 7.3), hợp cho ứng dụng CLI nghe cổng ngẫu nhiên.

client_id có thể là URL của một Client ID Metadata Document (discovery báo client_id_metadata_document_supported: true), nhưng chỉ các URL Tino đã đăng ký trước mới được nhận.

Bước 1 — Chuyển khách tới trang đồng ý

Ứng dụng tạo code_verifier, state, nonce ngẫu nhiên cho mỗi lần đăng nhập, giữ chúng (cookie httpOnly hoặc session), rồi chuyển trình duyệt tới https://auth.tino.vn/oauth/consent kèm các tham số trên query.

Ví dụ:

https://auth.tino.vn/oauth/consent?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fapp.example.com%2Fauth%2Fcallback&scope=openid%20profile%20email%20offline_access%20services%3Aread&state=af0ifjsldkj&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM&code_challenge_method=S256&nonce=n-0S6_WzA2Mj

Tạo PKCE (Node.js 18+):

import { createHash, randomBytes } from "node:crypto";

const codeVerifier = randomBytes(32).toString("base64url"); // 43 ký tự
const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");

Trên trang đồng ý, khách chưa đăng nhập thì đăng nhập trước (OTP, passkey, Google, Zalo, GitHub). Trình duyệt có từ hai tài khoản Tino trở lên thì khách chọn tài khoản. Khách đã cấp đủ các quyền này cho ứng dụng thì không phải đồng ý lại; xin thêm quyền thì hỏi lại.

Kết quả, Tino chuyển trình duyệt về redirect_uri:

Trước khi dùng code, so state nhận được với state đã giữ; khác nhau thì bỏ.

Bước 2 — Đổi code lấy token

Đổi code trong 60 giây, mỗi code dùng một lần: POST https://api.tino.vn/oauth/token, body application/x-www-form-urlencoded. Client confidential gọi từ server và gửi client_secret trong body; không dùng header Authorization: Basic.

curl -X POST https://api.tino.vn/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d grant_type=authorization_code \
  -d code=AUTH_CODE \
  -d redirect_uri=https://app.example.com/auth/callback \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d code_verifier=CODE_VERIFIER

Câu trả lời (HTTP 200):

{
  "access_token": "tinoat_…",
  "token_type": "Bearer",
  "expires_in": 86400,
  "scope": "openid profile email offline_access services:read",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6…",
  "refresh_token": "tinort_…"
}

Thời hạn do Tino cấu hình và có thể đổi: đọc expires_in của mỗi câu trả lời thay vì ghi cứng. Giữ token ở server (hoặc kho bảo mật của thiết bị), không đưa vào URL hay localStorage.

Làm mới và thu hồi token

Mỗi lần làm mới trả một refresh token mới và vô hiệu hoá cái cũ (xoay vòng). Dùng lại một refresh token đã xoay thì Tino thu hồi toàn bộ quyền của ứng dụng trên tài khoản đó; khách phải đăng nhập và đồng ý lại.

curl -X POST https://api.tino.vn/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=tinort_… \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET

• scope (không bắt buộc): thu hẹp quyền của token mới; vượt quyền đã cấp thì invalid_scope và refresh token cũ vẫn dùng được.
• Câu trả lời cùng dạng bước 2. Lưu ngay refresh_token mới trước khi dùng access_token.
• Nhiều tiến trình cùng làm mới một refresh token: chỉ một lần thắng, lần kia bị coi là dùng lại. Gom việc làm mới về một chỗ (khoá theo tài khoản).
• invalid_grant khi làm mới: token hết hạn, đã thu hồi hoặc khách đã thu hồi quyền ứng dụng. Đưa khách đăng nhập lại từ bước 1.

Thu hồi khi khách đăng xuất khỏi ứng dụng (RFC 7009): POST https://api.tino.vn/oauth/revoke với token=<refresh_token>, client_id, client_secret (client confidential). Refresh token và access token đi kèm cùng hết hiệu lực; endpoint luôn trả HTTP 200.

Khách cũng tự thu hồi được ở trang Ứng dụng được cấp quyền (https://auth.tino.vn/me/apps); token của ứng dụng hết hiệu lực ngay, lần gọi sau nhận 401 invalid_token.

ID token và UserInfo

ID token là JWT ký RS256; kiểm chữ ký bằng khoá có kid trùng header, lấy từ https://api.tino.vn/oauth/jwks (lưu cache, tải lại khi gặp kid lạ). Dùng thư viện OpenID Connect có sẵn (openid-client, jose, Authlib…) thay vì tự viết.

Ghép tài khoản theo sub, không theo email: khách đổi được email.

UserInfo trả cùng các claim (sub và các claim theo scope), cần access token có openid:

curl https://api.tino.vn/oauth/userinfo -H "Authorization: Bearer tinoat_…"

{ "sub": "26", "email": "binh@example.com", "given_name": "Bình", "family_name": "Trần", "name": "Bình Trần" }

Access token thiếu openid thì nhận 403 insufficient_scope.

Gọi API của Tino

Ứng dụng gọi API Tino thay khách qua gateway https://api.tino.vn/v1/<route> với Authorization: Bearer <access_token>. Mỗi route thuộc một quyền; route ngoài quyền của token trả 403 insufficient_scope.

curl https://api.tino.vn/v1/details -H "Authorization: Bearer tinoat_…"

GET /v1/details chạy route GET /details của UserAPI bằng tài khoản của khách; body và câu trả lời giữ nguyên dạng của UserAPI.

Quyền của dịch vụ (gateway /v1 mở từ 27/10/2026): gọi https://api.tino.vn/v1/service/<id dịch vụ>/<dịch vụ>/… cho dịch vụ của chính khách.

tinopay:owner (tạo API token TinoPay, liên kết tài khoản ngân hàng nhận tiền) như domains:owner: chỉ token API cá nhân có giới hạn IP.

Xin ít quyền nhất đủ dùng: khách thấy từng dòng trên trang đồng ý. domains:owner (lấy mã EPP, đổi chủ thể tên miền) và domains:registrant (hồ sơ chủ thể tên miền đang chờ) chỉ dành cho token API cá nhân; ứng dụng không bao giờ được cấp. Ba lệnh đặt đơn có thể trừ số dư (POST /v1/carts/{uuid}/confirm, POST /v1/order, POST /v1/order/{product_id}) cần cả orders:write và billing:write.

Từng route, tham số, ví dụ request và response: Gọi API Tino.

Lỗi thường gặp

/oauth/token và /oauth/revoke trả lỗi dạng {"error": "<mã>", "error_description": "<câu tiếng Anh>"}. /oauth/userinfo và gateway /v1 kèm header WWW-Authenticate: Bearer error="<mã>".

Lỗi nghiệp vụ của từng route /v1/* (ví dụ dịch vụ không tồn tại) giữ nguyên câu trả lời của UserAPI, thường là HTTP 200 kèm {"error": ["<mã>"]}.

Tham khảo

• OpenID discovery của Tino: endpoint, quyền, claim đang chạy trên production
• Protected resource metadata (RFC 9728): cho client MCP; xem Kết nối Claude, ChatGPT với Tino (MCP)
• JWKS: khoá công khai kiểm ID token
• RFC 6749 OAuth 2.0
• RFC 7636 PKCE
• RFC 7009 thu hồi token
• RFC 8252 ứng dụng native
• OpenID Connect Core 1.0