Origini dati esterne external-data-sources

In questa pagina: Connettiti alle API REST di terze parti e configura l’autenticazione in modo da poter richiamare dati esterni nei tuoi percorsi per condizioni e personalizzazione.

Utilizzare origini dati esterne gs-ext-data-sources

Le origini dati esterne consentono di definire una connessione a sistemi di terze parti, ad esempio se si utilizza un sistema di prenotazione alberghiera per verificare se un cliente ha registrato una stanza. A differenza dell’origine dati incorporata Adobe Experience Platform, è possibile creare tutte le origini dati esterne necessarie.

Sono supportate le API REST basate su POST o GET e che restituiscono JSON. Sono supportate le modalità chiave API, sia l’autenticazione di base che personalizzata.

Prendiamo l’esempio di un servizio API meteorologico che intendo sfruttare per personalizzare i comportamenti del mio percorso secondo i dati meteo in tempo reale.

Di seguito sono riportati due esempi della chiamata API:

La chiamata è composta da un URL principale, https://api.adobeweather.org/weather, due set di parametri (“city” per la città e “lat/long” per la latitudine e la longitudine) e la chiave API (appid).

Creare e configurare un’origine dati esterna create-ext-data-sources

Di seguito sono riportati i passaggi principali per creare e configurare una nuova origine dati esterna:

Sono consentiti solo caratteri alfanumerici e trattini bassi. La lunghezza massima è di 30 caratteri.

Per il set di parametri “long/lat”, viene creato un gruppo di campi con le seguenti informazioni:

In caso di una chiamata GET che richieda i parametri, inseriscili nel campo Valori dinamici e verranno aggiunti automaticamente alla fine della chiamata. Nel caso di una chiamata POST, è necessario:

{"id":{"param":"identifier"}}

Una volta salvate le modifiche, l’origine dati è configurata ed è pronta per essere utilizzata nei percorsi, ad esempio nelle tue condizioni o per personalizzare un’e-mail. Se la temperatura è superiore a 30°C, puoi decidere di inviare una comunicazione specifica.

Modalità di autenticazione personalizzata custom-authentication-mode

La modalità di autenticazione personalizzata viene utilizzata per l’autenticazione complessa, spesso utilizzata per chiamare protocolli di wrapping API come OAuth2 e per recuperare un token di accesso da inserire nella richiesta HTTP effettiva per l’azione.

Quando configuri l’autenticazione personalizzata, utilizza il pulsante Fai clic per controllare l’autenticazione per controllare se il payload di autenticazione personalizzata è configurato correttamente.

Quando il test ha esito positivo, il pulsante diventa verde.

Con questa modalità di autenticazione, l’esecuzione dell’azione è un processo in due fasi:

Definizione dell’endpoint da chiamare per generare il token di accesso custom-authentication-endpoint

Definizione del modo in cui il token di accesso deve essere inserito nella richiesta HTTP dell’azione custom-authentication-access-token

Il formato di questa autenticazione è:

{
    "type": "customAuthorization",
    "endpoint": "<URL of the authentication endpoint>",
    "method": "<HTTP method to call the authentication endpoint, in 'GET' or 'POST'>",
    (optional) "headers": {
        "<header name>": "<header value>",
        ...
    },
    (optional, mandatory if method is 'POST') "body": {
        "bodyType": "<'form'or 'json'>,
        "bodyParams": {
            "param1": value1,
            ...
        }
    },
    "tokenInResponse": "<'response' or json selector in format 'json://<field path to access token>'",
    "cacheDuration": {
        (optional, mutually exclusive with 'duration') "expiryInResponse": "<json selector in format 'json://<field path to expiry>'",
        (optional, mutually exclusive with 'expiryInResponse') "duration": <integer value>,
        "timeUnit": "<unit in 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'months', 'years'>"
    },
    "authorizationType": "<value in 'bearer', 'header' or 'queryParam'>",
    (optional, mandatory if authorizationType is 'header' or 'queryParam') "tokenTarget": "<name of the header or queryParam if the authorizationType is 'header' or 'queryParam'>",
}

Adesso puoi modificare la durata della cache del token per un’origine dati di autenticazione personalizzata. Di seguito è riportato un esempio di payload di autenticazione personalizzato. Durata della cache definita nel parametro cacheDuration. Tale parametro Specifica la durata di conservazione del token generato nella cache. L’unità può essere in millisecondi, secondi, minuti, ore, giorni, mesi, anni.

Ecco un esempio per il tipo di autenticazione bearer:

{
    "type": "customAuthorization",
    "endpoint": "https://<your_auth_endpoint>/epsilon/oauth2/access_token",
    "method": "POST",
    "headers": {
      "Authorization": "Basic EncodeBase64(<epsilon Client Id>:<epsilon Client Secret>)"
    },
    "body": {
      "bodyType": "form",
      "bodyParams": {
        "scope": "cn mail givenname uid employeeNumber",
        "grant_type": "password",
        "username": "<epsilon User Name>",
        "password": "<epsilon User Password>"
      }
    },
    "tokenInResponse": "json://access_token",
    "cacheDuration": {
      "duration": 5,
      "timeUnit": "minutes"
    },
  },

