OAuth 2-Autorisierung

Destination SDK unterstützt mehrere Autorisierungsmethoden für Ihr Ziel. Dazu gehört die Möglichkeit, sich mithilfe des OAuth 2 Autorisierungs-Frameworks bei Ihrem Ziel zu authentifizieren.

Auf dieser Seite werden die verschiedenen OAuth 2-Autorisierungsflüsse beschrieben, die von Destination SDK unterstützt werden, und Sie erhalten Anweisungen zum Einrichten der OAuth 2-Autorisierung für Ihr Ziel.

Unterstützte Integrationstypen supported-integration-types

Die nachstehende Tabelle beschreibt ausführlich, welche Integrationstypen die auf dieser Seite beschriebenen Funktionen unterstützen.

Hinzufügen von OAuth 2-Autorisierungsdetails zur Zielkonfiguration how-to-setup

Voraussetzungen in Ihrem System prerequisites

Als ersten Schritt müssen Sie in Ihrem System eine Anwendung für Adobe Experience Platform erstellen oder anderweitig Experience Platform in Ihrem System registrieren. Das Ziel besteht darin, eine Client-ID und ein Client-Geheimnis zu generieren, die für die Authentifizierung von Experience Platform an Ihrem Ziel erforderlich sind.

Als Teil dieser Konfiguration in Ihrem System benötigen Sie die Adobe Experience Platform OAuth 2-Umleitungs-/Callback-URLs, die Sie in der folgenden Liste finden.

Am Ende dieses Schritts sollten Sie über Folgendes verfügen:

Was Sie in Destination SDK tun müssen to-do-in-destination-sdk

Um die OAuth 2-Autorisierung für Ihr Ziel in Experience Platform einzurichten, müssen Sie Ihre OAuth 2-Details zur Zielkonfiguration unter dem Parameter customerAuthenticationConfigurations hinzufügen. Siehe Kundenauthentifizierung für ausführliche Beispiele. Spezifische Anweisungen dazu, welche Felder Sie je nach OAuth 2-Autorisierungstyp zu Ihrer Konfigurationsvorlage hinzufügen müssen, finden Sie weiter unten auf dieser Seite.

Unterstützte OAuth 2-Gewährungstypen oauth2-grant-types

Experience Platform unterstützt die drei OAuth 2-Gewährungstypen in der folgenden Tabelle. Wenn Sie ein benutzerdefiniertes OAuth 2-Setup haben, kann Adobe es mithilfe von benutzerdefinierten Feldern in Ihrer Integration unterstützen. Weitere Informationen finden Sie in den Abschnitten zu den einzelnen Fördertypen.

In der obigen Tabelle sind die Felder aufgeführt, die in standardmäßigen OAuth 2-Flüssen verwendet werden. Zusätzlich zu diesen Standardfeldern können verschiedene Partnerintegrationen zusätzliche Eingaben und Ausgaben erfordern. Adobe hat ein flexibles OAuth 2-Autorisierungs-Framework für die Destination SDK entwickelt, das Varianten des obigen Standardfeldmusters handhaben kann und gleichzeitig einen Mechanismus zur automatischen Neuerstellung ungültiger Ausgaben unterstützt, wie z. B. abgelaufene Zugriffstoken.

Die Ausgabe enthält in allen Fällen ein Zugriffstoken, das von Experience Platform verwendet wird, um sich zu authentifizieren und die Autorisierung für Ihr Ziel beizubehalten.

Das System, das Adobe für die OAuth 2-Autorisierung entwickelt hat:

OAuth 2 mit Autorisierungs-Code authorization-code

Wenn Ihr Ziel einen standardmäßigen OAuth 2.0-Autorisierungs-Code-Fluss (lesen Sie dazu den Abschnitt RFC-Standardspezifikationen) oder eine Variante davon unterstützt, finden Sie unten die erforderlichen und die optionalen Felder:

Um diese Autorisierungsmethode für Ihr Ziel einzurichten, fügen Sie die folgenden Zeilen zu Ihrer Konfiguration hinzu, wenn Sie eine Zielkonfiguration erstellen:

{
//...
  "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 mit Passwortgewährung

Für die OAuth 2-Passwortgewährung (lesen Sie die RFC-Standardspezifikationen) erfordert Experience Platform den Benutzernamen und das Passwort der Benutzerin bzw. des Benutzers. Im Autorisierungsfluss tauscht Experience Platform diese Anmeldeinformationen gegen ein Zugriffstoken und optional ein Aktualisierungstoken aus.
Adobe verwendet die folgenden Standardeingaben, um die Zielkonfiguration zu vereinfachen und Werte zu überschreiben:

Um diese Autorisierungsmethode für Ihr Ziel einzurichten, fügen Sie die folgenden Zeilen zu Ihrer Konfiguration hinzu, wenn Sie eine Zielkonfiguration erstellen:

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

OAuth 2 mit Gewährung von Client-Anmeldeinformationen

Sie können ein Ziel für OAuth 2 Client-Anmeldeinformationen konfigurieren (lesen Sie den Abschnitt RFC-Standardspezifikationen) konfigurieren, das die unten aufgeführten Standardeingaben und -ausgaben unterstützt. Sie können die Werte anpassen. Siehe Anpassen der OAuth 2-Konfiguration für Details.

Um diese Autorisierungsmethode für Ihr Ziel einzurichten, fügen Sie die folgenden Zeilen zu Ihrer Konfiguration hinzu, wenn Sie eine Zielkonfiguration erstellen:

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

Anpassen der OAuth 2-Konfiguration customize-configuration

Die in den obigen Abschnitten beschriebenen Konfigurationen beschreiben standardmäßige OAuth 2-Gewährungen. Das von Adobe entworfene System bietet jedoch eine Flexibilität, sodass Sie für alle Variationen der OAuth 2-Gewährungen auch benutzerdefinierte Parameter verwenden können. Um die standardmäßigen OAuth 2-Einstellungen anzupassen, verwenden Sie die Parameter authenticationDataFields, wie in den Beispielen unten dargestellt.

Beispiel 1: Verwenden von authenticationDataFields zum Erfassen von Informationen aus der Autorisierungsantwort example-1

In diesem Beispiel verfügt eine Zielplattform über Aktualisierungstoken, die nach einer bestimmten Zeitdauer ablaufen. In diesem Fall richtet der Partner das benutzerdefinierte Feld refreshTokenExpiration ein, um das Ablaufdatum des Aktualisierungstokens aus dem Feld refresh_token_expires_in in der API-Antwort abzurufen.

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

Beispiel 2: Verwenden von authenticationDataFields, um ein spezielles Aktualisierungstoken bereitzustellen example-2

In diesem Beispiel richtet ein Partner sein Ziel ein, um ein spezielles Aktualisierungstoken bereitzustellen. Außerdem wird das Ablaufdatum für Zugriffstoken nicht in der API-Antwort zurückgegeben, sodass er einen Standardwert (in diesem Fall 3600 Sekunden) hartcodieren kann.

      "authenticationDataFields": [
        {
            "name": "refreshToken",
            "value": "special_refresh_token"
        },
        {
            "name": "expiresIn",
            "value": 3600
        }
      ]

Beispiel 3: Die Benutzenden geben die Client-ID und das Client-Geheimnis ein, wenn sie das Ziel konfigurieren example-3

In diesem Beispiel muss die Kundin oder der Kunde nicht (wie im Abschnitt Voraussetzungen in Ihrem System gezeigt) eine globale Kunden-ID und ein Kundengeheimnis erstellen, sondern die Kunden-ID, das Kundengeheimnis und die Konto-ID (die ID, die die Kundin bzw. der Kunde für die Anmeldung beim Ziel verwendet) eingeben

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

Sie können die folgenden Parameter in authenticationDataFields zum Anpassen Ihrer OAuth 2-Konfiguration verwenden:

Aktualisierung des Zugriffstokens access-token-refresh

Adobe hat ein System entwickelt, das abgelaufene Zugriffstoken aktualisiert, ohne dass die Benutzenden sich wieder bei Ihrer Plattform anmelden müssen. Das System kann ein neues Token generieren, sodass die Aktivierung an Ihr Ziel nahtlos für die Kundinnen und Kunden fortgesetzt wird.

Um die Aktualisierung des Zugriffstokens einzurichten, müssen Sie möglicherweise eine vorlagenbasierte HTTP-Anfrage konfigurieren, die es Adobe ermöglicht, mithilfe eines Aktualisierungstokens ein neues Zugriffstoken zu erhalten. Wenn das Zugriffstoken abgelaufen ist, verwendet Adobe die von Ihnen bereitgestellte vorlagenbasierte Anfrage und fügt die von Ihnen angegebenen Parameter hinzu. Verwenden Sie den Parameter accessTokenRequest zum Konfigurieren eines Aktualisierungsmechanismus für Zugriffstoken.

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

Sie können die folgenden Parameter in accessTokenRequest verwenden, um Ihren Token-Aktualisierungsprozess anzupassen:

Vorlagenkonventionen templating-conventions

Abhängig von Ihrer Autorisierungsanpassung müssen Sie möglicherweise auf Datenfelder in der Autorisierungsantwort zugreifen, wie im vorherigen Abschnitt gezeigt. Machen Sie sich dazu bitte mit der Pebble-Vorlagensprache vertraut, die von Adobe verwendet wird, und lesen Sie die unten stehenden Vorlagenkonventionen, um Ihre OAuth 2-Implementierung anzupassen.

Nächste Schritte next-steps

Durch Lesen dieses Artikels erhalten Sie jetzt Informationen zu den von Adobe Experience Platform unterstützten OAuth 2-Autorisierungsmustern und erfahren, wie Sie Ihr Ziel mit OAuth 2-Autorisierungsunterstützung konfigurieren. Als Nächstes können Sie Ihr OAuth 2-unterstütztes Ziel mithilfe von Destination SDK einrichten. Lesen Sie Verwenden von Destination SDK, um Ihr Ziel zu konfigurieren für die nächsten Schritte.