-
Notifications
You must be signed in to change notification settings - Fork 1.4k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Update uninstallation instructions * Update docs/dev/oauth_for_integrations.md Co-authored-by: bgoldberg122 <[email protected]> * Update docs/dev/oauth_for_integrations.md Co-authored-by: DeForest Richards <[email protected]> * restructuring, adding more testing info * Apply suggestions from code review Co-authored-by: Austin Lai <[email protected]> * Update docs/dev/oauth_for_integrations.md Co-authored-by: Austin Lai <[email protected]> * Update docs/dev/oauth_for_integrations.md Co-authored-by: Florent Clarret <[email protected]> * Update docs/dev/oauth_for_integrations.md Co-authored-by: Florent Clarret <[email protected]> --------- Co-authored-by: bgoldberg122 <[email protected]> Co-authored-by: DeForest Richards <[email protected]> Co-authored-by: Austin Lai <[email protected]> Co-authored-by: Florent Clarret <[email protected]>
- Loading branch information
5 people
authored
Aug 8, 2023
1 parent
c845677
commit 66d9d63
Showing
1 changed file
with
49 additions
and
20 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -59,43 +59,72 @@ The client is the component of an application that enables users to authorize th | |
|
|
||
| For more information about implementing the OAuth protocol with Datadog, see [Datadog OAuth2][1]. For more information about building and publishing an integration, see the [Integrations developer documentation][5]. | ||
|
|
||
| 6. Test the OAuth protocol by clicking **Test Authorization** on your client's details page. This directs you to the onboarding URL and starts the authorization flow that a customer takes. | ||
| ### Test the OAuth client | ||
|
|
||
| Before your client is published, only members of your Datadog organization can authorize against your client during testing. | ||
| Once you have implemented the OAuth protocol, you should test your OAuth client to ensure that you can send data into Datadog, or pull data out, according to your use case. | ||
|
|
||
| 7. To validate that OAuth is working properly, make a request to the `marketplace_create_api` endpoint with your token in the headers of the request. | ||
| **Note**: Until your integration tile is published, you can only authorize the OAuth client from your sandbox organization. This means that you can only send data into or pull data out of your sandbox account. | ||
|
|
||
| If successful, this request returns an API key that you should securely save so you can use it to submit data into Datadog on behalf of the user. **You cannot access this API key value again after the initial request response**. | ||
| To test your OAuth client, complete the following steps: | ||
|
|
||
| 8. Test that your OAuth client can work across multiple [Datadog sites][8] by kicking off authorization from a non-US1 Datadog account: | ||
| - If you do not have access to a sandbox account on a different site, contact `[email protected]`. | ||
| - Export your app manifest from the account in the *original* Datadog site by navigating to the app you've created in the Developer Platform, clicking the gear icon on the top right, and clicking **Export App Manifest**. | ||
| - In your account on the *new* Datadog site, navigate to the Developer Platform and import your app manifest from Step 2. | ||
| - After successfully importing your manifest, navigate to the **OAuth & Permissions** tab to find your OAuth client, along with its client ID and client secret. Use these credentials to test authorization from this site. | ||
| #### Test that authorization is working properly | ||
| Ensure that you do not hit any errors when going through the basic authorization flow. | ||
|
|
||
| 9. Test any additional scopes that you’ve requested access for. | ||
| 1. Navigate to the Developer Platform, click the Edit icon on your app, and open the **OAuth and Permissions** tab. | ||
| 2. Select your OAuth client, and click the **Test Authorization** button on your client's details page. | ||
| 3. This directs you to the onboarding URL and starts the authorization flow that a customer takes. By clicking this button, the `domain` parameter is provided on the redirect to the `onboarding_url`. | ||
| 4. Go through the OAuth flow and authorize your integration. | ||
|
|
||
| ### Publish the OAuth client | ||
| #### Create an API Key | ||
| If your OAuth client requests the `api_keys_write` scope, ensure that you can successfully make a request to the `marketplace_create_api` endpoint with your token in the headers of the request. | ||
|
|
||
| If successful, this request returns an API key that you can find on the [API Keys Management page][10]. You must securely save this key to use it for submitting data into Datadog on behalf of the user. **You cannot access this API key value again after the initial request response**. | ||
|
|
||
| #### Test multiple Datadog sites | ||
| Test that your OAuth client can work across multiple [Datadog sites][8] by kicking off authorization from your EU Datadog sandbox organization. | ||
| 1. If you do not have access to a sandbox account on a different site, contact `[email protected]`. | ||
| 2. Export your app manifest from the organization in the *original* US1 Datadog site by navigating to the app you've created in the Developer Platform, clicking the Gear icon to the right of **Documentation**, and clicking **Export App Manifest**. | ||
| 3. In your EU sandbox organization, navigate to the Developer Platform and import your app manifest from Step 2. | ||
| 4. After successfully importing your manifest, navigate to the **OAuth & Permissions** tab to find your OAuth client, along with its client ID and client secret. Update your OAuth implementation to use these credentials. | ||
| 5. Navigate to the **Test Authorization** button, click it, and go through the OAuth flow. | ||
|
|
||
| ### Confirm data flow for all scopes | ||
| Ensure that you are able to send data in, pull data out, or edit data for each scope you've requested. | ||
|
|
||
| In order to publish an OAuth client, you first need to open a pull request for your integration in either the [`integrations-extras`][5] or [Marketplace][6] GitHub repositories. | ||
| ### Publish the OAuth client | ||
|
|
||
| As a part of your pull request, update your README file with an **uninstallation** section under `## Setup` that includes the following instructions (along with any custom instructions you would like to add): | ||
| #### Create or update your pull request | ||
| In order to publish an OAuth client, you first need to open a pull request for your integration in either the [`integrations-extras`][5] or [Marketplace][6] GitHub repositories if you haven't already. | ||
|
|
||
| - Once this integration has been uninstalled, any previous authorizations are revoked. | ||
| - Additionally, ensure that all API keys associated with this integration have been disabled by searching for the integration name on the [API Keys page][10]. | ||
| As a part of your pull request, complete the following steps: | ||
|
|
||
| 1. Update your README file with an `## Uninstallation` section under `## Setup` that includes the following instructions (along with any custom instructions you would like to add): | ||
| - Once this integration has been uninstalled, any previous authorizations are revoked. | ||
| - Additionally, ensure that all API keys associated with this integration have been disabled by searching for the integration name on the [API Keys page][10]. | ||
| 2. Update your `manifest.json` file to reference this new `## Uninstallation` section. This reference should appear directly beneath the support field: | ||
| - ``` | ||
| "support": "README.md#Support", | ||
| "uninstallation": "README.md#Uninstallation", | ||
| ``` | ||
|
|
||
| #### Initiate publishing process in Developer Platform | ||
| To start the publishing process in the [Developer Platform][4]: | ||
|
|
||
| 1. Navigate to the **Publishing** tab under **General**. In Step 1 of the publishing flow, you receive your published client ID and secret. In Step 2, you can enter additional information about your integration and see the published `app_uuid` to use below. | ||
| 1. Navigate to the **Publishing** tab under **General**. In Step 1 of the publishing flow, you receive your published client ID and secret. The OAuth implementation needs to be updated to include these client credentials. **Note:** Save your client ID and client secret in a secure location. This information is not shown again. | ||
|
|
||
| 2. In Step 2, you can enter additional information about your integration and see the published `app_uuid` to use below. | ||
|
|
||
| 3. When opening a pull request for a **new integration** in `integrations-extras` or `Marketplace`, use the `app_uuid` value from step 2 in the `app_uuid` field of the `manifest.json` file. If the `app_uuid` values do not align, your application does not publish correctly. If you have an **existing integration**, there is no need to update the `app_uuid`. | ||
|
|
||
| Once an OAuth client is submitted for publishing, the team is notified. When your pull request is approved by all required parties and is ready to be merged, at that point your OAuth client gets published as well. Your integration tile is then published to your sandbox account (_not_ for all customers), and your OAuth client can then be authorized by any Datadog organization (not only your Sandbox organization). | ||
|
|
||
| Save your client ID, client secret, and `app_uuid` in a secure location. | ||
| At this point, Datadog recommends doing final testing with your OAuth client to ensure authorization is working smoothly. | ||
|
|
||
| 2. When opening a pull request for a **new integration** in `integrations-extras` or `Marketplace`, use the `app_uuid` value for publishing in the `app_uuid` field of the `manifest.json` file. If the `app_uuid` values do not align, your application does not publish correctly. If you have an **existing integration**, there is no need to update the `app_uuid`. | ||
| #### Making changes after submitting your client for publishing | ||
|
|
||
| You cannot edit a published OAuth client directly, so only go through the publishing flow when everything has been tested and is ready to go. To make updates to the OAuth client, you need to go through the publishing flow again. **The published client credentials do not appear again**. | ||
| You cannot edit a published OAuth client directly, so only go through the publishing flow when everything has been tested and is ready to go. To make updates to the OAuth client after it has been submitted for publishing, you need to go through the publishing flow again and re-submit. **The published client credentials do not appear again**. | ||
|
|
||
| For more information about the integration publishing process, see the [Marketplace and Integrations documentation][7]. | ||
| For more information about publishing your integration tile and creating your pull request, see the [Marketplace and Integrations documentation][7]. | ||
|
|
||
| ## Add OAuth to an existing offering | ||
|
|
||
|
|
||