Configurare l’autenticazione per un connettore Streaming SDK
L’autenticazione è richiesta per tutti i connettori generati con Streaming SDK. Prima di inviare o rilasciare un connettore, configurare un meccanismo di autenticazione supportato:
Configura il meccanismo che corrisponde al modello di integrazione del connettore.
Prima di iniziare
Assicurati di disporre di:
- Implementazione del connettore Streaming SDK completata.
- Endpoint API di Streaming Ingestion di staging o test.
- Un’organizzazione di test Adobe e una sandbox.
- Un payload dell’evento di test.
- Un piano per memorizzare e ruotare le credenziali in modo sicuro.
- Un modo per acquisire i dettagli di richieste e risposte senza esporre segreti.
Requisiti OAuth aggiuntivi
Se usa OAuth 2.0, si assicuri di avere:
- Accesso a Adobe Developer Console.
- L’API o il profilo di prodotto richiesto per il connettore.
- ID client e segreto client per le credenziali selezionate.
- Gli ambiti richiesti.
- Il flusso OAuth e l’endpoint token richiesti dal connettore.
Per informazioni dettagliate sul tipo di credenziale Adobe e sull’implementazione, consulta:
Requisiti HMAC aggiuntivi
Se usi HMAC, assicurati di avere:
- Segreto condiviso configurato per il webhook o il connettore.
- Percorso sicuro per l’archiviazione del segreto.
- Codice che può calcolare una firma HMAC-SHA256.
- Il corpo esatto dell’evento serializzato che verrà inviato ad Adobe.
- Procedura di test per segreti validi, non validi, mancanti e ruotati.
Configurare OAuth 2.0
1. Crea o seleziona una credenziale Adobe
Innanzitutto, devi creare o selezionare le credenziali Adobe Developer Console richieste dal connettore.
Configura:
- Tipo di credenziali.
- L’API Adobe o il profilo di prodotto richiesto.
- Gli ambiti richiesti.
- Le impostazioni di reindirizzamento o consenso, se applicabili al flusso OAuth selezionato.
Non utilizzare un tipo di credenziali non supportato dal modello di integrazione del connettore.
2. Memorizza la configurazione OAuth in modo sicuro
Conservare i seguenti valori in modo sicuro:
- ID client.
- Segreto client.
- Ambiti richiesti.
- Endpoint token.
- Eventuali valori tenant, organizzazione o ambiente specifici del connettore.
Non confermare i segreti client nel controllo del codice sorgente né includerli in registri, messaggi di errore, schermate o risultati dei test.
3. Aggiungere la configurazione OAuth al connettore
Memorizza i valori di configurazione OAuth nella configurazione o nel servizio del connettore. Streaming SDK non definisce un campo di specifica della connessione per questo passaggio di autenticazione, perché governa il modo in cui il connettore chiama l’API Streaming Ingestion e non il modo in cui Experience Platform si connette all’origine.
La configurazione del connettore deve includere:
- Tipo di autenticazione.
- ID client.
- Segreto client.
- Ambiti.
- Endpoint token.
- Qualsiasi valore tenant o organizzazione aggiuntivo richiesto dal tipo di credenziale.
4. Ottenere un token di accesso
Implementa il flusso OAuth documentato per il tipo di credenziali.
Il connettore deve:
- Esegui l’autenticazione utilizzando le credenziali OAuth configurate.
- Richiedi gli ambiti richiesti dall’integrazione Streaming SDK.
- Memorizza il token di accesso in memoria o in un altro percorso sicuro.
- Aggiorna o riacquisisci il token in base alla durata del token.
- Evita di registrare il token o il segreto client.
5. Aggiungere il token di accesso alle richieste
Includi il token di accesso come token bearer nelle richieste inviate dal connettore:
Authorization: Bearer {ACCESS_TOKEN}
Usa HTTPS per tutte le richieste.
6. Gestire gli errori dei token
Il connettore deve rilevare e gestire gli errori di autenticazione, tra cui:
- Token di accesso mancanti.
- Token di accesso scaduti.
- Credenziali client non valide.
- Ambiti insufficienti.
- Credenziali revocate o disabilitate.
Alla scadenza di un token, ottieni un nuovo token utilizzando il flusso OAuth documentato e riprova solo quando l’operazione può essere ritentata in modo sicuro.
Configurare l’autenticazione basata su HMAC
1. Configurare il segreto condiviso
Crea o ottieni il segreto condiviso richiesto dal connettore e configuralo nella configurazione del connettore o del webhook.
Il segreto deve essere:
- Conservare in modo sicuro.
- Disponibile per il codice di firma in fase di esecuzione.
- Escluso dal controllo del codice sorgente e dai registri.
- Ruotato in base ai criteri di sicurezza.
2. Serializzare l’evento
Serializzare l’evento prima di calcolare la firma.
La firma deve essere calcolata dallo stesso messaggio serializzato inviato dal connettore nel corpo della richiesta.
serializedMessage = serialize(event)
Non calcolare la firma da una rappresentazione dell’evento e non inviare un’altra rappresentazione. Le modifiche apportate allo spazio vuoto, all’ordine delle proprietà, all’escape, alla codifica o alle terminazioni di riga possono impedire la convalida della firma.
3. Calcola la firma HMAC-SHA256
Calcolare il valore HMAC-SHA256 utilizzando:
- Chiave: il segreto condiviso configurato.
- Messaggio: il corpo della richiesta serializzata.
signature = HMAC-SHA256(secret, serializedMessage)
4. Aggiungere l’intestazione HMAC
Aggiungere la firma calcolata alla richiesta come intestazione x-hmac-sha256:
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
Ad esempio, l’intestazione viene risolta in un valore simile a:
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
Il valore dell’intestazione deve rappresentare il calcolo HMAC-SHA256 per il corpo esatto della richiesta inviato ad Adobe.
5. Inviare la richiesta
Invia la richiesta firmata tramite HTTPS all’endpoint API Streaming Ingestion.
L’API Streaming Ingestion verifica la firma prima di elaborare l’evento. Le richieste con una firma mancante o non valida vengono rifiutate.
6. Ruota il segreto in modo sicuro
Quando ruoti un segreto, segui questa sequenza:
- Crea un nuovo segreto nel sistema di gestione delle credenziali.
- Mantenere attivo il segreto esistente durante la distribuzione del nuovo segreto, se sono supportati i segreti sovrapposti.
- Aggiorna la configurazione del connettore con il nuovo segreto.
- Distribuisci o salva la configurazione.
- Invia una richiesta di test e verifica che l’autenticazione abbia esito positivo.
- Monitora gli errori di autenticazione, quindi revoca il vecchio segreto dopo che tutte le istanze del connettore hanno utilizzato quello nuovo.
Verificare il connettore
Verifica il connettore con scenari di autenticazione sia di successo che di insuccesso.
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| Test | Risultato previsto |
| Richiesta con un token di accesso valido | L’evento viene accettato ed elaborato. |
| Richiedi senza token di accesso | Richiesta rifiutata. |
| Richiesta con token di accesso scaduto | La richiesta viene rifiutata o il connettore ottiene un nuovo token e tenta di nuovo in base ai criteri dei tentativi. |
| Richiesta con token di accesso non valido | Richiesta rifiutata. |
| Richiesta con ambiti insufficienti | Richiesta rifiutata. |
| Richiedi dopo rotazione credenziali | Il connettore ottiene e utilizza correttamente le nuove credenziali. |
| 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 | Risultato previsto |
| Richiesta con firma valida e segreto corrente | L’evento viene accettato ed elaborato. |
Richiedi senza x-hmac-sha256 |
Richiesta rifiutata. |
| Richiesta con firma non valida | Richiesta rifiutata. |
| Richiesta firmata con segreto errato | Richiesta rifiutata. |
| Corpo della richiesta modificato dopo la generazione della firma | Richiesta rifiutata. |
| Richiesta firmata con un segreto precedente valido durante la rotazione | Il risultato segue il documentato comportamento di rotazione segreta. |
| Richiesta firmata con un segreto rimosso | Richiesta rifiutata. |
Per ciascuna prova registrare quanto segue:
- Metodo di richiesta ed endpoint.
- Intestazioni di richiesta con segreti e token oscurati.
- Corpo della richiesta serializzato.
- Meccanismo di autenticazione utilizzato.
- Stato e corpo della risposta.
- Marca temporale e identificatore di correlazione o di traccia, se disponibile.
- Se l’evento è stato acquisito correttamente.
Risoluzione dei problemi
Errori di autenticazione OAuth
Verifica quanto segue:
- Il token di accesso è stato generato per l’organizzazione e l’ambiente Adobe corretti.
- L’ID client e il segreto client appartengono alle credenziali configurate.
- Gli ambiti richiesti sono corretti.
- Il token di accesso non è scaduto.
- Il token viene inviato utilizzando lo schema Authorization: Bearer.
- Il connettore sta utilizzando l’endpoint token corretto.
- Le credenziali hanno accesso all’API o al profilo di prodotto richiesto.
Errori di autenticazione HMAC
Verifica quanto segue:
- L’intestazione
x-hmac-sha256è presente. - Il nome e il valore dell’intestazione vengono digitati correttamente.
- Il connettore sta utilizzando il segreto corretto.
- La firma viene calcolata con HMAC-SHA256.
- La firma viene calcolata sul corpo esatto della richiesta serializzata.
- Il corpo della richiesta non viene riformattato dopo il calcolo della firma.
- La codifica della firma e le lettere maiuscole richieste sono corrette.
- Il connettore utilizza il segreto corrente o precedente corretto durante la rotazione.
- Il segreto è disponibile per il runtime e non è stato troncato o alterato.
Requisiti per l’invio
Prima di inviare o rilasciare il connettore, verifica quanto segue:
- Il connettore utilizza l’autenticazione basata su OAuth 2.0 o HMAC per ogni richiesta all’API Streaming Ingestion.
- Hai testato gli scenari in Verifica il connettore e registrato i risultati.
- Il connettore rifiuta le richieste non autenticate e non autenticate correttamente.
- I segreti e i token non vengono salvati nel controllo del codice sorgente, nei registri, nei messaggi di errore o nelle schermate.
Passaggi successivi
Con l’autenticazione configurata e verificata, continuare a Verificare e inviare l’origine. Per informazioni su come documentare i requisiti di autenticazione per la tua origine, consulta Documentare la tua origine (Streaming SDK).