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
Within your Datadog Partner Sandbox Account, 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.
- To build the URL for this GET 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.
- The
site
query parameter provides the Datadog site that the authorizing user is in, as well as any subdomain they may be using, and is required to construct the URL for this GET request to the Authorize endpoint: <site>/oauth2/v1/authorize?...
.
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.
- To build the URL for this post request, use the
domain
query parameter that is provided on the redirect to your redirect_uri
. - It is required to construct the URL for this POST request to the token endpoint:
https://api.<domain>/oauth2/v1/token
.
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)}
.
- Note*: API endpoints are different in each Datadog site. 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
. - Use the
domain
query parameter directly in these API calls to ensure the correct endpoint is being contacted. For example, to make a call to the Events endpoint, you would build your request URL as https://api.<domain>/api/v1/events
. - Some endpoints may also require an API key, which is created in Step 8.
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, and cannot be re-generated unless the user deletes it within their Datadog account. Store this value in a secure database or location.
For more information about OAuth client creation, testing and publishing, see OAuth for Datadog Integrations.
Initiate authorization from a third-party location
Users can start the authorization process in Datadog by clicking Connect Accounts in the integration tile. When a user clicks Connect Accounts in Datadog, information regarding their Datadog site is sent on redirect to the onboarding_url
and on redirect to the redirect_uri
. The user’s Datadog site is required to make API calls on behalf of the user and receive an authorization code. If a user initiates authorization from the integration’s external website, the user’s site information is not provided.
Additionally, 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 they return to the Datadog integration tile).
Datadog recommends that partners prompt users to initiate authorization from Datadog, rather than from their own platform.
While Datadog does not recommend supporting initiating authorization from a third-party location anywhere outside of the Datadog integration tile, if you do choose to go down this path then you must ensure that you are able to support users in all Datadog sites, and are willing to continue to support new Datadog sites as they may be created. This usually includes implementing a way for the user to manually input their site onto your platform while authorizing.
Keep in mind that organizations may have subdomains as well (for example, https://subdomain.datadoghq.com). Subdomains should not be included in API calls, which is why using the domain
query parameter that’s returned on redirect to the redirect_uri
is recommended when building out the URL for any API call. 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.
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. The code_challenge must use a base64url encoding. |
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: