Xác thực các dịch vụ phía sau của bạn với Zonos bằng cách sử dụng mã hóa khóa bất đối xứng — không cần bí mật chia sẻ.
Zonos hỗ trợ xác thực máy chủ sang máy chủ thông qua OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Dịch vụ của bạn ký một JWT có thời gian sống ngắn bằng khóa riêng RSA của bạn; Zonos xác minh nó bằng cách sử dụng khóa công khai đã đăng ký của bạn và trả về một token Bearer có phạm vi giới hạn trong tổ chức của bạn.
Tóm tắt luồng:
Tạo một cặp khóa RSA và đăng ký khóa công khai của bạn với Zonos.
Lúc chạy, ký một xác nhận JWT bằng khóa riêng của bạn và POST nó đến điểm cuối token.
Zonos trả về một token truy cập có thời gian sống ngắn.
Bao gồm token truy cập dưới dạng Authorization: Bearer <token> trên mỗi yêu cầu API.
Bước 1 — Đăng ký khóa công khai của bạn (thiết lập một lần)
Tạo cặp khóa RSA 4096-bit và chia sẻ khóa công khai với Zonos. Điều này được thực hiện một lần trong quá trình onboarding.
Chia sẻ public_key.pem với Zonos. Lưu trữ private_key.pem trong trình quản lý bí mật chuyên dụng (AWS Secrets Manager, HashiCorp Vault, v.v.) — không bao giờ trong kiểm soát nguồn hoặc biến môi trường.
Zonos sẽ đăng ký khóa của bạn và trả về ID Tổ chức của bạn, trở thành yêu cầu iss trong tất cả các xác nhận JWT.
Bước 2 — Xây dựng một xác nhận JWT
Ký một JWT bằng RS256 bằng cách sử dụng khóa riêng của bạn. Xác nhận có hiệu lực cho một lần trao đổi token duy nhất — giữ cửa sổ hết hạn ngắn (60–300 giây).
Token truy cập hết hạn trong 5 phút theo mặc định. Lưu trữ token trong bộ nhớ cache và làm mới một cách chủ động — không yêu cầu token mới trên mỗi lệnh gọi API. Mỗi lần làm mới yêu cầu một xác nhận JWT được ký lại.
Xác thực OAuth 2.0
Xác thực OAuth 2.0
Xác thực các dịch vụ phía sau của bạn với Zonos bằng cách sử dụng mã hóa khóa bất đối xứng — không cần bí mật chia sẻ.
Zonos hỗ trợ xác thực máy chủ sang máy chủ thông qua OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Dịch vụ của bạn ký một JWT có thời gian sống ngắn bằng khóa riêng RSA của bạn; Zonos xác minh nó bằng cách sử dụng khóa công khai đã đăng ký của bạn và trả về một token Bearer có phạm vi giới hạn trong tổ chức của bạn.
Tóm tắt luồng:
Authorization: Bearer <token>trên mỗi yêu cầu API.Bước 1 — Đăng ký khóa công khai của bạn (thiết lập một lần)
Tạo cặp khóa RSA 4096-bit và chia sẻ khóa công khai với Zonos. Điều này được thực hiện một lần trong quá trình onboarding.
Tạo cặp khóa
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemChia sẻ
public_key.pemvới Zonos. Lưu trữprivate_key.pemtrong trình quản lý bí mật chuyên dụng (AWS Secrets Manager, HashiCorp Vault, v.v.) — không bao giờ trong kiểm soát nguồn hoặc biến môi trường.Zonos sẽ đăng ký khóa của bạn và trả về ID Tổ chức của bạn, trở thành yêu cầu
isstrong tất cả các xác nhận JWT.Bước 2 — Xây dựng một xác nhận JWT
Ký một JWT bằng
RS256bằng cách sử dụng khóa riêng của bạn. Xác nhận có hiệu lực cho một lần trao đổi token duy nhất — giữ cửa sổ hết hạn ngắn (60–300 giây).Các yêu cầu bắt buộc
iss"org_abc123")sub"checkout-service")aud"zonos-auth"expiatiatjtiTiêu đề JWT phải chỉ định
"alg": "RS256"và"typ": "JWT".Ví dụ về mã
import jwt, uuid, timewith open("private_key.pem") as f:private_key = f.read()now = int(time.time())assertion = jwt.encode({"iss": "org_abc123","sub": "checkout-service","aud": "zonos-auth","iat": now,"exp": now + 300,"jti": str(uuid.uuid4()),},private_key,algorithm="RS256",)Bước 3 — Trao đổi xác nhận cho token truy cập
Gửi JWT đã ký đến điểm cuối token Zonos để nhận token Bearer có thời gian sống ngắn.
Điểm cuối
application/x-www-form-urlencodedcũng được chấp nhận.Trường yêu cầu
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionYêu cầu và phản hồi
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeVí dụ mã đầy đủ
import requestsresponse = requests.post("https://auth.zonos.com/oauth/token",json={"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": assertion,},)data = response.json()access_token = data["access_token"]expires_in = data["expires_in"]Bước 4 — Gọi API Zonos bằng token truy cập
Bao gồm token truy cập dưới dạng token
Bearertrong tiêu đềAuthorizationtrên mỗi yêu cầu API Zonos.Yêu cầu ví dụ
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Vòng đời token và bộ nhớ cache
Token truy cập hết hạn trong 5 phút theo mặc định. Lưu trữ token trong bộ nhớ cache và làm mới một cách chủ động — không yêu cầu token mới trên mỗi lệnh gọi API. Mỗi lần làm mới yêu cầu một xác nhận JWT được ký lại.
import time, requests_cache = {"access_token": None, "expires_at": 0}def get_access_token():if time.time() < _cache["expires_at"] - 30:return _cache["access_token"]assertion = build_jwt_assertion()data = requests.post("https://auth.zonos.com/oauth/token",json={"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": assertion,},).json()_cache["access_token"] = data["access_token"]_cache["expires_at"] = time.time() + data["expires_in"]return _cache["access_token"]Tham khảo lỗi
Tất cả các lỗi tuân theo định dạng phản hồi lỗi OAuth 2.0 (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typekhông phảiurn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorNguyên nhân phổ biến của
invalid_grant:expnằm trong quá khứ — đảm bảo đồng hồ hệ thống của bạn được đồng bộ NTPaudkhông chính xác"zonos-auth"isskhông khớp với ID Tổ chức đã đăng ký của bạnCác thực hành bảo mật tốt nhất
jti. Một giá trị duy nhất cho mỗi xác nhận cho phép phát hiện phát lại phía máy chủ.access_tokenhoặcassertion. Coi cả hai là thông tin xác thực.Trang này có hữu ích không?