Uwierzytelniaj usługi zaplecza w Zonos przy użyciu kryptografii z kluczem asymetrycznym — bez wspólnych tajemnic.
Zonos obsługuje uwierzytelnianie maszyna-do-maszyny za pośrednictwem OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Twoja usługa podpisuje krótkotrwały JWT swoim prywatnym kluczem RSA; Zonos weryfikuje go za pomocą zarejestrowanego klucza publicznego i zwraca token nośnika ograniczony do twojej organizacji.
Podsumowanie przepływu:
Wygeneruj parę kluczy RSA i zarejestruj swój klucz publiczny w Zonos.
W czasie wykonywania podpisz asercję JWT swoim kluczem prywatnym i wyślij ją za pomocą żądania POST do punktu końcowego tokenu.
Zonos zwraca krótkotrwały token dostępu.
Dołącz token dostępu jako Authorization: Bearer <token> w każdym żądaniu API.
Krok 1 — Zarejestruj swój klucz publiczny (jednorazowa konfiguracja)
Wygeneruj parę kluczy RSA o rozmiarze 4096 bitów i udostępnij klucz publiczny w Zonos. Jest to wykonywane raz podczas wdrażania.
Udostępnij plik public_key.pem w Zonos. Przechowuj plik private_key.pem w dedykowanym menedżerze tajemnic (AWS Secrets Manager, HashiCorp Vault, itp.) — nigdy w kontroli źródła lub zmiennych środowiskowych.
Zonos zarejestruje Twój klucz i zwróci Twój identyfikator organizacji, który staje się roszczeniem iss we wszystkich asercjach JWT.
Krok 2 — Zbuduj asercję JWT
Podpisz JWT za pomocą RS256 przy użyciu swojego klucza prywatnego. Asercja jest ważna dla pojedynczej wymiany tokenów — utrzymuj okno ważności krótkie (60–300 sekund).
Tokeny dostępu wygasają w ciągu 5 minut domyślnie. Buforuj token i odśwież proaktywnie — nie żądaj nowego tokenu przy każdym wywołaniu API. Każde odświeżenie wymaga nowo podpisanej asercji JWT.
Uwierzytelnianie OAuth 2.0
Uwierzytelnianie OAuth 2.0
Uwierzytelniaj usługi zaplecza w Zonos przy użyciu kryptografii z kluczem asymetrycznym — bez wspólnych tajemnic.
Zonos obsługuje uwierzytelnianie maszyna-do-maszyny za pośrednictwem OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Twoja usługa podpisuje krótkotrwały JWT swoim prywatnym kluczem RSA; Zonos weryfikuje go za pomocą zarejestrowanego klucza publicznego i zwraca token nośnika ograniczony do twojej organizacji.
Podsumowanie przepływu:
Authorization: Bearer <token>w każdym żądaniu API.Krok 1 — Zarejestruj swój klucz publiczny (jednorazowa konfiguracja)
Wygeneruj parę kluczy RSA o rozmiarze 4096 bitów i udostępnij klucz publiczny w Zonos. Jest to wykonywane raz podczas wdrażania.
Wygeneruj parę kluczy
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemUdostępnij plik
public_key.pemw Zonos. Przechowuj plikprivate_key.pemw dedykowanym menedżerze tajemnic (AWS Secrets Manager, HashiCorp Vault, itp.) — nigdy w kontroli źródła lub zmiennych środowiskowych.Zonos zarejestruje Twój klucz i zwróci Twój identyfikator organizacji, który staje się roszczeniem
isswe wszystkich asercjach JWT.Krok 2 — Zbuduj asercję JWT
Podpisz JWT za pomocą
RS256przy użyciu swojego klucza prywatnego. Asercja jest ważna dla pojedynczej wymiany tokenów — utrzymuj okno ważności krótkie (60–300 sekund).Wymagane roszczenia
iss"org_abc123")sub"checkout-service")aud"zonos-auth"expiatiatjtiNagłówek JWT musi określić
"alg": "RS256"i"typ": "JWT".Przykłady kodu
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",)Krok 3 — Wymień asercję na token dostępu
Wyślij podpisany JWT do punktu końcowego tokenu Zonos, aby otrzymać krótkotrwały token nośnika.
Punkt końcowy
Obsługiwany jest również
application/x-www-form-urlencoded.Pola żądania
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionŻądanie i odpowiedź
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopePełne przykłady kodu
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"]Krok 4 — Wywołaj interfejsy API Zonos za pomocą tokenu dostępu
Dołącz token dostępu jako token
Bearerw nagłówkuAuthorizationw każdym żądaniu API Zonos.Przykładowe żądanie
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Cykl życia tokenu i buforowanie
Tokeny dostępu wygasają w ciągu 5 minut domyślnie. Buforuj token i odśwież proaktywnie — nie żądaj nowego tokenu przy każdym wywołaniu API. Każde odświeżenie wymaga nowo podpisanej asercji JWT.
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"]Odniesienie błędów
Wszystkie błędy podlegają formatowi odpowiedzi błędu OAuth 2.0 (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typenie byłurn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorTypowe przyczyny
invalid_grant:expjest w przeszłości — upewnij się, że zegar systemu jest zsynchronizowany za pomocą NTPaudnie jest dokładnie"zonos-auth"issnie odpowiada zarejestrowanemu identyfikatorowi organizacjiNajlepsze praktyki bezpieczeństwa
jti. Unikatowa wartość na asercję umożliwia wykrywanie powtórzeń po stronie serwera.access_tokenlubassertion. Traktuj oba jako poświadczenia.Czy ta strona była pomocna?