Authentification OAuth 2

Présentation

Utilisez la Destination SDK pour permettre à Adobe Experience Platform de se connecter à votre destination à l’aide du Structure d’authentification OAuth 2.

Cette page décrit les différents flux d’authentification OAuth 2 pris en charge par Destination SDK et fournit des instructions pour configurer l’authentification OAuth 2 pour votre destination.

Comment ajouter des détails d’authentification OAuth 2 à votre configuration de destination

Conditions préalables dans votre système

Pour commencer, vous devez créer une application dans votre système pour Adobe Experience Platform ou enregistrer un Experience Platform dans votre système. L’objectif est de générer un ID client et un secret client, qui sont nécessaires pour authentifier l’Experience Platform sur votre destination. Dans le cadre de cette configuration de votre système, vous avez besoin des URL de redirection/rappel OAuth 2 de Adobe Experience Platform, que vous pouvez obtenir à partir de la liste ci-dessous.

• 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

À la fin de cette étape, vous devez disposer des éléments suivants :

• un ID client ;
• un secret client ;
• URL de rappel de l’Adobe (pour l’octroi du code d’autorisation).

Ce que vous devez faire en Destination SDK

Pour configurer l’authentification OAuth 2 pour votre destination dans Experience Platform, vous devez ajouter les détails OAuth 2 à la variable configuration de destination, sous customerAuthenticationConfigurations en utilisant le paramètre platform.adobe.io/data/core/activation/authoring/destinations Point d’entrée API. Voir exemple de configuration. Vous trouverez ci-dessous des instructions spécifiques sur les champs à ajouter à votre modèle de configuration, en fonction de votre type d’octroi d’authentification OAuth 2.

Types d’octroi OAuth 2 pris en charge

Experience Platform prend en charge les trois types de subventions OAuth 2 dans le tableau ci-dessous. Si vous disposez d’une configuration OAuth 2 personnalisée, Adobe peut la prendre en charge à l’aide de champs personnalisés de votre intégration. Pour plus d’informations, reportez-vous aux sections de chaque type d’octroi.

Le tableau ci-dessus répertorie les champs utilisés dans les flux OAuth 2 standard. Outre ces champs standard, diverses intégrations de partenaires peuvent nécessiter des entrées et des sorties supplémentaires. Adobe a conçu un framework d’authentification/d’autorisation OAuth 2 flexible pour la Destination SDK qui peut gérer des variations du modèle de champs standard ci-dessus, tout en prenant en charge un mécanisme pour générer automatiquement des sorties non valides, telles que des jetons d’accès expirés.

Dans tous les cas, la sortie comprend un jeton d’accès, utilisé par l’Experience Platform pour authentifier et maintenir l’authentification auprès de votre destination.

Le système que Adobe a conçu pour l’authentification OAuth 2 :

• Prend en charge les trois autorisations OAuth 2 tout en tenant compte des variations qu’elles comportent, telles que les champs de données supplémentaires, les appels d’API non standard, etc.
• Prend en charge les jetons d’accès avec des valeurs de durée de vie variables, qu’il s’agisse de 90 jours, 30 minutes ou de toute autre valeur de durée de vie que vous spécifiez.
• Prend en charge les flux d’autorisation OAuth 2 avec ou sans jetons d’actualisation.

OAuth 2 avec code d’autorisation

Si votre destination prend en charge un flux de code d’autorisation OAuth 2.0 standard (lisez la section Spécifications des normes RFC) ou une variante de celle-ci, consultez les champs obligatoires et facultatifs ci-dessous :

Pour configurer cette méthode d’authentification pour votre destination, ajoutez les lignes suivantes à votre configuration, dans la section /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 avec octroi de mot de passe

Pour l’octroi du mot de passe OAuth 2 (lisez la section Spécifications des normes RFC), Experience Platform requiert le nom d’utilisateur et le mot de passe de l’utilisateur. Dans le flux d’authentification, l’Experience Platform échange ces informations d’identification pour un jeton d’accès et, éventuellement, un jeton d’actualisation.
Adobe utilise les entrées standard ci-dessous pour simplifier la configuration de destination, avec la possibilité de remplacer les valeurs :

