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

1. Create and configure your OAuth client in the Developer Platform.

2. 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.

3. 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?....

4. 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.

5. 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.

6. 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.

7. 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.

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:

1. The application requests authorization from a user to access a set of Datadog scopes.
2. When a user clicks Authorize, the application obtains a unique authorization code.
3. 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:

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:

Learn how to use the OAuth 2.0 authorization endpointsDOCUMENTATION