Join the Beta!
The Datadog Developer Platform is in beta. If you don't have access, contact apps@datadoghq.com.
Overview
This page provides a step-by-step overview on how to implement the OAuth protocol end-to-end on your application once your confidential client is created.
Implement the OAuth protocol
Create and configure your OAuth client in the Developer Platform.
After a user installs your integration, they can click the Connect Accounts button to connect their account in the Configure tab of the integration tile.
When a user clicks this button, they are directed to the onboarding_url
that you provided as a part of the OAuth client creation process. This page should be the sign-in page for your platform.
Once a user signs in, redirect them to the OAuth2 Authorization endpoint with the appropriate URL parameters, which includes the added code_challenge
parameter generated by your application.
To learn how to derive the code_challenge
parameter, see the PKCE section. Your application must save code_verifier
for the token request in Step 5.
- In order to build the URL for this post request, use the
site
query parameter that is provided on the redirect to your onboarding_url
. - This parameter is only provided if the user initiates authorization from the Datadog integration tile. See the Initiate authorization from a third-party location section for more options if the user chooses to initiate authorization externally.
- For example,
site
may be https://app.datadoghq.com
, https://app.datadoghq.eu
, https://us5.datadoghq.com
, or it might have a custom subdomain that must be accounted for, such as https://<custom_subdomain>.datadoghq.com
. - To handle multiple Datadog sites dynamically, you can append the Datadog
authorize
path to this constructed URL.
Once a user clicks Authorize, Datadog makes a POST request to the authorize endpoint. The user is redirected to the redirect_uri
that you provided when setting up the OAuth Client with the authorization code
parameter in the query component.
From the redirect_uri
, make a POST request to the Datadog token endpoint that includes the authorization code from Step 4, the code_verifier
from Step 3, your OAuth client ID, and client secret.
- In order to build the URL for this post request, use the
site
query parameter that is provided on the redirect to your redirect_uri
. - For example,
site
might be https://app.datadoghq.com
, https://app.datadoghq.eu
, https://us5.datadoghq.com
, or it might have a custom subdomain that must be accounted for, such as https://<custom_subdomain>.datadoghq.com
. - To handle multiple Datadog sites dynamically, you can append the Datadog
token
path to this constructed URL.
Upon success, you receive your access_token
and refresh_token
in the response body. Your application should display a confirmation page with the following message: You may now close this tab
.
Use the access_token
to make calls to Datadog API endpoints by sending it in as a part of the authorization header of your request: headers = {"Authorization": "Bearer {}".format(access_token)}
.
- When making calls to API endpoints, ensure that the user’s Datadog site is taken into account. For example, if a user is in the EU region, the events endpoint is
https://api.datadoghq.eu/api/v1/events
, while for users in US1, the events endpoint is https://api.datadoghq.com/api/v1/events
. Some endpoints may also require an API key, which is created in Step 8 below.
Call the API Key Creation endpoint to generate an API key that allows you to send data on behalf of Datadog users.
If the API_KEYS_WRITE
scope has not been added to your client, this step fails. This endpoint generates an API Key that is only shown once. Store this value in a secure database or location.
For more information about client creation and publishing, see OAuth for Datadog Integrations.
Initiate authorization from a third-party location
You can start the authorization process in Datadog by clicking Connect Accounts in the integration tile, or from the integration’s external website. For example, if there’s an integration configuration page on your website that Datadog users need to use, you can give users the option to start the authorization process from there.
When kicking off authorization from a third-party location—anywhere outside of the Datadog integration tile—you need to account for the Datadog site (such as EU, US1, US3, or US5) when routing users through the authorization flow and building out the URL for the authorization
and token
endpoints.
To ensure that users are authorizing in the correct site, always direct them to the US1 Datadog site (app.datadoghq.com
), and from there, they can select their region. Once the authorization flow is complete, ensure that all followup API calls use the correct site that is returned as a query parameter with the redirect_uri
(See Step 5 in Implement the OAuth protocol).
When users initiate authorization from the Datadog integration tile, they are required to have corresponding permissions for all requested scopes. If authorization is initiated from somewhere other than the integration tile, users without all of the required permissions may complete authorization (but are prompted to re-authorize with proper permissions when returning to the integration tile). To avoid this, users should be routed from third-party platforms to the Datadog integration tile to begin authorization.
Authorization code grant flow with PKCE
While the OAuth2 protocol supports several grant flows, the authorization code grant flow with PKCE is the recommended grant type for long-running applications where a user grants explicit consent once and client credentials can be securely stored.
This grant type allows applications to securely obtain a unique authorization code and exchange it for an access token that enables them to make requests to Datadog APIs. The authorization code grant flow consists of three steps:
- The application requests authorization from a user to access a set of Datadog scopes.
- When a user clicks Authorize, the application obtains a unique authorization code.
- The application exchanges the authorization code for an access token, which is used to access Datadog APIs.
Use the PKCE extension
Proof key for code exchange (PKCE) is an extension of the OAuth2 authorization code grant flow to protect OAuth2 clients from interception attacks. If an attacker intercepts the flow and gains access to the authorization code before it is returned to the application, they can obtain access tokens and gain access to Datadog APIs.
To mitigate such attacks, the PKCE extension includes the following parameters to securely correlate an authorization request with a token request throughout the grant flow:
Parameter | Definition |
---|
Code Verifier | A dynamically-generated cryptographic random string. |
Code Challenge | A transformation of the code verifier. |
Code Challenge Method | The method used to derive the code_challenge from the code_verifier . You must use SHA-256 to compute the code_challenge . |
The PKCE protocol integrates with the authorization code grant flow by completing the following actions:
The application generates a code_verifier
random string and derives the corresponding code_challenge
using the code_challenge_method
.
The application sends an authorization request to Datadog with the code_challenge
and code_challenge_method
parameters to obtain an authorization code.
The application sends a token request to Datadog with the authorization code and code_verifier
to obtain an access token. The token endpoint verifies the authorization code by transforming the code_verifier
using the code_challenge_method
and comparing it with the original code_challenge
value.
Further Reading
Additional helpful documentation, links, and articles: