Utilizza la Destination SDK per consentire a Adobe Experience Platform di connettersi alla tua destinazione utilizzando il Framework di autenticazione di OAuth 2.
Questa pagina descrive i vari flussi di autenticazione OAuth 2 supportati da Destination SDK e fornisce istruzioni per configurare l’autenticazione OAuth 2 per la destinazione.
Come primo passo, devi creare un’app nel tuo sistema per Adobe Experience Platform o registrare in altro modo l’Experience Platform nel tuo sistema. L'obiettivo è quello di generare un ID client e un segreto client, necessari per autenticare l'Experience Platform nella destinazione. Come parte di questa configurazione del sistema, hai bisogno degli URL di reindirizzamento/callback di Adobe Experience Platform OAuth 2, che puoi ottenere dall’elenco seguente.
https://platform-va7.adobe.io/data/core/activation/oauth/api/v1/callback
https://platform-nld2.adobe.io/data/core/activation/oauth/api/v1/callback
https://platform-aus5.adobe.io/data/core/activation/oauth/api/v1/callback
Il passaggio per registrare un URL di reindirizzamento/callback per Adobe Experience Platform nel sistema è necessario solo per il OAuth 2 con codice di autorizzazione tipo di sovvenzione. Per gli altri due tipi di sovvenzione supportati (password e credenziali client), puoi saltare questo passaggio.
Alla fine di questo passaggio, dovresti avere:
Per configurare l’autenticazione OAuth 2 per la destinazione nell’Experience Platform, devi aggiungere i dettagli OAuth 2 al configurazione di destinazione, customerAuthenticationConfigurations
utilizzando platform.adobe.io/data/core/activation/authoring/destinations
Endpoint API. Consulta la sezione configurazione di esempio. Istruzioni specifiche su quali campi devi aggiungere al modello di configurazione, a seconda del tipo di concessione di autenticazione OAuth 2, sono più avanti in questa pagina.
L’Experience Platform supporta i tre tipi di sovvenzione OAuth 2 nella tabella seguente. Se disponi di una configurazione OAuth 2 personalizzata, Adobe è in grado di supportarla con l’aiuto di campi personalizzati nella tua integrazione. Per ulteriori informazioni, consulta le sezioni relative a ciascun tipo di sovvenzione.
Sovvenzione OAuth 2 | Ingressi | Uscite |
---|---|---|
Codice di autorizzazione |
|
|
Password |
|
|
Credenziali client |
|
|
Nella tabella riportata sopra sono elencati i campi utilizzati nei flussi OAuth 2 standard. Oltre a questi campi standard, diverse integrazioni dei partner possono richiedere ingressi e uscite aggiuntive. Adobe ha progettato un framework flessibile di autenticazione/autorizzazione OAuth 2 per Destination SDK che può gestire le varianti al pattern di campi standard di cui sopra, mentre supporta un meccanismo per rigenerare automaticamente le uscite non valide, ad esempio i token di accesso scaduti.
L'output in tutti i casi include un token di accesso, utilizzato da Experience Platform per autenticare e mantenere l'autenticazione nella destinazione.
Il sistema progettato da Adobe per l’autenticazione OAuth 2:
Se la destinazione supporta un flusso di codice di autorizzazione OAuth 2.0 standard (consulta la sezione Specifiche degli standard RFC) o una sua variazione, consulta i campi obbligatori e facoltativi di seguito:
Sovvenzione OAuth 2 | Ingressi | Uscite |
---|---|---|
Codice di autorizzazione |
|
|
Per impostare questo metodo di autenticazione per la destinazione, aggiungi le seguenti righe alla configurazione, nel /destinations
endpoint:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_AUTHORIZATION_CODE",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"authorizationUrl": "https://www.moviestar.com/dialog/OAuth",
"refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
//...
}
Parametro | Tipo | Descrizione |
---|---|---|
authType |
Stringa | Usa "OAUTH2". |
grant |
Stringa | Utilizzare "OAUTH2_AUTHORIZATION_CODE". |
accessTokenUrl |
Stringa | L’URL sul tuo lato, che rilascia token di accesso e, facoltativamente, aggiorna i token. |
authorizationUrl |
Stringa | L’URL del server di autorizzazione, in cui l’utente viene reindirizzato per accedere all’applicazione. |
refreshTokenUrl |
Stringa | Facoltativo. L’URL sul tuo lato, che causa problemi con i token di aggiornamento. Spesso, il refreshTokenUrl è uguale a accessTokenUrl . |
clientId |
Stringa | L'ID client che il sistema assegna a Adobe Experience Platform. |
clientSecret |
Stringa | Il segreto client assegnato dal sistema a Adobe Experience Platform. |
scope |
Elenco delle stringhe | Facoltativo. Imposta l’ambito di ciò che il token di accesso consente ad Experience Platform di eseguire sulle risorse. Esempio: "leggi, scrivi". |
Per la concessione della password OAuth 2 (leggere il Specifiche degli standard RFC), Experience Platform richiede il nome utente e la password dell’utente. Nel flusso di autenticazione, Experience Platform scambia queste credenziali per un token di accesso e, facoltativamente, un token di aggiornamento.
L'Adobe utilizza gli input standard riportati di seguito per semplificare la configurazione della destinazione, con la possibilità di ignorare i valori:
Sovvenzione OAuth 2 | Ingressi | Uscite |
---|---|---|
Password |
|
|
Non è necessario aggiungere parametri per username
e password
nella configurazione seguente. Quando aggiungi "grant": "OAUTH2_PASSWORD"
nella configurazione di destinazione, il sistema richiederà all'utente di fornire un nome utente e una password nell'interfaccia utente di Experience Platform, quando si autentica nella tua destinazione.
Per impostare questo metodo di autenticazione per la destinazione, aggiungi le seguenti righe alla configurazione, nel /destinations
endpoint:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_PASSWORD",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
Parametro | Tipo | Descrizione |
---|---|---|
authType |
Stringa | Usa "OAUTH2". |
grant |
Stringa | Utilizzare "OAUTH2_PASSWORD". |
accessTokenUrl |
Stringa | L’URL sul tuo lato, che rilascia token di accesso e, facoltativamente, aggiorna i token. |
clientId |
Stringa | L'ID client che il sistema assegna a Adobe Experience Platform. |
clientSecret |
Stringa | Il segreto client assegnato dal sistema a Adobe Experience Platform. |
scope |
Elenco delle stringhe | Facoltativo. Imposta l’ambito di ciò che il token di accesso consente ad Experience Platform di eseguire sulle risorse. Esempio: "leggi, scrivi". |
Puoi configurare le credenziali client OAuth 2 (leggi la sezione Specifiche degli standard RFC), che supporta gli ingressi e le uscite standard elencati di seguito. Puoi personalizzare i valori. Vedi Personalizzare la configurazione OAuth 2 per i dettagli.
Sovvenzione OAuth 2 | Ingressi | Uscite |
---|---|---|
Credenziali client |
|
|
Per impostare questo metodo di autenticazione per la destinazione, aggiungi le seguenti righe alla configurazione, nel /destinations
endpoint:
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_CLIENT_CREDENTIALS",
"accessTokenUrl": "https://api.moviestar.com/OAuth/access_token",
"refreshTokenUrl": "https://api.moviestar.com/OAuth/refresh_token",
"clientId": "Experience-Platform-client-id",
"clientSecret": "Experience-Platform-client-secret",
"scope": ["read", "write"]
}
]
//...
}
Parametro | Tipo | Descrizione |
---|---|---|
authType |
Stringa | Usa "OAUTH2". |
grant |
Stringa | Utilizzare "OAUTH2_CLIENT_CREDENTIALS". |
accessTokenUrl |
Stringa | L’URL del server di autorizzazione che rilascia un token di accesso e un token di aggiornamento facoltativo. |
refreshTokenUrl |
Stringa | Facoltativo. L’URL sul tuo lato, che causa problemi con i token di aggiornamento. Spesso, il refreshTokenUrl è uguale a accessTokenUrl . |
clientId |
Stringa | L'ID client che il sistema assegna a Adobe Experience Platform. |
clientSecret |
Stringa | Il segreto client assegnato dal sistema a Adobe Experience Platform. |
scope |
Elenco delle stringhe | Facoltativo. Imposta l’ambito di ciò che il token di accesso consente ad Experience Platform di eseguire sulle risorse. Esempio: "leggi, scrivi". |
Le configurazioni descritte nelle sezioni sopra descrivono le sovvenzioni standard OAuth 2. Tuttavia, il sistema progettato da Adobe offre flessibilità e consente di utilizzare parametri personalizzati per qualsiasi variante della sovvenzione OAuth 2. Per personalizzare le impostazioni standard di OAuth 2, utilizza il authenticationDataFields
, come illustrato negli esempi seguenti.
authenticationDataFields
per acquisire informazioni provenienti dalla risposta di autenticazioneIn questo esempio, una piattaforma di destinazione dispone di token di aggiornamento che scadono dopo un certo periodo di tempo. In questo caso, il partner imposta il refreshTokenExpiration
campo personalizzato per ottenere la scadenza del token di aggiornamento dal refresh_token_expires_in
nella risposta API.
{
"customerAuthenticationConfigurations":[
{
"authType":"OAUTH2",
"options":{
},
"grant":"OAUTH2_AUTHORIZATION_CODE",
"accessTokenUrl":"https://api.moviestar.com/OAuth/access_token",
"authorizationUrl":"https://api.moviestar.com/OAuth/authorization",
"scope":[
"read",
"write",
"delete"
],
"refreshTokenUrl":"https://api.moviestar.com/OAuth/accessToken",
"clientSecret":"client-secret-here",
"authenticationDataFields":[
{
"name":"refreshTokenExpiration",
"title":"Refresh Token Expires In",
"description":"Time in seconds when the refresh token will expire",
"type":"string",
"isRequired":false,
"source":"CUSTOMER",
"authenticationResponsePath":"refresh_token_expires_in"
}
]
}
]
}
authenticationDataFields
per fornire un token di aggiornamento specialeIn questo esempio, un partner imposta la propria destinazione per fornire un token di aggiornamento speciale. Inoltre, la data di scadenza dei token di accesso non viene restituita nella risposta API, in modo che possano codificare un valore predefinito, in questo caso 3600 secondi.
"authenticationDataFields": [
{
"name": "refreshToken",
"value": "special_refresh_token"
},
{
"name": "expiresIn",
"value": 3600
}
]
In questo esempio, invece di creare un ID client globale e un segreto client come mostrato nella sezione . Prerequisiti nel sistema, il cliente deve inserire l’ID client, il segreto client e l’ID account (l’ID che il cliente utilizza per accedere alla destinazione)
{
//...
"customerAuthenticationConfigurations": [
{
"authType": "OAUTH2",
"grant": "OAUTH2_CLIENT_CREDENTIALS",
"authenticationDataFields": [
{
"name": "clientId",
"title": "Client ID",
"description": "Client ID",
"type": "string",
"isRequired": true,
"source": "CUSTOMER"
},
{
"name": "clientSecret",
"title": "Client Secret",
"description": "Client Secret",
"type": "string",
"isRequired": true,
"format": "password",
"source": "CUSTOMER"
},
{
"name": "moviestarId",
"title": "Moviestar ID",
"description": "Moviestar ID",
"type": "string",
"isRequired": true,
"source": "CUSTOMER"
}
],
"accessTokenRequest": {
"destinationServerType": "URL_BASED",
"urlBasedDestination": {
"url": {
"templatingStrategy": "PEBBLE_V1",
"value": "https://{{ authData.moviestarId }}.yourdestination.com/identity/oauth/token"
}
},
"httpTemplate": {
"requestBody": {
"templatingStrategy": "PEBBLE_V1",
"value": "{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
},
"httpMethod": "POST",
"contentType": "application/x-www-form-urlencoded"
},
"responseFields": [
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.access_token }}",
"name": "accessToken"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.scope }}",
"name": "scope"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.token_type }}",
"name": "tokenType"
},
{
"templatingStrategy": "PEBBLE_V1",
"value": "{{ response.body.expires_in }}",
"name": "expiresIn"
}
]
}
}
]
//...
}
Puoi utilizzare i seguenti parametri in authenticationDataFields
per personalizzare la configurazione OAuth 2:
Parametro | Tipo | Descrizione |
---|---|---|
authenticationDataFields.name |
Stringa | Nome del campo personalizzato. |
authenticationDataFields.title |
Stringa | Titolo che è possibile specificare per il campo personalizzato. |
authenticationDataFields.description |
Stringa | Descrizione del campo dati personalizzato configurato. |
authenticationDataFields.type |
Stringa | Definisce il tipo di campo dati personalizzato. Valori accettati: string , boolean , integer |
authenticationDataFields.isRequired |
Booleano | Specifica se il campo dati personalizzato è richiesto nel flusso di autenticazione. |
authenticationDataFields.format |
Stringa | Quando selezioni "format":"password" , Adobe crittografa il valore del campo dati di autenticazione . Quando utilizzato con "fieldType": "CUSTOMER" , nasconde anche l’input nell’interfaccia utente quando l’utente digita nel campo . |
authenticationDataFields.fieldType |
Stringa | Indica se l’input proviene dal partner (tu) o dall’utente, quando configura la destinazione nell’Experience Platform. |
authenticationDataFields.value |
Stringa. Booleano. Intero | Valore del campo dati personalizzato. Il valore corrisponde al tipo scelto da authenticationDataFields.type . |
authenticationDataFields.authenticationResponsePath |
Stringa | Indica il campo dal percorso di risposta API a cui si sta facendo riferimento. |
Adobe ha progettato un sistema che aggiorna i token di accesso scaduti senza richiedere all’utente di effettuare nuovamente l’accesso alla piattaforma. Il sistema è in grado di generare un nuovo token in modo che l’attivazione alla destinazione continui senza soluzione di continuità per il cliente.
Per impostare l’aggiornamento del token di accesso, potrebbe essere necessario configurare una richiesta HTTP modellata che consenta ad Adobe di ottenere un nuovo token di accesso, utilizzando un token di aggiornamento. Se il token di accesso è scaduto, Adobe accetta la richiesta temporanea fornita dall’utente, aggiungendo i parametri forniti. Utilizza la accessTokenRequest
per configurare un meccanismo di aggiornamento del token di accesso.
{
"customerAuthenticationConfigurations":[
{
"authType":"OAUTH2",
"grant":"OAUTH2_CLIENT_CREDENTIALS",
"accessTokenRequest":{
"destinationServerType":"URL_BASED",
"urlBasedDestination":{
"url":{
"templatingStrategy":"PEBBLE_V1",
"value":"https://{{authData.customerId}}.yourdestination.com/identity/oauth/token"
}
},
"httpTemplate":{
"requestBody":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ formUrlEncode('grant_type', 'client_credentials', 'client_id', authData.clientId, 'client_secret', authData.clientSecret) | raw }}"
},
"httpMethod":"POST",
"contentType":"application/x-www-form-urlencoded",
"headers":[
]
},
"responseFields":[
{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.body.expires_in }}",
"name":"expiresIn"
},
{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.body.access_token }}",
"name":"accessToken"
}
],
"validations":[
{
"name":"access_token validation",
"actualValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{response.body.access_token is empty }}"
},
"expectedValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"false"
}
},
{
"name":"response status",
"actualValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"{{ response.status }}"
},
"expectedValue":{
"templatingStrategy":"PEBBLE_V1",
"value":"200"
}
}
]
}
}
]
}
Puoi utilizzare i seguenti parametri in accessTokenRequest
per personalizzare il processo di aggiornamento del token:
Parametro | Tipo | Descrizione |
---|---|---|
accessTokenRequest.destinationServerType |
Stringa | Seleziona URL_BASED . |
accessTokenRequest.urlBasedDestination.url.templatingStrategy |
Stringa |
|
accessTokenRequest.urlBasedDestination.url.value |
Stringa | URL in cui Experience Platform richiede il token di accesso. |
accessTokenRequest.httpTemplate.requestBody.templatingStrategy |
Stringa |
|
accessTokenRequest.httpTemplate.requestBody.value |
Stringa | Utilizza il linguaggio dei modelli per personalizzare i campi nella richiesta HTTP all’endpoint del token di accesso. Per informazioni su come utilizzare i modelli per personalizzare i campi, consulta convenzioni di modellazione sezione . |
accessTokenRequest.httpTemplate.httpMethod |
Stringa | Specifica il metodo HTTP utilizzato per chiamare l'endpoint del token di accesso. Nella maggior parte dei casi, questo valore è POST . |
accessTokenRequest.httpTemplate.contentType |
Stringa | Specifica il tipo di contenuto della chiamata HTTP all'endpoint del token di accesso. Ad esempio: application/x-www-form-urlencoded o application/json . |
accessTokenRequest.httpTemplate.headers |
Stringa | Specifica se è necessario aggiungere intestazioni alla chiamata HTTP all'endpoint del token di accesso. |
accessTokenRequest.responseFields.templatingStrategy |
Stringa |
|
accessTokenRequest.responseFields.value |
Stringa | Utilizza il linguaggio dei modelli per accedere ai campi della risposta HTTP dall’endpoint del token di accesso. Per informazioni su come utilizzare i modelli per personalizzare i campi, consulta convenzioni di modellazione sezione . |
accessTokenRequest.validations.name |
Stringa | Indica il nome fornito per la convalida. |
accessTokenRequest.validations.actualValue.templatingStrategy |
Stringa |
|
accessTokenRequest.validations.actualValue.value |
Stringa | Utilizza il linguaggio dei modelli per accedere ai campi nella risposta HTTP. Per informazioni su come utilizzare i modelli per personalizzare i campi, consulta convenzioni di modellazione sezione . |
accessTokenRequest.validations.expectedValue.templatingStrategy |
Stringa |
|
accessTokenRequest.validations.expectedValue.value |
Stringa | Utilizza il linguaggio dei modelli per accedere ai campi nella risposta HTTP. Per informazioni su come utilizzare i modelli per personalizzare i campi, consulta convenzioni di modellazione sezione . |
A seconda della personalizzazione dell’autenticazione, potrebbe essere necessario accedere ai campi di dati nella risposta all’autenticazione, come illustrato nella sezione precedente. Per farlo, ti preghiamo di familiarizzare con il Linguaggio di template di pallina utilizzato dall’Adobe e fai riferimento alle convenzioni di modello riportate di seguito per personalizzare l’implementazione di OAuth 2.
Prefisso | Descrizione | Esempio |
---|---|---|
authData | Accedi al valore di qualsiasi campo dati partner o cliente. | {{ authData.accessToken }} |
response.body | corpo di risposta HTTP | {{ response.body.access_token }} |
response.status | Stato della risposta HTTP | {{ response.status }} |
response.headers | Intestazioni di risposta HTTP | {{ response.headers.server[0] }} |
userContext | Accedere alle informazioni sul tentativo di autenticazione corrente |
|
Leggendo questo articolo, ora conosci i pattern di autenticazione OAuth 2 supportati da Adobe Experience Platform e sai come configurare la destinazione con il supporto di autenticazione OAuth 2. Successivamente, puoi impostare la destinazione supportata OAuth 2 utilizzando Destination SDK. Leggi Utilizza Destination SDK per configurare la destinazione per i passaggi successivi.