Express Kurier. Direkt.
Auch Overnight.
x25pronto Schweiz bringt Ware direkt ans Ziel. Für kleine Ware fährt ein Auto. Für mehr Platz gibt es Transporter oder XL. Direkt, Express und Overnight fahren von Montag bis Sonntag. Freie Zeiten stehen im Kalender.
Implementierung von OAuth2‑Flows für B2B‑Logistikintegrationen
Schritt‑für‑Schritt Anleitung für Entwickler und Integrationsverantwortliche: Welcher OAuth2‑Flow passt für API‑Zugriffe zwischen Speditionssoftware und x25pronto‑Systemen und wie läuft das Partner‑Onboarding?
Kurzantwort
Kurz: Wählen Sie den OAuth2‑Grant, der zu Ihrer Integrationsarchitektur passt (Client Credentials für Server‑zu‑Server, Authorization Code für Benutzer‑begleitete Integrationen). Definieren Sie Scopes für minimalen Zugriff, registrieren Sie Redirect‑URLs mit https, sichern Sie Client‑Geheimnisse und führen Sie ein klares Partner‑Onboarding mit Test‑ und Produktions‑Keys durch.
1. Welcher Grant‑Type passt zu Ihrer Integration?
Für Server‑zu‑Server‑Kommunikation ohne Nutzerinteraktion nutzen Sie den Client Credentials Grant. Er ist einfach, sicher und geeignet für automatisierte API‑Aufrufe zwischen Logistiksystemen. Wenn ein Agent oder Sachbearbeiter im Browser oder in einer App aktiv einwilligen muss, verwenden Sie den Authorization Code Grant mit PKCE. Dieser Flow schützt das Authorization Code‑Token gegen Abfangversuche und ist empfohlen, wenn ein Benutzer explizit zustimmen soll.
2. Scopes: Prinzip der minimalen Rechte
Definieren Sie Scopes knapp und eindeutig. Beispiele: shipment.read, shipment.write, booking.create, booking.manage. Vergeben Sie nur die Scopes, die der Client konkret braucht. Dokumentieren Sie die Bedeutung jedes Scopes in Ihrer API‑Dokumentation, damit Partner wissen, welche Funktionen sie anfordern müssen.
3. Redirect‑URLs und sichere Registrierung
Alle Redirect‑URLs müssen https verwenden. Akzeptieren Sie nur vorregistrierte Redirect‑URLs im Produktivbetrieb. Vermeiden Sie Wildcards. Bei mobilen Apps oder SPAs nutzen Sie registrierte App‑Schemes oder PKCE (Proof Key for Code Exchange). Prüfen Sie Redirect‑URLs strikt beim Token‑Austausch.
4. Client‑ID, Client‑Secret und Speicherung
Geben Sie Client‑Secrets nur an vertrauenswürdige Server‑Seiten. Speichern Sie Secrets sicher (z. B. in Vaults). Für öffentliche Clients (z. B. Single‑Page‑Apps) verwenden Sie keinen Client‑Secret, sondern PKCE. Rotieren Sie Secrets regelmässig und protokollieren Sie Änderungen im Onboarding‑Protokoll.
5. Token‑Lebensdauer und Refresh‑Tokens
Setzen Sie Access‑Tokens mit kurzer Laufzeit (z. B. Minuten bis Stunden) und ermöglichen Sie bei Bedarf Refresh‑Tokens für Authorisation Code Clients. Für Client Credentials ist meist ein neues Access‑Token durch erneute Authentifizierung üblich. Loggen Sie Token‑Ausgaben und -Fehler für Security‑Audits.
6. Partner‑Onboarding Checklist
1) Technische Kontaktperson benennen. 2) Client‑Typ (confidential/public) klären. 3) Redirect‑URL(s) übermitteln. 4) Benötigte Scopes angeben. 5) Test‑Client‑ID/Secret bereitstellen und Testendpunkte erklären. 6) Sicherheitsanforderungen und Secret‑Rotation erklären. 7) Produktions‑Freigabe nach Integrationstests erteilen. 8) Monitoring‑Zugänge und Ansprechpartner für Störungen bereitstellen.
Häufige Fragen
Welche Flow‑Option ist für Batch‑Massendaten am besten?
Für Batch‑Prozesse ohne Benutzerinteraktion eignet sich der Client Credentials Grant. Er erlaubt automatisierte, geplante API‑Aufrufe zwischen Backend‑Systemen.
Wie teste ich Redirect‑URLs ohne Produktions‑Domain?
Nutzen Sie dedizierte Test‑Domains oder lokale Tunneling‑Tools (z. B. sichere https‑Tunnel). Registrieren Sie Test‑Redirect‑URLs separat und vermeiden Sie die Verwendung von Produktions‑Credentials.
Wann sollten wir PKCE einsetzen?
PKCE sollten Sie für alle öffentlichen Clients einsetzen: native Apps, SPAs oder Browser‑basierte Tools. PKCE schützt den Authorization Code Flow ohne Client‑Secret.
Welche Logs sollte ich speichern?
Speichern Sie Zeitstempel, Client‑ID, Scope‑Anfragen, Statuscodes, IP‑Adressen der Anfragen und Fehlerdetails. PII nur nach Bedarf und DSGVO/DSG‑konform.