Autenticazione OAuth 2

Panoramica

Utilizza Destination SDK per consentire a Adobe Experience Platform di connettersi alla destinazione utilizzando Framework di autenticazione 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.

Aggiungere dettagli di autenticazione OAuth 2 alla configurazione di destinazione

Prerequisiti nel sistema

Come primo passo, devi creare un’app per Adobe Experience Platform o registrare in altro modo un Experience Platform. L’obiettivo è generare un ID client e un segreto client, necessari per autenticare l’Experience Platform nella destinazione. Come parte di questa configurazione nel tuo sistema, devi disporre 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

Al termine di questo passaggio, dovresti disporre di:

• Un ID cliente;
• Un segreto cliente;
• URL di callback di Adobe (per la concessione del codice di autorizzazione).

Cosa devi fare nella Destination SDK

Per impostare l’autenticazione OAuth 2 per la destinazione in Experience Platform, è necessario aggiungere i dettagli OAuth 2 alla configurazione di destinazione, sotto il customerAuthenticationConfigurations , utilizzando il platform.adobe.io/data/core/activation/authoring/destinations Endpoint API. Consulta la configurazione di esempio. Di seguito sono riportate istruzioni specifiche sui campi da aggiungere al modello di configurazione, a seconda del tipo di concessione di autenticazione OAuth 2.

Tipi di concessione OAuth 2 supportati

L’Experience Platform supporta i tre tipi di sovvenzione OAuth 2 riportati nella tabella seguente. Se disponi di una configurazione OAuth 2 personalizzata, Adobe è in grado di supportarla con l’aiuto di campi personalizzati nell’integrazione. Per ulteriori informazioni, consulta le sezioni per ogni tipo di sovvenzione.

La tabella precedente elenca i campi utilizzati nei flussi standard OAuth 2. Oltre a questi campi standard, varie integrazioni di partner possono richiedere input e output aggiuntivi. Adobe ha progettato un framework flessibile di autenticazione/autorizzazione OAuth 2 per Destination SDK che può gestire le varianti al modello di campi standard di cui sopra, supportando al contempo un meccanismo per rigenerare automaticamente gli output non validi, come i token di accesso scaduti.

L’output include sempre 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:

• Supporta tutte e tre le sovvenzioni OAuth 2 tenendo conto di eventuali varianti di esse, come campi di dati aggiuntivi, chiamate API non standard e altro ancora.
• Supporta i token di accesso con valori di durata variabili, che si tratti di 90 giorni, 30 minuti o qualsiasi altro valore di durata specificato.
• Supporta i flussi di autorizzazione OAuth 2 con o senza token di aggiornamento.

OAuth 2 con codice di autorizzazione

Se la destinazione supporta un flusso standard del codice di autorizzazione OAuth 2.0 (leggi la Specifiche degli standard RFC) o una sua variante, consulta i campi obbligatori e facoltativi seguenti:

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"]
    }
  ]
//...
}

OAuth 2 con concessione password

Per la concessione della password OAuth 2 (leggi 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, per un token di aggiornamento.
Adobe utilizza gli input standard riportati di seguito per semplificare la configurazione di destinazione, con la possibilità di ignorare i valori:

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"]
    }
  ]

Concessione OAuth 2 con credenziali client

È possibile configurare le credenziali di un client OAuth 2 (leggere la Specifiche degli standard RFC), che supporta gli ingressi e le uscite standard elencati di seguito. Puoi personalizzare i valori. Consulta Personalizzare la configurazione di OAuth 2 per i dettagli.

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"]
    }
  ]
//...
}

Personalizzare la configurazione di OAuth 2

Le configurazioni descritte nelle sezioni precedenti descrivono le sovvenzioni standard OAuth 2. Tuttavia, il sistema progettato da Adobe offre flessibilità che consente di utilizzare parametri personalizzati per qualsiasi variante nella sovvenzione OAuth 2. Per personalizzare le impostazioni standard di OAuth 2, utilizzare authenticationDataFields come mostrato negli esempi di seguito.

Esempio 1: utilizzo authenticationDataFields per acquisire informazioni provenienti dalla risposta di autenticazione

In 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 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"
            }
         ]
      }
   ]
}

Esempio 2: utilizzo authenticationDataFields per fornire un token di aggiornamento speciale

In questo esempio, un partner imposta la propria destinazione in modo da fornire un token di aggiornamento speciale. Inoltre, la data di scadenza per i 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
        }
      ]

Esempio 3: l’utente immette l’ID client e il segreto client quando configura la destinazione

In questo esempio, invece di creare un ID client globale e un segreto client come mostrato nella sezione Prerequisiti nel sistema, al cliente viene richiesto di immettere 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:

Aggiornamento del token di accesso

Adobe ha progettato un sistema che aggiorna i token di accesso scaduti senza richiedere all’utente di accedere nuovamente alla piattaforma. Il sistema è in grado di generare un nuovo token in modo che l’attivazione nella destinazione continui senza problemi per il cliente.

Per impostare l’aggiornamento del token di accesso, potrebbe essere necessario configurare una richiesta HTTP con modello 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 basata su modelli fornita dall’utente, aggiungendo i parametri forniti. Utilizza il accessTokenRequest parametro 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:

Convenzioni di modelli

A seconda della personalizzazione dell’autenticazione, potrebbe essere necessario accedere ai campi dati nella risposta di autenticazione, come illustrato nella sezione precedente. Per farlo, impara a conoscere Linguaggio per modelli di ciottoli utilizzato da Adobe e fai riferimento alle convenzioni di modelli riportate di seguito per personalizzare l’implementazione di OAuth 2.

Passaggi successivi

Leggendo questo articolo, ora hai una conoscenza dei modelli di autenticazione OAuth 2 supportati da Adobe Experience Platform e sai come configurare la tua destinazione con il supporto per l’autenticazione di OAuth 2. Successivamente, puoi impostare la destinazione supportata da OAuth 2 tramite Destination SDK. Letto Utilizza Destination SDK per configurare la destinazione per i passaggi successivi.

Risorse Business.Adobe.com