Pour configurer cette méthode d’authentification pour votre destination, ajoutez les lignes suivantes à votre configuration, dans la section /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"]
    }
  ]

OAuth 2 avec octroi des informations d’identification du client

Vous pouvez configurer des informations d’identification du client OAuth 2 (lisez la section Spécifications des normes RFC), qui prend en charge les entrées et sorties standard répertoriées ci-dessous. Vous pouvez personnaliser les valeurs. Voir Personnalisation de votre configuration OAuth 2 pour plus d’informations.

Pour configurer cette méthode d’authentification pour votre destination, ajoutez les lignes suivantes à votre configuration, dans la section /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"]
    }
  ]
//...
}

Personnalisation de votre configuration OAuth 2

Les configurations décrites dans les sections ci-dessus décrivent les subventions OAuth 2 standard. Cependant, le système conçu par Adobe offre une certaine flexibilité afin que vous puissiez utiliser des paramètres personnalisés pour n’importe quelle variante de l’octroi OAuth 2. Pour personnaliser les paramètres OAuth 2 standard, utilisez le authenticationDataFields , comme illustré dans les exemples ci-dessous.

Exemple 1 : Utilisation authenticationDataFields pour capturer les informations provenant de la réponse d’authentification

Dans cet exemple, une plateforme de destination dispose de jetons d’actualisation qui expirent après un certain temps. Dans ce cas, le partenaire configure la variable refreshTokenExpiration champ personnalisé pour obtenir l’expiration du jeton d’actualisation à partir de la propriété refresh_token_expires_in dans la réponse de l’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"
            }
         ]
      }
   ]
}

Exemple 2 : Utilisation authenticationDataFields pour fournir un jeton d’actualisation spécial

Dans cet exemple, un partenaire configure sa destination pour fournir un jeton d’actualisation spécial. De plus, la date d’expiration des jetons d’accès n’est pas renvoyée dans la réponse de l’API. Ils peuvent donc coder en dur une valeur par défaut, ici 3 600 secondes.

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

Exemple 3 : L’utilisateur saisit l’ID client et le secret client lors de la configuration de la destination.

Dans cet exemple, au lieu de créer un ID client global et un secret client comme illustré dans la section Conditions préalables dans votre système, le client doit saisir l’ID du client, le secret client et l’ID de compte (l’ID que le client utilise pour se connecter à la destination).

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

Vous pouvez utiliser les paramètres suivants dans authenticationDataFields pour personnaliser votre configuration OAuth 2 :

Actualisation du jeton d’accès

Adobe a conçu un système qui actualise les jetons d’accès expirés sans que l’utilisateur doive se reconnecter à votre plateforme. Le système peut générer un nouveau jeton afin que l’activation vers votre destination se poursuive de manière transparente pour le client.

Pour configurer l’actualisation du jeton d’accès, vous devrez peut-être configurer une requête HTTP modélisée qui permet à l’Adobe d’obtenir un nouveau jeton d’accès à l’aide d’un jeton d’actualisation. Si le jeton d’accès a expiré, Adobe accepte la demande modélisée que vous avez fournie, en ajoutant les paramètres que vous avez fournis. Utilisez la variable accessTokenRequest pour configurer un mécanisme d’actualisation du jeton d’accès.

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

Vous pouvez utiliser les paramètres suivants dans accessTokenRequest pour personnaliser votre processus d’actualisation de jeton :

Conventions relatives aux modèles

Selon la personnalisation de votre authentification, vous devrez peut-être accéder aux champs de données dans la réponse d’authentification, comme indiqué dans la section précédente. Pour ce faire, familiarisez-vous avec le Langage de modèle de bloc utilisé par Adobe et reportez-vous aux conventions de création de modèles ci-dessous pour personnaliser votre implémentation OAuth 2.

Étapes suivantes

En lisant cet article, vous comprenez maintenant les modèles d’authentification OAuth 2 pris en charge par Adobe Experience Platform et vous savez comment configurer votre destination avec la prise en charge de l’authentification OAuth 2. Ensuite, vous pouvez configurer votre destination OAuth 2 prise en charge à l’aide de Destination SDK. Lecture Utiliser la Destination SDK pour configurer votre destination pour les étapes suivantes.

Ressources Business.Adobe.com