Autenticazione personalizzata basata su certificato certificate-credential

Per le API aziendali che applicano la verifica dell’identità basata su certificato, ad esempio Microsoft Entra ID, è possibile configurare l’autenticazione personalizzata basata su certificato aggiungendo "subType": "certificateCredential" al payload di autorizzazione personalizzato. Journey Optimizer utilizza il certificato gestito di Adobe per firmare un’asserzione client JWT e scambiarla per un token di accesso. Non è richiesto alcun segreto client.

Questa opzione aggiunge due campi obbligatori allo schema customAuthorization standard: subType e aud. Tutti gli altri campi (endpoint, method, parametri corpo, tokenInResponse) rimangono invariati. Quando subType è assente, il comportamento è identico a quello dell’autenticazione personalizzata standard, senza influire sulle configurazioni esistenti.

I campi client_assertion e client_assertion_type non vengono mai creati dall’utente. Vengono inserite automaticamente dalla piattaforma in fase di runtime, immediatamente prima della chiamata dell’endpoint del token.

Come funziona certificate-credential-how-it-works

L’autenticazione personalizzata basata su certificato implementa le credenziali client OAuth 2.0 con un’asserzione client JWT, come definito in RFC 7523, lo stesso standard supportato da Microsoft Entra ID e Okta. Al posto del segreto client, Journey Optimizer dimostra la propria identità utilizzando un JWT firmato con la chiave privata gestita di Adobe. Il provider di identità verifica la firma utilizzando il certificato pubblico di Adobe, che viene registrato una volta nel provider di identità.

Lo scambio di token segue questi passaggi:

Dettagli del certificato di Adobe certificate-credential-details

Adobe gestisce il certificato e la relativa chiave privata associata. Nella tabella seguente sono riepilogate le proprietà chiave:

Adobe ruota automaticamente il certificato 60 giorni prima della scadenza. Il certificato precedente rimane valido fino a 30 giorni prima della scadenza. I clienti non ricevono alcuna notifica. Per informazioni su come monitorare la rotazione a livello di programmazione, vedere il guardrail Rotazione certificato di seguito.

Struttura delle asserzioni JWT certificate-credential-jwt

L’asserzione del client JWT non viene creata dall’utente, ma generata e firmata automaticamente da Journey Optimizer. La struttura prevista viene fornita qui in modo che il team del provider di identità possa convalidare le attestazioni.

Intestazione:

{
  "alg": "RS256",
  "x5t": "<base64url SHA-1 thumbprint of Adobe's leaf certificate>"
}

Payload:

{
  "iss": "<client_id>",
  "sub": "<client_id>",
  "aud": "<token endpoint URL>",
  "iat": "<current unix timestamp>",
  "exp": "<iat + 600 seconds>",
  "jti": "<unique UUID per request>"
}

Si noti quanto segue:

Di seguito è riportato un esempio per il tipo di autenticazione delle credenziali del certificato, per Microsoft Entra ID:

{
  "type": "customAuthorization",
  "subType": "certificateCredential",
  "aud": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "authorizationType": "Bearer",
  "endpoint": "https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token",
  "method": "POST",
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "client_id": "<your-client-id>",
      "grant_type": "client_credentials",
      "scope": "https://api.example.com/.default"
    }
  },
  "tokenInResponse": "json://access_token"
}

Di seguito è riportato un esempio per lo stesso tipo di autenticazione delle credenziali del certificato per Okta:

{
  "type": "customAuthorization",
  "subType": "certificateCredential",
  "authorizationType": "bearer",
  "endpoint": "https://<your-okta-domain>/oauth2/v1/token",
  "aud": "https://<your-okta-domain>/oauth2/v1/token",
  "method": "POST",
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "client_id": "<your-okta-app-client-id>",
      "grant_type": "client_credentials",
      "scope": "<your-api-scope>"
    }
  },
  "tokenInResponse": "json://access_token"
}

Di seguito è riportato un esempio per il tipo di autenticazione dell’intestazione:

{
  "type": "customAuthorization",
  "endpoint": "https://myapidomain.com/v2/user/login",
  "method": "POST",
  "headers": {
    "x-retailer": "any value"
  },
  "body": {
    "bodyType": "form",
    "bodyParams": {
      "secret": "any value",
      "username": "any value"
    }
  },
  "tokenInResponse": "json://token",
  "cacheDuration": {
    "expiryInResponse": "json://expiryDuration",
    "timeUnit": "minutes"
  },
  "authorizationType": "header",
  "tokenTarget": "x-auth-token"
}

Ecco un esempio della risposta della chiamata API di accesso:

{
  "token": "xDIUssuYE9beucIE_TFOmpdheTqwzzISNKeysjeODSHUibdzN87S",
  "expiryDuration" : 5
}