Konfigurieren der Authentifizierung für einen Streaming-SDK-Connector
Alle mit Streaming SDK erstellten Connectoren müssen authentifiziert werden. Bevor Sie einen Connector senden oder freigeben, konfigurieren Sie einen unterstützten Authentifizierungsmechanismus:
Konfigurieren Sie den Mechanismus, der dem Integrationsmodell Ihres Connectors entspricht.
Voraussetzungen
Vergewissern Sie sich, dass Sie Folgendes haben:
- Eine abgeschlossene Implementierung des Streaming-SDK-Connectors.
- Ein Staging- oder Test-Streaming-Aufnahme-API-Endpunkt.
- Testen Sie eine Adobe-Organisation und -Sandbox.
- Payload eines Testereignisses.
- Ein Plan zum sicheren Speichern und Rotieren von Anmeldeinformationen.
- Eine Möglichkeit, Anfrage- und Antwortdetails zu erfassen, ohne Geheimnisse offenzulegen.
Zusätzliche OAuth-Anforderungen
Wenn Sie OAuth 2.0 verwenden, stellen Sie Folgendes sicher:
- Zugriff auf Adobe Developer Console.
- Die erforderliche API oder das Produktprofil für den Connector.
- Die Client-ID und das Client-Geheimnis für die ausgewählte Berechtigung.
- Die erforderlichen Bereiche.
- Der für den Connector erforderliche OAuth-Fluss- und -Token-Endpunkt.
Den entsprechenden Adobe-Berechtigungstyp und die Implementierungsdetails finden Sie unter:
Zusätzliche HMAC-Anforderungen
Wenn Sie HMAC verwenden, stellen Sie sicher, dass Sie über Folgendes verfügen:
- Ein für den Webhook oder Connector konfiguriertes gemeinsames Geheimnis.
- Ein sicherer Speicherort für das Speichern der geheimen Daten.
- Code zur Berechnung einer HMAC-SHA256-Signatur.
- Der exakte serialisierte Ereignistext, der an Adobe gesendet wird.
- Ein Testverfahren für gültige, ungültige, fehlende und rotierte geheime Daten.
Konfigurieren von OAuth 2.0
1. Adobe-Anmeldedaten erstellen oder auswählen
Zunächst müssen Sie die für Ihren Connector erforderlichen Adobe Developer Console-Anmeldeinformationen erstellen oder auswählen.
Konfigurieren:
- Der Berechtigungstyp.
- Die erforderliche Adobe-API oder das erforderliche Produktprofil.
- Die erforderlichen Bereiche.
- Die Umleitungs- oder Einverständniseinstellungen, falls für den ausgewählten OAuth-Fluss zutreffend.
Verwenden Sie keinen Berechtigungstyp, der vom Integrationsmodell des Connectors nicht unterstützt wird.
2. Sicheres Speichern der OAuth-Konfiguration
Speichern Sie die folgenden Werte sicher:
- Client-ID.
- Client-Geheimnis.
- Erforderliche Bereiche.
- Token-Endpunkt.
- Alle Connector-spezifischen Mandanten-, Organisations- oder Umgebungswerte.
Übertragen Sie keine Client-Geheimnisse in die Quell-Code-Verwaltung und schließen Sie sie nicht in Protokolle, Fehlermeldungen, Screenshots oder Testergebnisse ein.
3. Hinzufügen der OAuth-Konfiguration zu Ihrem Connector
Speichern Sie die OAuth-Konfigurationswerte in der eigenen Konfiguration Ihres Connectors oder in Ihrem eigenen Service. Streaming-SDK definiert kein Verbindungsspezifikationsfeld für diesen Authentifizierungsschritt, da dadurch gesteuert wird, wie Ihr Connector die Streaming-Aufnahme-API aufruft, und nicht, wie Experience Platform eine Verbindung zu Ihrer Quelle herstellt.
Die Konfiguration Ihres Connectors muss Folgendes enthalten:
- Authentifizierungstyp.
- Client-ID.
- Client-Geheimnis.
- Bereiche.
- Token-Endpunkt.
- Alle zusätzlichen Mandanten- oder Organisationswerte, die für Ihren Berechtigungstyp erforderlich sind.
4. Abrufen eines Zugriffstokens
Implementieren Sie den dokumentierten OAuth-Fluss für Ihren Berechtigungstyp.
Der Connector muss:
- Authentifizieren Sie sich mit den konfigurierten OAuth-Anmeldeinformationen.
- Anfordern der für die Streaming-SDK-Integration erforderlichen Bereiche.
- Speichern Sie das Zugriffstoken im Speicher oder an einem anderen sicheren Speicherort.
- Aktualisieren oder erwerben Sie das Token entsprechend der Token-Lebensdauer erneut.
- Vermeiden Sie die Protokollierung des Tokens oder des Client-Geheimnisses.
5. Hinzufügen des Zugriffstokens zu Anfragen
Schließen Sie das Zugriffs-Token als Bearer-Token in Anfragen ein, die vom Connector gesendet werden:
Authorization: Bearer {ACCESS_TOKEN}
Verwenden Sie HTTPS für alle Anfragen.
6. Token-Fehler beheben
Der Connector sollte Authentifizierungsfehler erkennen und behandeln, darunter:
- Fehlende Zugriffstoken.
- Abgelaufene Zugriffstoken.
- Ungültige Client-Anmeldedaten.
- Unzureichende Bereiche.
- Gesperrte oder deaktivierte Anmeldeinformationen.
Wenn ein Token abläuft, rufen Sie mithilfe des dokumentierten OAuth-Flusses ein neues Token ab und versuchen Sie es nur, wenn der Vorgang sicher ist, es erneut zu versuchen.
Konfigurieren der HMAC-basierten Authentifizierung
1. Konfigurieren des gemeinsamen Geheimnisses
Erstellen oder beziehen Sie die für den Connector erforderlichen gemeinsamen geheimen Daten und konfigurieren Sie sie im Connector- oder Webhook-Setup.
Das Geheimnis muss lauten:
- Sicher aufbewahren.
- Verfügbar für den Signiercode zur Laufzeit.
- Aus der Quell-Code-Verwaltung und den Protokollen ausgeschlossen.
- Rotiert gemäß Ihrer Sicherheitsrichtlinie.
2. Ereignis serialisieren
Serialisieren Sie das Ereignis vor der Berechnung der Signatur.
Die Signatur muss aus derselben serialisierten Nachricht berechnet werden, die der Connector im Anfragetext sendet.
serializedMessage = serialize(event)
Berechnen Sie die Signatur nicht aus einer Darstellung des Ereignisses und senden Sie keine andere Darstellung. Änderungen an Leerzeichen, Eigenschaftsreihenfolge, Escape-Zeichen, Codierung oder Zeilenenden können dazu führen, dass die Signaturüberprüfung fehlschlägt.
3. Berechnung der HMAC-SHA256-Signatur
Berechnen Sie den HMAC-SHA256-Wert wie folgt:
- Schlüssel: Das konfigurierte gemeinsame Geheimnis.
- Nachricht: Der serialisierte Anfragetext.
signature = HMAC-SHA256(secret, serializedMessage)
4. HMAC-Header hinzufügen
Fügen Sie der Anfrage die berechnete Signatur als x-hmac-sha256 hinzu:
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
Beispielsweise wird die Kopfzeile aufgelöst zu einem Wert, der ähnlich ist wie:
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
Der Wert im Header muss der HMAC-SHA256-Berechnung für den exakten Anfragetext entsprechen, der an Adobe gesendet wird.
5. Anforderung senden
Senden Sie die signierte Anfrage über HTTPS an den Endpunkt der Streaming-Aufnahme-API.
Die Streaming-Aufnahme-API überprüft die Signatur, bevor das Ereignis verarbeitet wird. Anfragen mit fehlender oder ungültiger Signatur werden abgelehnt.
6. Sicheres Drehen der geheimen Daten
Folgen Sie beim Drehen von geheimen Daten dieser Reihenfolge:
- Erstellen Sie ein neues Geheimnis in Ihrem Berechtigungs-Management-System.
- Lassen Sie die vorhandenen geheimen Daten aktiv, während Sie die neuen geheimen Daten bereitstellen, wenn sich überschneidende geheime Daten unterstützt werden.
- Aktualisieren Sie die Connector-Konfiguration mit den neuen geheimen Daten.
- Bereitstellen oder Speichern der Konfiguration.
- Senden Sie eine Testanfrage und überprüfen Sie, ob die Authentifizierung erfolgreich ist.
- Überwachen Sie nach Authentifizierungsfehlern und widerrufen Sie dann die alten geheimen Daten, nachdem alle Connector-Instanzen die neue verwendet haben.
Überprüfen des Connectors
Testen Sie den Connector mit erfolgreichen und nicht erfolgreichen Authentifizierungsszenarien.
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| Test | Erwartetes Ergebnis |
| Anfrage mit einem gültigen Zugriffstoken | Das Ereignis wird akzeptiert und verarbeitet. |
| Anfrage ohne Zugriffs-Token | Die Anfrage wird abgelehnt. |
| Anfrage mit abgelaufenem Zugriffstoken | Die Anfrage wird abgelehnt, oder der Connector erhält ein neues Token und versucht es gemäß seiner Wiederholungsrichtlinie erneut. |
| Anfrage mit einem ungültigen Zugriffstoken | Die Anfrage wird abgelehnt. |
| Anfrage mit unzureichendem Umfang | Die Anfrage wird abgelehnt. |
| Anfordern nach Rotation der Anmeldeinformationen | Der Connector ruft die neue Berechtigung erfolgreich ab und verwendet sie. |
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 | |
|---|---|
| Test | Erwartetes Ergebnis |
| Anfrage mit einer gültigen Signatur und aktuellem Geheimnis | Das Ereignis wird akzeptiert und verarbeitet. |
Anfrage ohne x-hmac-sha256 |
Die Anfrage wird abgelehnt. |
| Anfrage mit ungültiger Signatur | Die Anfrage wird abgelehnt. |
| Mit falschem Geheimnis signierte Anfrage | Die Anfrage wird abgelehnt. |
| Anfragetext wurde nach der Signaturgenerierung geändert | Die Anfrage wird abgelehnt. |
| Anforderung wurde während der Rotation mit einem gültigen vorherigen Geheimnis signiert | Das Ergebnis folgt dem dokumentierten Verhalten bei geheimer Rotation. |
| Mit einem entfernten Geheimnis signierte Anfrage | Die Anfrage wird abgelehnt. |
Notieren Sie sich für jeden Test Folgendes:
- Anfragemethode und -endpunkt.
- Anfrage-Header, mit Geheimnissen und Token geschwärzt.
- Serialisierter Anfragetext.
- Verwendeter Authentifizierungsmechanismus.
- Antwortstatus und -text.
- Zeitstempel und Korrelations- oder Ablaufverfolgungskennung, falls verfügbar.
- Ob das Ereignis erfolgreich aufgenommen wurde.
Fehlerbehebung
OAuth-Authentifizierungsfehler
Überprüfen Sie Folgendes:
- Das Zugriffstoken wurde für die richtige Adobe-Organisation und -Umgebung generiert.
- Die Client-ID und das Client-Geheimnis gehören zur konfigurierten Berechtigung.
- Die angeforderten Bereiche sind korrekt.
- Das Zugriffstoken ist nicht abgelaufen.
- Das Token wird mithilfe des Authorization: Bearer-Schemas gesendet.
- Der Connector verwendet den richtigen Token-Endpunkt.
- Die Berechtigung hat Zugriff auf die erforderliche API oder das erforderliche Produktprofil.
HMAC-Authentifizierungsfehler
Überprüfen Sie Folgendes:
- Die
x-hmac-sha256Kopfzeile ist vorhanden. - Der Header-Name und der -Wert werden korrekt geschrieben.
- Der Connector verwendet die richtigen geheimen Daten.
- Die Signatur wird mit HMAC-SHA256 berechnet.
- Die Signatur wird für den exakten serialisierten Anfragetext berechnet.
- Der Anfragetext wird nach der Berechnung der Signatur nicht neu formatiert.
- Die erforderliche Signaturcodierung und die Groß-/Kleinschreibung sind korrekt.
- Der Connector verwendet während der Rotation die richtigen aktuellen oder vorherigen geheimen Daten.
- Die geheimen Daten sind zur Laufzeit verfügbar und wurden weder gekürzt noch geändert.
Einreichungsanforderungen
Bevor Sie Ihren Connector übermitteln oder freigeben, bestätigen Sie Folgendes:
- Ihr Connector verwendet OAuth 2.0- oder HMAC-basierte Authentifizierung für jede Anfrage an die Streaming-Aufnahme-API.
- Sie haben die Szenarien in Überprüfen des Connectors getestet und die Ergebnisse aufgezeichnet.
- Ihr Connector lehnt nicht authentifizierte und falsch authentifizierte Anfragen ab.
- Geheime Daten und Token werden nicht in die Quell-Code-Verwaltung, in Protokolle, Fehlermeldungen oder Screenshots übertragen.
Nächste Schritte
Fahren Sie nach der Konfiguration und Verifizierung der Authentifizierung Testen und Senden Ihrer Quelle fort. Informationen zum Dokumentieren der Authentifizierungsanforderungen für Ihre Quelle finden Sie unter Dokumentieren Ihrer Quelle (Streaming-SDK).