Chọn luồng
| Luồng | Dùng khi | Access token | Refresh token |
|---|---|---|---|
client_credentials | Máy chủ của bạn tự hành động, cho một tenant: đồng bộ, tác vụ nền, webhook. | 30 phút (1800 giây) | Không có. Xin token mới. |
authorization_code + PKCE | Ứng dụng của bạn hành động thay một người dùng đã đăng nhập và đồng ý: cổng đối tác, ứng dụng di động. | 10 phút (600 giây) | Với offline_access: 30 ngày nếu không dùng, tối đa 365 ngày, đổi mới mỗi lần dùng. |
Thời hạn trên là mặc định của dịch vụ; hãy đọc expires_in trong mỗi phản hồi thay vì ghi cứng. Hãy coi access token là chuỗi mờ.
Ứng dụng chứng minh mình là ai
| Phương thức | Cách làm | Dành cho |
|---|---|---|
client_secret_basic | Authorization: Basic base64(client_id:client_secret) | Ứng dụng bảo mật có khóa bí mật. |
private_key_jwt | client_assertion_type và client_assertion: một JWT ngắn hạn bạn ký bằng khóa riêng. Chi tiết bên dưới. | Ứng dụng bảo mật muốn dùng cặp khóa thay vì khóa bí mật dùng chung. |
none | Chỉ gửi client_id; PKCE bảo vệ bước đổi code. | Ứng dụng công khai (ví dụ ứng dụng di động). |
Mỗi yêu cầu dùng một phương thức. Một ứng dụng chỉ có một phương thức tại một thời điểm; gửi cả Basic lẫn assertion là invalid_request.
client_credentials
Scope là tùy chọn và phải nằm trong tập ứng dụng của bạn đã được duyệt. Chỉ xin những gì cần.
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials \
-d scope="trips:read routes:read"{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9...",
"token_type": "Bearer",
"expires_in": 1800,
"scope": "trips:read routes:read"
}Ứng dụng đối tác: chỉ rõ tenant
Ứng dụng đối tác phục vụ nhiều tenant nên yêu cầu client_credentials chỉ rõ tenant bằng tenant=<install_id> (giá trị sti_... từ bước cài đặt). Chỉ hoạt động với một lượt cài đặt còn hiệu lực của chính ứng dụng của bạn và có scope tenant:connect.
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=client_credentials \
-d tenant="$INSTALL_ID" \
-d scope="trips:read"authorization_code với PKCE
Người dùng duyệt ứng dụng của bạn trên một trang của Stracker, bạn nhận một code dùng một lần ở địa chỉ chuyển hướng và đổi nó lấy token. PKCE S256 là bắt buộc với mọi ứng dụng, bảo mật hay công khai; plain bị từ chối.
- Tạo verifier và challenge. Verifier là chuỗi ngẫu nhiên 43 đến 128 ký tự an toàn cho URL; challenge là base64url của SHA-256 của nó.
- Đưa người dùng tới trang authorize với các tham số bên dưới.
- Người dùng đăng nhập và đồng ý. Stracker chuyển hướng tới
redirect_uricủa bạn kèmcode,statevàiss. Kiểm trastateđúng là giá trị bạn đã gửi vàisslàhttps://api.stracker.vn. - Đổi code trong 60 giây. Code chỉ dùng được một lần; dùng lại sẽ thu hồi quyền đã cấp từ code đó.
- Gọi API bằng access token.
# 1. A random code_verifier (43-128 characters of A-Z a-z 0-9 - . _ ~)
CODE_VERIFIER=$(openssl rand -base64 48 | tr '+/' '-_' | tr -d '=\n')
# 2. Its S256 challenge: BASE64URL(SHA256(code_verifier))
CODE_CHALLENGE=$(printf %s "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')https://app.stracker.vn/oauth/authorize
?response_type=code
&client_id=YOUR_CLIENT_ID
&redirect_uri=https%3A%2F%2Fexample.com%2Fstracker%2Fcallback
&scope=trips%3Aread%20offline_access
&state=RANDOM_VALUE_YOU_CHECK_ON_RETURN
&code_challenge=CODE_CHALLENGE
&code_challenge_method=S256| Tham số | Giá trị |
|---|---|
response_type | code |
client_id | Client ID của bạn. |
redirect_uri | Đúng một trong các địa chỉ bạn đã đăng ký (so khớp chuỗi chính xác). Chỉ https; ứng dụng công khai trên thiết bị có thể dùng http://127.0.0.1:<cổng> hoặc một scheme riêng. |
scope | Các scope cách nhau bằng dấu cách. Thêm offline_access để nhận refresh token. |
state | Một giá trị ngẫu nhiên bạn kiểm tra khi quay lại. |
code_challenge, code_challenge_method | Challenge S256 và đúng chữ S256. |
https://example.com/stracker/callback?code=stco_...&state=RANDOM_VALUE_YOU_CHECK_ON_RETURN&iss=https%3A%2F%2Fapi.stracker.vn# Confidential client (has a secret): authenticate with Basic
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=authorization_code \
-d code="$CODE" \
-d redirect_uri="https://example.com/stracker/callback" \
-d code_verifier="$CODE_VERIFIER"
# Public client (no secret, for example a native app): send client_id instead
curl -sS https://api.stracker.vn/v1/oauth/token \
-d grant_type=authorization_code \
-d client_id="$CLIENT_ID" \
-d code="$CODE" \
-d redirect_uri="myapp://stracker/callback" \
-d code_verifier="$CODE_VERIFIER"{
"access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImF0K2p3dCIsImtpZCI6Ii4uLiJ9...",
"token_type": "Bearer",
"expires_in": 600,
"scope": "trips:read offline_access",
"refresh_token": "stcr_..."
}Refresh token
Xin offline_access để nhận refresh token (stcr_...). Mỗi lần dùng, nó được đổi mới: phản hồi mang refresh token mới và token cũ coi như đã dùng. Khi làm mới có thể thu hẹp scope, không bao giờ mở rộng.
curl -sS https://api.stracker.vn/v1/oauth/token \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d grant_type=refresh_token \
-d refresh_token="$REFRESH_TOKEN"private_key_jwt: ký thay vì chia sẻ khóa bí mật
Thay vì khóa bí mật, ứng dụng của bạn đăng ký một khóa công khai và tự chứng minh bằng một JWT ngắn hạn được ký bằng khóa riêng (RFC 7523, OpenID Connect private_key_jwt). Không có bí mật nào đi qua mạng, và bạn đổi khóa mà không phải phối hợp một giá trị dùng chung. Dùng được cho client_credentials, authorization_code, refresh_token, revoke và introspect.
1. Tạo cặp khóa
Nên dùng ES256 (khóa EC trên đường cong P-256). RS256 cần khóa RSA từ 2048 đến 8192 bit với số mũ công khai 65537. Khóa riêng ở lại phía bạn và không bao giờ rời khỏi đó.
# ES256: an EC key on the P-256 curve, private key in PKCS#8
openssl ecparam -name prime256v1 -genkey -noout | openssl pkcs8 -topk8 -nocrypt -out private.pem
openssl pkey -in private.pem -pubout -out public.pem# RS256: RSA 2048 to 8192 bits (public exponent 65537)
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out private.pem
openssl pkey -in private.pem -pubout -out public.pemconst { generateKeyPairSync } = require('node:crypto');
const fs = require('node:fs');
const kid = process.argv[2] ?? 'my-key-1'; // 1-64 characters of A-Z a-z 0-9 . _ -
const { privateKey, publicKey } = generateKeyPairSync('ec', { namedCurve: 'P-256' });
// The private key never leaves your machine; keep it out of version control.
fs.writeFileSync('private.pem', privateKey.export({ type: 'pkcs8', format: 'pem' }), { mode: 0o600 });
// Paste this public JWK into Stracker (API keys > OAuth apps > Keys).
const jwk = { ...publicKey.export({ format: 'jwk' }), kid, alg: 'ES256', use: 'sig' };
console.log(JSON.stringify(jwk, null, 2));2. Đăng ký khóa công khai
Bạn đăng ký khóa công khai dưới dạng JWK (RFC 7517). Đoạn Node.js ở trên in ra một JWK; để đổi public.pem sang JWK, dùng:
// Turn public.pem into the public JWK Stracker asks for
const { createPublicKey } = require('node:crypto');
const fs = require('node:fs');
const jwk = createPublicKey(fs.readFileSync('public.pem')).export({ format: 'jwk' });
console.log(JSON.stringify({ ...jwk, kid: 'my-key-1', use: 'sig' }, null, 2));{
"kty": "EC",
"crv": "P-256",
"x": "...base64url...",
"y": "...base64url...",
"kid": "my-key-1",
"alg": "ES256",
"use": "sig"
}- Chấp nhận:
ECvới đường congP-256, hoặcRSAtừ 2048 đến 8192 bit với số mũ 65537. kidlà bắt buộc: 1 đến 64 ký tự trongA-Z a-z 0-9 . _ -, không trùng với khóa còn hiệu lực khác của ứng dụng.- Bị từ chối: mọi thành phần riêng (
d,p,q,dp,dq,qi,oth,k),usekhácsig,algkhông khớp loại khóa, điểm không nằm trên đường cong. Các thành phần khác bị bỏ. - Một ứng dụng giữ tối đa 5 khóa còn hiệu lực. Thêm khóa mới trước khi thu hồi khóa cũ; khóa còn hiệu lực cuối cùng của ứng dụng đang dùng khóa không thể thu hồi.
- Ứng dụng của đơn vị: quản trị viên đăng ký khóa trên ứng dụng trong Stracker, mục API keys. Ứng dụng đối tác: đường dẫn bàn giao thông tin đăng nhập chúng tôi gửi (đường dẫn dùng để lộ khóa bí mật) cho phép bạn đăng ký khóa của mình thay vào đó.
3. Dựng và ký assertion
// Header
{ "alg": "ES256", "typ": "JWT", "kid": "my-key-1" }
// Claims
{
"iss": "YOUR_CLIENT_ID",
"sub": "YOUR_CLIENT_ID",
"aud": "https://api.stracker.vn/v1/oauth/token",
"iat": 1763104324,
"exp": 1763104384,
"jti": "f3c1b7a2-3d52-4b5a-9d6c-0f6a53b0a111"
}| Phần | Quy tắc |
|---|---|
alg | Chỉ ES256 hoặc RS256. none, HS* và các header như jku, x5u, jwk, x5c, crit bị từ chối: khóa chỉ lấy từ tập bạn đã đăng ký. |
kid | kid của khóa bạn ký. Nên có; giúp máy chủ khỏi phải thử từng khóa. |
iss và sub | Cả hai đều bằng client ID của bạn. |
aud | Đúng một giá trị: URL endpoint token https://api.stracker.vn/v1/oauth/token (cũng chấp nhận issuer https://api.stracker.vn). Danh sách nhiều audience bị từ chối. |
exp | Bắt buộc, tối đa 5 phút tính từ bây giờ. iat và nbf là tùy chọn và được kiểm tra khi có; exp - iat tối đa 5 phút. Cho phép lệch đồng hồ 30 giây. |
jti | Bắt buộc, duy nhất. Một assertion chỉ dùng được một lần: jti được ghi nhớ đến exp và dùng lại sẽ bị từ chối. Tạo mới cho mỗi yêu cầu. |
| Kích thước | Tối đa 8192 ký tự. Nếu bạn gửi client_id, nó phải bằng iss. |
Chữ ký ES256 là dạng thô 64 byte r || s mà JWS dùng, không phải dạng DER mà một số thư viện sinh mặc định. Các ví dụ cho thấy cách làm đúng.
const crypto = require('node:crypto');
const fs = require('node:fs');
const CLIENT_ID = process.env.STRACKER_CLIENT_ID;
const KID = 'my-key-1'; // the kid you registered with the public key
const TOKEN_URL = 'https://api.stracker.vn/v1/oauth/token';
const b64u = (value) => Buffer.from(value).toString('base64url');
function clientAssertion(privateKeyPem) {
const now = Math.floor(Date.now() / 1000);
const header = { alg: 'ES256', typ: 'JWT', kid: KID };
const claims = {
iss: CLIENT_ID,
sub: CLIENT_ID,
aud: TOKEN_URL, // exactly one audience
iat: now,
exp: now + 60, // at most 5 minutes ahead
jti: crypto.randomUUID(), // single use: a new one for every request
};
const input = `${b64u(JSON.stringify(header))}.${b64u(JSON.stringify(claims))}`;
// JWS wants r||s (IEEE P1363), not the DER form Node signs with by default.
const signature = crypto.sign('sha256', Buffer.from(input), { key: privateKeyPem, dsaEncoding: 'ieee-p1363' });
return `${input}.${signature.toString('base64url')}`;
}
async function getToken() {
const body = new URLSearchParams({
grant_type: 'client_credentials',
scope: 'trips:read',
client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
client_assertion: clientAssertion(fs.readFileSync('private.pem', 'utf8')),
});
const response = await fetch(TOKEN_URL, { method: 'POST', body });
return response.json(); // { access_token, token_type: 'Bearer', expires_in, scope }
}import os
import time
import uuid
import jwt # PyJWT, with the "cryptography" extra: pip install "pyjwt[crypto]" requests
import requests
CLIENT_ID = os.environ["STRACKER_CLIENT_ID"]
KID = "my-key-1" # the kid you registered with the public key
TOKEN_URL = "https://api.stracker.vn/v1/oauth/token"
def client_assertion(private_key_pem: str) -> str:
now = int(time.time())
claims = {
"iss": CLIENT_ID,
"sub": CLIENT_ID,
"aud": TOKEN_URL, # exactly one audience
"iat": now,
"exp": now + 60, # at most 5 minutes ahead
"jti": str(uuid.uuid4()), # single use: a new one for every request
}
return jwt.encode(claims, private_key_pem, algorithm="ES256", headers={"kid": KID})
def get_token() -> dict:
with open("private.pem") as handle:
assertion = client_assertion(handle.read())
response = requests.post(
TOKEN_URL,
data={
"grant_type": "client_credentials",
"scope": "trips:read",
"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
"client_assertion": assertion,
},
timeout=10,
)
return response.json() # {"access_token": ..., "token_type": "Bearer", "expires_in": ..., "scope": ...}4. Xin token
curl -sS https://api.stracker.vn/v1/oauth/token \
-d grant_type=client_credentials \
-d scope="trips:read" \
-d client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer \
-d client_assertion="$CLIENT_ASSERTION"- Mọi lỗi của assertion (chữ ký sai,
audsai, hết hạn, dùng lại, khóa không có hoặc hết hạn) đều là cùng một401 invalid_client, nên người dò không biết thêm gì. Khi lỗi, hãy kiểm tra đồng hồ,aud,kidvà khóa đã được đăng ký, còn hiệu lực chưa. - Gửi cả Basic lẫn assertion,
client_assertion_typesai, tham số lặp, hoặcclient_idkhácisslà400 invalid_request. - Khi chuyển ứng dụng từ khóa bí mật sang khóa: các khóa bí mật hiện có vẫn dùng được trong 24 giờ rồi ngừng. Ứng dụng không còn khóa bí mật hết hạn thì từ chối Basic.
Revoke và introspect
Revoke (RFC 7009) trả 200 {} khi ứng dụng của bạn đã xác thực, dù token còn sống hay không. Thu hồi refresh token kết thúc toàn bộ quyền đã cấp; thu hồi access token chỉ kết thúc token đó. Introspect (RFC 7662) dành cho ứng dụng bảo mật và trả { "active": false } cho mọi token không còn hiệu lực với bạn.
# Revoke an access token or a refresh token (a refresh token ends the whole grant). Always answers 200 {}.
curl -sS https://api.stracker.vn/v1/oauth/revoke \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d token="$TOKEN"
# Ask whether a token is live (confidential clients only)
curl -sS https://api.stracker.vn/v1/oauth/introspect \
-u "$CLIENT_ID:$CLIENT_SECRET" \
-d token="$TOKEN"Discovery
| Gì | URL |
|---|---|
| Metadata máy chủ ủy quyền (RFC 8414) | https://api.stracker.vn/.well-known/oauth-authorization-server |
| Khóa ký (JWKS) | https://api.stracker.vn/.well-known/jwks.json |
| Trang authorize | https://app.stracker.vn/oauth/authorize |
| Token, revoke, introspect | https://api.stracker.vn/v1/oauth/token, /v1/oauth/revoke, /v1/oauth/introspect |
curl -sS https://api.stracker.vn/.well-known/oauth-authorization-server
curl -sS https://api.stracker.vn/.well-known/jwks.jsonGọi API
- Gửi
Authorization: Bearer <access_token>. Token không bao giờ nằm trong URL. - Một đường dẫn đóng với token OAuth trừ khi có trong tham chiếu API:
403 OAUTH_ROUTE_NOT_EXPOSED. - Mỗi yêu cầu được kiểm tra lại: ứng dụng bị tắt, quyền bị thu hồi, tenant bị đình chỉ hoặc gỡ tiện ích
apisẽ chặn token trong khoảng 30 giây. Xem lỗi để biết các mã. - Token thiếu scope trả
403 OAUTH_INSUFFICIENT_SCOPEkèmWWW-Authenticate: Bearer error="insufficient_scope"và scope cần có.