Authentifizieren Sie Ihre Backend-Services bei Zonos mit asymmetrischer Schlüsselkryptografie — ohne gemeinsame Geheimnisse.
Zonos unterstützt Machine-to-Machine-Authentifizierung über OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Ihr Service signiert ein kurzlebiges JWT mit Ihrem RSA-Privatschlüssel; Zonos verifiziert es mit Ihrem registrierten öffentlichen Schlüssel und gibt ein Bearer-Token zurück, das auf Ihre Organisation beschränkt ist.
Ablaufübersicht:
Generieren Sie ein RSA-Schlüsselpaar und registrieren Sie Ihren öffentlichen Schlüssel bei Zonos.
Signieren Sie zur Laufzeit eine JWT-Assertion mit Ihrem Privatschlüssel und senden Sie sie per POST an den Token-Endpunkt.
Zonos gibt ein kurzlebiges Access Token zurück.
Fügen Sie das Access Token als Authorization: Bearer <token> bei jeder API-Anfrage hinzu.
Teilen Sie public_key.pem mit Zonos. Speichern Sie private_key.pem in einem dedizierten Secrets Manager (AWS Secrets Manager, HashiCorp Vault usw.) — niemals in der Quellcodeverwaltung oder in Umgebungsvariablen.
Zonos registriert Ihren Schlüssel und gibt Ihre Organization ID zurück, die zum iss-Claim in allen JWT-Assertions wird.
Schritt 2 — JWT-Assertion erstellen
Signieren Sie ein JWT mit RS256 unter Verwendung Ihres Privatschlüssels. Die Assertion ist für einen einzelnen Token-Austausch gültig — halten Sie das Ablauffenster kurz (60–300 Sekunden).
Access Tokens laufen standardmäßig nach 5 Minuten ab. Cachen Sie das Token und erneuern Sie es proaktiv — fordern Sie nicht bei jedem API-Aufruf ein neues Token an. Jede Erneuerung erfordert eine neu signierte JWT-Assertion.
Schützen Sie Ihren Privatschlüssel. Speichern Sie ihn in einem dedizierten Secrets Manager — niemals in der Quellcodeverwaltung, Umgebungsvariablen oder Logs.
Halten Sie Assertions kurzlebig. 60–300 Sekunden sind Standard; es gibt keinen Grund, längere auszustellen.
Fügen Sie jti hinzu. Ein eindeutiger Wert pro Assertion ermöglicht serverseitige Replay-Erkennung.
Rotieren Sie Schlüsselpaare regelmäßig. Registrieren Sie einen neuen öffentlichen Schlüssel bei Zonos, bevor Sie den alten widerrufen, um Ausfallzeiten zu vermeiden.
Protokollieren Sie niemals access_token- oder assertion-Werte. Behandeln Sie beides als Anmeldedaten.
OAuth 2.0-Authentifizierung
OAuth 2.0-Authentifizierung
Authentifizieren Sie Ihre Backend-Services bei Zonos mit asymmetrischer Schlüsselkryptografie — ohne gemeinsame Geheimnisse.
Zonos unterstützt Machine-to-Machine-Authentifizierung über OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Ihr Service signiert ein kurzlebiges JWT mit Ihrem RSA-Privatschlüssel; Zonos verifiziert es mit Ihrem registrierten öffentlichen Schlüssel und gibt ein Bearer-Token zurück, das auf Ihre Organisation beschränkt ist.
Ablaufübersicht:
Authorization: Bearer <token>bei jeder API-Anfrage hinzu.Schritt 1 — Öffentlichen Schlüssel registrieren (einmalige Einrichtung)
Generieren Sie ein 4096-Bit-RSA-Schlüsselpaar und teilen Sie den öffentlichen Schlüssel mit Zonos. Dies erfolgt einmalig während des Onboardings.
Schlüsselpaar generieren
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemTeilen Sie
public_key.pemmit Zonos. Speichern Sieprivate_key.pemin einem dedizierten Secrets Manager (AWS Secrets Manager, HashiCorp Vault usw.) — niemals in der Quellcodeverwaltung oder in Umgebungsvariablen.Zonos registriert Ihren Schlüssel und gibt Ihre Organization ID zurück, die zum
iss-Claim in allen JWT-Assertions wird.Schritt 2 — JWT-Assertion erstellen
Signieren Sie ein JWT mit
RS256unter Verwendung Ihres Privatschlüssels. Die Assertion ist für einen einzelnen Token-Austausch gültig — halten Sie das Ablauffenster kurz (60–300 Sekunden).Erforderliche Claims
iss"org_abc123")sub"checkout-service")aud"zonos-auth"seinexpiatiatjtiDer JWT-Header muss
"alg": "RS256"und"typ": "JWT"angeben.Codebeispiele
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",)Schritt 3 — Assertion gegen Access Token tauschen
Senden Sie das signierte JWT an den Zonos-Token-Endpunkt, um ein kurzlebiges Bearer-Token zu erhalten.
Endpunkt
application/x-www-form-urlencodedwird ebenfalls akzeptiert.Anfragefelder
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionAnfrage und Antwort
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeVollständige Codebeispiele
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"]Schritt 4 — Zonos-APIs mit dem Access Token aufrufen
Fügen Sie das Access Token als
Bearer-Token imAuthorization-Header bei jeder Zonos-API-Anfrage hinzu.Beispielanfrage
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Token-Lebenszyklus und Caching
Access Tokens laufen standardmäßig nach 5 Minuten ab. Cachen Sie das Token und erneuern Sie es proaktiv — fordern Sie nicht bei jedem API-Aufruf ein neues Token an. Jede Erneuerung erfordert eine neu signierte JWT-Assertion.
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"]Fehlerreferenz
Alle Fehler folgen dem OAuth 2.0-Fehlerantwortformat (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typewar nichturn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorHäufige Ursachen für
invalid_grant:expliegt in der Vergangenheit — stellen Sie sicher, dass Ihre Systemuhr NTP-synchronisiert istaudist nicht exakt"zonos-auth"issstimmt nicht mit Ihrer registrierten Organization ID übereinSicherheits-Best Practices
jtihinzu. Ein eindeutiger Wert pro Assertion ermöglicht serverseitige Replay-Erkennung.access_token- oderassertion-Werte. Behandeln Sie beides als Anmeldedaten.War diese Seite hilfreich?