Autenticazione OAuth 2

Panoramica

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 aggiungere i dettagli di autenticazione OAuth 2 alla configurazione di destinazione

Prerequisiti nel sistema

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

Alla fine di questo passaggio, dovresti avere:

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

Cosa devi fare nella Destination SDK

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.

Tipi di sovvenzione OAuth 2 supportati

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.

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:

• Supporta tutte e tre le sovvenzioni OAuth 2 tenendo conto delle eventuali varianti, ad esempio campi di dati aggiuntivi, chiamate API non standard e altro ancora.
• Supporta token di accesso con diversi valori di ciclo di vita, siano essi 90 giorni, 30 minuti o qualsiasi altro valore di ciclo di vita 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 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:

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 (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:

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 di OAuth 2 con credenziali client

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.

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 OAuth 2

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.

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

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

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

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, 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:

Accedere al token refresh

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:

Convenzioni di modellazione

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.

Passaggi successivi

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.