Présentation

Cette page explique de façon détaillée comment implémenter le protocole OAuth de bout en bout dans votre application après la création de votre client confidentiel.

Implémenter le protocole OAuth

1. Dans votre compte sandbox partenaire Datadog, créez et configurez votre client OAuth dans la plateforme de développement.

2. Après avoir installé votre intégration, les utilisateurs peuvent cliquer sur le bouton Connect Accounts pour connecter leur compte dans l’onglet Configure du carré d’intégration.

   Lorsqu’un utilisateur clique sur ce bouton, il est redirigé vers la page spécifiée via le paramètre onboarding_url que vous avez défini dans le cadre du processus de création du client OAuth. Cette page doit correspondre à la page de connexion de votre plateforme.

3. Lorsqu’un utilisateur se connecte, redirigez-le vers l’endpoint d’autorisation OAuth2 avec les paramètres d’URL appropriés, notamment le paramètre code_challenge supplémentaire généré par votre application.

   Pour savoir comment obtenir le paramètre code_challenge, consultez la rubrique PKCE. Votre application doit enregistrer la valeur code_verifier pour la requête de token à l’étape 5.

   • Pour construire l’URL de cette requête GET, utilisez le paramètre de requête site fourni lors de la redirection vers votre onboarding_url.
   • Ce paramètre n’est fourni que si l’utilisateur initie l’autorisation depuis le carré d’intégration Datadog. Consultez la rubrique Initier l’autorisation depuis un emplacement tiers pour connaître les autres options disponibles si l’utilisateur choisit d’initier l’autorisation depuis un emplacement externe.
   • Le paramètre de requête site fournit le site Datadog dans lequel se trouve l’utilisateur autorisateur, ainsi que tout sous-domaine qu’il utilise éventuellement. Il est nécessaire pour construire l’URL de cette requête GET vers l’endpoint d’autorisation : <site>/oauth2/v1/authorize?....

4. Lorsqu’un utilisateur clique sur Authorize, Datadog envoie une requête POST à l’endpoint d’autorisation. L’utilisateur est alors redirigé vers la ressource spécifiée via le paramètre redirect_uri que vous avez défini lors de la configuration du client OAuth, avec le paramètre code d’autorisation dans le composant de requête.

5. Depuis la ressource spécifiée via le paramètre redirect_uri, envoyez à l’endpoint de token Datadog une requête POST comprenant le code d’autorisation de l’étape 4, la valeur code_verifier de l’étape 3, l’identifiant de votre client OAuth, ainsi que le secret du client.

   • Pour construire l’URL de cette requête POST, utilisez le paramètre de requête domain fourni lors de la redirection vers votre redirect_uri.
   • Il est nécessaire pour construire l’URL de cette requête POST vers l’endpoint de token : https://api.<domain>/oauth2/v1/token.

6. Une fois l’opération réussie, vous recevez vos tokens access_token et refresh_token dans le corps de la réponse. Votre application devrait afficher une page de confirmation avec le message suivant : You may now close this tab.

7. Utilisez le token access_token pour appeler les endpoints d’API Datadog en l’envoyant dans l’en-tête d’autorisation de votre requête : headers = {"Authorization": "Bearer {}".format(access_token)}.

   • Remarque* : les endpoints d’API diffèrent selon le site Datadog. Par exemple, si un utilisateur se trouve dans la région EU, l’endpoint Events est https://api.datadoghq.eu/api/v1/events, tandis que pour les utilisateurs en US1, l’endpoint Events est https://api.datadoghq.com/api/v1/events.
   • Utilisez le paramètre de requête domain directement dans ces appels d’API pour vous assurer que le bon endpoint est contacté. Par exemple, pour effectuer un appel vers l’endpoint Events, construisez l’URL de votre requête comme suit : https://api.<domain>/api/v1/events.
   • Certains endpoints peuvent également nécessiter une clé d’API, créée à l’étape 8.

8. Appelez l’endpoint de création de clé d’API pour générer une clé d’API vous permettant d’envoyer des données pour le compte des utilisateurs Datadog.

   Si le périmètre API_KEYS_WRITE n’a pas été ajouté à votre client, cette étape échoue. Cet endpoint génère une clé d’API qui n’est affichée qu’une seule fois et ne peut pas être régénérée sauf si l’utilisateur la supprime dans son compte Datadog. Stockez cette valeur dans une base de données ou un emplacement sécurisé.

Pour en savoir plus sur la création, le test et la publication de clients OAuth, consultez la section Créer une intégration basée sur une API.

Initier l’autorisation depuis un emplacement tiers

