Configurer l’authentification pour un connecteur SDK de diffusion en continu
L’authentification est requise pour tous les connecteurs créés avec la diffusion en continu de SDK. Avant d’envoyer ou de libérer un connecteur, configurez un mécanisme d’authentification pris en charge :
Configurez le mécanisme correspondant au modèle d’intégration de votre connecteur.
Avant de commencer
Assurez-vous que vous disposez des éléments suivants :
- Implémentation du connecteur Streaming SDK terminée.
- Point d’entrée de l’API d’ingestion en flux continu intermédiaire ou test.
- Testez l’organisation Adobe et le sandbox.
- Une payload d’événement de test.
- Plan de stockage et de rotation sécurisés des informations d’identification.
- Un moyen de capturer les détails de requête et de réponse sans exposer de secrets.
Exigences OAuth supplémentaires
Si vous utilisez OAuth 2.0, assurez-vous que vous disposez des éléments suivants :
- Accès à Adobe Developer Console.
- API ou profil de produit requis pour le connecteur.
- Identifiant client et secret client pour les informations d’identification sélectionnées.
- Portées requises.
- Le point d’entrée de flux et de jeton OAuth requis par le connecteur.
Pour le type d’informations d’identification Adobe approprié et les détails d’implémentation, voir :
Autres exigences relatives à HMAC
Si vous utilisez HMAC, assurez-vous que vous disposez des éléments suivants :
- Secret partagé configuré pour le webhook ou le connecteur.
- Emplacement sécurisé pour le stockage du secret.
- Code qui peut calculer une signature HMAC-SHA256.
- Corps exact de l’événement sérialisé qui sera envoyé à Adobe.
- Procédure de test pour les secrets valides, non valides, manquants et pivotés.
Configuration d’OAuth 2.0
1. Création ou sélection d’informations d’identification Adobe
Tout d’abord, vous devez créer ou sélectionner les informations d’identification Adobe Developer Console requises par votre connecteur.
Configurer :
- Type d’informations d’identification.
- L’API ou le profil de produit Adobe requis.
- Portées requises.
- Paramètres de redirection ou de consentement, le cas échéant, pour le flux OAuth sélectionné.
N’utilisez pas un type d’informations d’identification non pris en charge par le modèle d’intégration du connecteur.
2. Stockez la configuration OAuth en toute sécurité.
Stockez les valeurs suivantes en toute sécurité :
- Identifiant du client.
- Secret client.
- Portées requises.
- Point d’entrée du jeton.
- Toute valeur de client, d’organisation ou d’environnement spécifique au connecteur.
Ne validez pas les secrets client dans le contrôle de code source et ne les incluez pas dans les journaux, les messages d’erreur, les captures d’écran ou les résultats de test.
3. Ajouter la configuration OAuth à votre connecteur
Stockez les valeurs de configuration OAuth dans la configuration ou le service de votre connecteur. La diffusion en continu de SDK ne définit pas de champ de spécification de connexion pour cette étape d’authentification, car elle régit la manière dont votre connecteur appelle l’API d’ingestion en flux continu, et non la manière dont Experience Platform se connecte à votre source.
La configuration de votre connecteur doit inclure les éléments suivants :
- Type d’authentification.
- Identifiant du client.
- Secret client.
- Portées.
- Point d’entrée du jeton.
- Toute valeur d’organisation ou de client supplémentaire requise par votre type d’informations d’identification.
4. Obtention d’un jeton d’accès
Mettez en œuvre le flux OAuth documenté pour votre type d’informations d’identification.
Le connecteur doit :
- Authentifiez-vous à l’aide des informations d’identification OAuth configurées.
- Demandez les portées requises par l’intégration de Streaming SDK.
- Stockez le jeton d’accès en mémoire ou dans un autre emplacement sécurisé.
- Actualisez ou réacquérez le jeton en fonction de sa durée de vie.
- Évitez de consigner le jeton ou le secret client.
5. Ajouter le jeton d’accès aux requêtes
Incluez le jeton d’accès en tant que jeton porteur sur les requêtes envoyées par le connecteur :
Authorization: Bearer {ACCESS_TOKEN}
Utilisez HTTPS pour toutes les requêtes.
6. Gérer les échecs de jeton
Le connecteur doit détecter et gérer les échecs d’authentification, notamment :
- Jetons d’accès manquants.
- Jetons d’accès expirés.
- Informations d’identification client non valides.
- Portées insuffisantes.
- Informations d’identification révoquées ou désactivées.
Lorsqu’un jeton expire, obtenez un nouveau jeton à l’aide du flux OAuth documenté et réessayez uniquement lorsque l’opération peut être réexécutée en toute sécurité.
Configuration de l’authentification basée sur HMAC
1. Configurer le secret partagé
Créez ou obtenez le secret partagé requis par le connecteur et configurez-le dans la configuration du connecteur ou du webhook.
Le secret doit être :
- Stocké en toute sécurité.
- Disponible pour le code de signature à l’exécution.
- Exclus du contrôle de code source et des journaux.
- Pivotement selon votre politique de sécurité.
2. Sérialiser l’événement
Sérialisez l’événement avant de calculer la signature.
La signature doit être calculée à partir du même message sérialisé que le connecteur envoie dans le corps de la requête.
serializedMessage = serialize(event)
Ne pas calculer la signature à partir d’une représentation de l’événement et envoyer une autre représentation. Les modifications apportées aux espaces blancs, à l’ordre des propriétés, à l’échappement, au codage ou aux fins de ligne peuvent entraîner l’échec de la validation de la signature.
3. Calculer la signature HMAC-SHA256
Calculez la valeur HMAC-SHA256 à l’aide de :
- Clé : le secret partagé configuré.
- Message : corps de la requête sérialisée.
signature = HMAC-SHA256(secret, serializedMessage)
4. Ajouter l’en-tête HMAC
Ajoutez la signature calculée à la requête en tant qu’en-tête x-hmac-sha256 :
POST <streaming-ingestion-endpoint>
Content-Type: application/json
x-hmac-sha256: {CALCULATED_SIGNATURE}
<serialized-message>
Par exemple, l’en-tête est résolu sur une valeur similaire à :
{
"x-hmac-sha256": "5f2c8b7e0d9c3a4e6b1f2d3c4a5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3"
}
La valeur de l’en-tête doit représenter le calcul HMAC-SHA256 pour le corps exact de la requête envoyée à Adobe.
5. Envoyer la demande
Envoyez la requête signée via HTTPS au point d’entrée de l’API d’ingestion en flux continu.
L’API d’ingestion en flux continu vérifie la signature avant de traiter l’événement. Les demandes dont la signature est manquante ou non valide sont rejetées.
6. Faire pivoter le secret en toute sécurité
Lorsque vous faites pivoter un secret, suivez cette séquence :
- Créez un secret dans votre système de gestion des informations d’identification.
- Gardez le secret existant actif pendant que vous déployez le nouveau secret, si les secrets qui se chevauchent sont pris en charge.
- Mettez à jour la configuration du connecteur avec le nouveau secret.
- Déployez ou enregistrez la configuration.
- Envoyez une demande de test et vérifiez que l’authentification réussit.
- Surveillez les échecs d’authentification, puis révoquez l’ancien secret une fois que toutes les instances du connecteur utilisent le nouveau.
Vérification du connecteur
Testez le connecteur avec les scénarios d’authentification réussie et non réussie.
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 | |
|---|---|
| Test | Résultat attendu |
| Demande avec un jeton d’accès valide | L’événement est accepté et traité. |
| Requête sans jeton d’accès | La demande est rejetée. |
| Demande avec jeton d’accès expiré | La requête est rejetée ou le connecteur obtient un nouveau jeton et tente une nouvelle tentative conformément à sa politique de reprise. |
| Demande avec jeton d’accès non valide | La demande est rejetée. |
| Requête avec des portées insuffisantes | La demande est rejetée. |
| Demander après la rotation des informations d’identification | Le connecteur obtient et utilise les nouvelles informations d’identification avec succès. |
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 | |
|---|---|
| Test | Résultat attendu |
| Requête avec une signature valide et un secret actuel | L’événement est accepté et traité. |
Requête sans x-hmac-sha256 |
La demande est rejetée. |
| Requête avec une signature non valide | La demande est rejetée. |
| Demande signée avec un secret incorrect | La demande est rejetée. |
| Corps de la requête modifié après la génération de la signature | La demande est rejetée. |
| Requête signée avec un secret précédent valide lors de la rotation | Le résultat suit le comportement secret-rotation documenté. |
| Demande signée avec un secret supprimé | La demande est rejetée. |
Enregistrez les éléments suivants pour chaque test :
- Méthode de requête et point d’entrée.
- En-têtes de requête, avec secrets et jetons supprimés.
- Corps de requête sérialisé.
- Mécanisme d’authentification utilisé.
- Statut de réponse et corps.
- Horodatage et identifiant de corrélation ou de trace, le cas échéant.
- Indique si l’événement a bien été ingéré.
Dépannage
Échec de l’authentification OAuth
Vérifiez les points suivants :
- Le jeton d’accès a été généré pour l’organisation et l’environnement Adobe appropriés.
- L’ID client et le secret client appartiennent aux informations d’identification configurées.
- Les portées demandées sont correctes.
- Le jeton d’accès n’a pas expiré.
- Le jeton est envoyé à l’aide du schéma Authorization: Bearer.
- Le connecteur utilise le point d’entrée de jeton correct.
- Les informations d’identification ont accès à l’API ou au profil de produit requis.
Échec de l’authentification HMAC
Vérifiez les points suivants :
- L’en-tête
x-hmac-sha256est présent. - Le nom et la valeur de l’en-tête sont correctement orthographiés.
- Le connecteur utilise le secret correct.
- La signature est calculée avec HMAC-SHA256.
- La signature est calculée sur le corps exact de la requête sérialisée.
- Le corps de la requête n’est pas reformaté après le calcul de la signature.
- L’encodage de signature et la casse requis sont corrects.
- Le connecteur utilise le secret actuel ou précédent correct lors de la rotation.
- Le secret est disponible pour l’exécution et n’a pas été tronqué ni modifié.
Exigences de soumission
Avant d’envoyer ou de libérer votre connecteur, vérifiez les points suivants :
- Votre connecteur utilise l’authentification OAuth 2.0 ou basée sur HMAC pour chaque requête à l’API d’ingestion en flux continu.
- Vous avez testé les scénarios dans Vérifier le connecteur et enregistré les résultats.
- Votre connecteur rejette les requêtes non authentifiées et incorrectement authentifiées.
- Vos secrets et jetons ne sont pas validés dans le contrôle de code source, les journaux, les messages d’erreur ou les captures d’écran.
Étapes suivantes
Une fois l’authentification configurée et vérifiée, continuez à Tester et envoyer votre source. Pour savoir comment documenter les exigences d’authentification pour votre source, voir Documenter votre source (Streaming SDK).