Les utilisateurs peuvent démarrer le processus d’autorisation dans Datadog en cliquant sur Connect Accounts dans le carré d’intégration. Lorsqu’un utilisateur clique sur Connect Accounts dans Datadog, des informations concernant son site Datadog sont envoyées lors de la redirection vers l’onboarding_url et lors de la redirection vers le redirect_uri. Le site Datadog de l’utilisateur est nécessaire pour effectuer des appels d’API en son nom et recevoir un code d’autorisation. Si un utilisateur initie l’autorisation depuis le site web externe de l’intégration, les informations sur le site de l’utilisateur ne sont pas fournies.

De plus, lorsque les utilisateurs initient l’autorisation depuis le carré d’intégration Datadog, ils doivent disposer des autorisations correspondantes pour tous les périmètres demandés. Si l’autorisation est initiée depuis un autre emplacement que le carré d’intégration, les utilisateurs ne disposant pas de toutes les autorisations requises peuvent terminer l’autorisation (mais sont invités à réautoriser avec les autorisations appropriées lorsqu’ils retournent au carré d’intégration Datadog).

Datadog recommande aux partenaires d’inviter les utilisateurs à initier l’autorisation depuis Datadog plutôt que depuis leur propre plateforme.

Bien que Datadog ne recommande pas de prendre en charge l’initiation de l’autorisation depuis un emplacement tiers en dehors du carré d’intégration Datadog, si vous choisissez cette voie, vous devez vous assurer de pouvoir prendre en charge les utilisateurs sur tous les sites Datadog, et être prêt à continuer à prendre en charge les nouveaux sites Datadog au fur et à mesure de leur création. Cela implique généralement de mettre en place un moyen pour l’utilisateur de saisir manuellement son site sur votre plateforme lors de l’autorisation.

Gardez à l’esprit que les organisations peuvent également avoir des sous-domaines (par exemple, https://subdomain.datadoghq.com). Les sous-domaines ne doivent pas être inclus dans les appels d’API, c’est pourquoi l’utilisation du paramètre de requête domain renvoyé lors de la redirection vers le redirect_uri est recommandée lors de la construction de l’URL pour tout appel d’API. Pour vous assurer que les utilisateurs s’autorisent sur le bon site, redirigez-les toujours vers le site Datadog US1 (app.datadoghq.com) ; depuis là, ils peuvent sélectionner leur région.

Flux d’octroi de code d’autorisation avec PKCE

Bien que le protocole OAuth2 prenne en charge plusieurs flux d’octroi, le flux d’octroi de code d’autorisation avec PKCE est recommandé pour les applications à exécution longue, où un utilisateur accorde son consentement explicite une fois et où les identifiants du client sont ensuite conservés de façon sécurisée.

Ce type d’octroi permet aux applications d’obtenir de façon sécurisée un code d’autorisation unique et de l’échanger contre un token d’accès leur permettant d’envoyer des requêtes aux API Datadog. Le flux d’octroi de code d’autorisation comporte trois étapes :

1. L’application demande l’autorisation à un utilisateur d’accéder à un ensemble de contextes Datadog.
2. Lorsqu’un utilisateur clique sur Authorize, l’application obtient un code d’autorisation unique.
3. L’application échange le code d’autorisation contre un token d’accès, qui est utilisé pour accéder aux API Datadog.

Utiliser l’extension PKCE

Proof Key for Code Exchange (PKCE) est une extension du flux d’octroi de code d’autorisation OAuth2 destinée à protéger les clients OAuth2 des attaques par interception. Si une personne malveillante intercepte le flux et parvient à accéder au code d’autorisation avant que celui-ci soit renvoyé à l’application, il peut accéder aux tokens et aux API Datadog.

Pour limiter ces risques, l’extension PKCE inclut les paramètres suivants pour associer de façon sécurisée une requête d’autorisation à une requête de token tout au long du flux d’octroi :

Le protocole PKCE s’intègre au flux d’octroi de code d’autorisation en effectuant les actions suivantes :

• L’application génère une chaîne aléatoire code_verifier et obtient le code_challenge correspondant en utilisant la méthode définie via le paramètre code_challenge_method.

• L’application envoie à Datadog une requête d’autorisation contenant les paramètres code_challenge et code_challenge_method pour obtenir un code d’autorisation.

• L’application envoie à Datadog une requête de token contenant le code d’autorisation et la chaîne code_verifier pour obtenir un token d’accès. L’endpoint de token vérifie le code d’autorisation en transformant la chaîne code_verifier à l’aide de la méthode définie via le paramètre code_challenge_method et compare la valeur obtenue à la valeur code_challenge d’origine.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Utiliser les endpoints d'autorisation OAuth 2.0DOCUMENTATION