AWS quick documentation change
Summary
Comprehensive rewrite of Zendesk integration documentation, adding detailed prerequisites, step-by-step authentication configuration (OAuth client and API token), connector setup instructions, available actions table, and troubleshooting guidance.
Security assessment
The changes significantly expand authentication documentation by adding OAuth/API key setup procedures and emphasize security best practices like immediate recording of secrets. However, there's no evidence of addressing a specific vulnerability or security incident.
Diff
diff --git a/quick/latest/userguide/zendesk-integration.md b/quick/latest/userguide/zendesk-integration.md index 9c2567fe9..692dcb1ce 100644 --- a//quick/latest/userguide/zendesk-integration.md +++ b//quick/latest/userguide/zendesk-integration.md @@ -7 +7 @@ -What you can doSet up Zendesk integrationManage Zendesk integrations +PrerequisitesVerify your Zendesk accountConfigure Zendesk accountSet up the integration in Amazon QuickAvailable actionsTroubleshooting @@ -11 +11 @@ What you can doSet up Zendesk integrationManage Zendesk integrations -With Zendesk Suite integration in Amazon Quick, you can perform actions within Zendesk instances, including managing tickets, users, and customer support workflows. For Amazon Quick subscription requirements, see [Set up integrations in the console](./integration-console-setup-process.html). +Manage your Zendesk support tickets directly from Amazon Quick using natural language. With the Zendesk Suite action connector, you can create, update, search, and list support tickets without leaving Amazon Quick. @@ -13 +13 @@ With Zendesk Suite integration in Amazon Quick, you can perform actions within Z -## What you can do +Zendesk Suite is available as a built-in connector in Amazon Quick. To set up this integration, complete the following two steps. First, prepare your Zendesk account with the required access. Then, create the connector in Amazon Quick and authenticate with your Zendesk credentials. @@ -15 +15 @@ With Zendesk Suite integration in Amazon Quick, you can perform actions within Z -With Zendesk Suite integration, you can perform actions within your Zendesk instances through the action connector. +This connector supports OAuth user authentication and API key service authentication. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](./quick-action-auth.html). @@ -17 +17 @@ With Zendesk Suite integration, you can perform actions within your Zendesk inst -**Action connector** +## Prerequisites @@ -18,0 +19 @@ With Zendesk Suite integration, you can perform actions within your Zendesk inst +Before you set up the integration, verify that you have the following resources and access. @@ -20 +21 @@ With Zendesk Suite integration, you can perform actions within your Zendesk inst -Create, update, and manage tickets, users, and customer support processes through the Zendesk API. + * An active Zendesk account with an admin role. @@ -22 +23 @@ Create, update, and manage tickets, users, and customer support processes throug -## Set up Zendesk integration + * Permissions to access tickets and support data in your Zendesk instance. @@ -24 +25,75 @@ Create, update, and manage tickets, users, and customer support processes throug -Follow these steps to create your Zendesk integration: + * A subscription that meets the requirements described in [Set up integrations in the console](./integration-console-setup-process.html). + + + + +## Verify your Zendesk account + +Before you configure Amazon Quick, verify that your Zendesk account meets the following requirements. + + * Your Zendesk account is active and you can sign in to the [Zendesk sign-in page](https://www.zendesk.com/login/) on the Zendesk website. + + * The tickets and support data that you want to access are accessible to your account. + + + + +## Configure Zendesk account + +The Custom OAuth app authentication method in Amazon Quick requires an OAuth client configured in Zendesk. The API key authentication method requires an API token. + +### To configure an OAuth client + + 1. In your Zendesk instance, navigate to **Admin Center** , then **Apps and integrations** , and then **OAuth clients** under **API**. + + 2. Choose **Add OAuth Client**. + + 3. Complete the form with the following fields: + + * **Name** – Enter a name for your app. + + * **Description** – Enter a short description. + + * **Identifier** – Enter a unique identifier for the OAuth client. + + * **Redirect URLs** – Enter `https://`region`.quicksight.aws.amazon.com/sn/oauthcallback`. Replace `region` with your AWS Region, for example, `us-east-1`. + + 4. Choose **Save**. Zendesk generates a client secret. + +###### Important + +Record the client secret now. You cannot retrieve it after you leave this page. + + 5. After you capture the secret, choose **Save** again to create the OAuth client. + + + + +The Identifier and the secret serve as the Client ID and Client Secret when you configure the action connector in Amazon Quick with the Custom OAuth app authentication method. + +For more information, see [Using OAuth authentication with your application](https://support.zendesk.com/hc/en-us/articles/4408845965210-Using-OAuth-authentication-with-your-application) on the Zendesk website. + +### To configure an API token + + 1. Navigate to **Admin Center** , then **Apps and integrations** , and then **API tokens**. + + 2. Choose **Add API token**. + + 3. For **Description** , enter a short description for the API token. + + 4. Choose **Save**. Zendesk generates an API token. + +###### Important + +Record the API token now. You cannot retrieve it after you leave this page. + + + + +If you choose the API key authentication method in Amazon Quick, use this API token as the API key value. + +For more information, see [Managing API token access to the Zendesk API](https://support.zendesk.com/hc/en-us/articles/4408889192858-Managing-API-token-access-to-the-Zendesk-API) on the Zendesk website. + +## Set up the integration in Amazon Quick + +After you verify your Zendesk account access, create the connector in Amazon Quick. @@ -30 +105,15 @@ Follow these steps to create your Zendesk integration: - 3. Find and choose **Zendesk Suite**. + 3. Choose **Zendesk Suite** from the options available. + + 4. In the **Zendesk Suite** dialog, enter the following fields: + + * **Name** – A descriptive name for your Zendesk connector. + + * **Description (Optional)** – Choose **\+ Add Description** to add notes about how this connector will be used. + + * **Connection type** – Choose **Public network**. + + 5. Choose your authentication method and configure the connector settings: + + * **Custom OAuth app** – Enter the following fields for your Zendesk instance: + + * **Base URL** @@ -32 +121 @@ Follow these steps to create your Zendesk integration: - 4. Fill in the integration details: + * **Client ID** @@ -34 +123 @@ Follow these steps to create your Zendesk integration: - * **Name** \- Descriptive name for your Zendesk integration. + * **Client Secret** @@ -36 +125 @@ Follow these steps to create your Zendesk integration: - * **Description** (Optional) - Purpose of the integration. + * **Token URL** @@ -38 +127 @@ Follow these steps to create your Zendesk integration: - 5. Choose your connection type: + * **Authorization URL** @@ -40 +129 @@ Follow these steps to create your Zendesk integration: - * **User authentication** \- OAuth-based authentication for individual user access. + * **Redirect URL** @@ -42 +131 @@ Follow these steps to create your Zendesk integration: - * **Service authentication** \- API key-based authentication for service access. + * **API Key** – Enter the following fields: @@ -44 +133 @@ Follow these steps to create your Zendesk integration: - 6. Fill in the connection settings based on your selected authentication method (either user or service): + * **Base URL** @@ -46 +135 @@ Follow these steps to create your Zendesk integration: - 1. For **User authentication (OAuth)** , configure the following fields: + * **API Key** (Zendesk API token) @@ -48 +137 @@ Follow these steps to create your Zendesk integration: - * **Base URL** \- Zendesk instance URL. + * **Email** associated with your Zendesk account @@ -50 +139 @@ Follow these steps to create your Zendesk integration: - * **Client ID** \- Zendesk OAuth app client ID. + 6. Choose **Next**. @@ -52 +141 @@ Follow these steps to create your Zendesk integration: - * **Client Secret** \- Zendesk OAuth app client secret. + 7. Review the actions for Zendesk Suite and choose **Next**. @@ -54 +143 @@ Follow these steps to create your Zendesk integration: - * **Token URL** \- Zendesk OAuth token endpoint. + 8. Specify who can access the connector: @@ -56 +145 @@ Follow these steps to create your Zendesk integration: - * **Auth URL** \- Zendesk OAuth authorization endpoint. + * To share with a team, enter a team name or group email. @@ -58 +147 @@ Follow these steps to create your Zendesk integration: - * **Redirect URL** \- OAuth redirect URI. + * To keep it private, leave the field blank. @@ -60 +149 @@ Follow these steps to create your Zendesk integration: -Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. + * To share with all users, toggle **Everyone in your organization**. @@ -62 +151 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. - 2. For **Service authentication (API Key)** , configure the following fields: + 9. Choose **Publish**. @@ -64 +152,0 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. - * **API Key** \- Zendesk API token. @@ -66 +153,0 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. - * **Base URL** \- Zendesk instance URL. @@ -68 +154,0 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. - * **Email** \- Associated Zendesk user email. @@ -70 +156 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. - 7. Select **Create and continue**. +The connector appears in the **Available** panel with a status of **Connected**. @@ -72 +158 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. - 8. Choose users to share the integration with. +## Available actions @@ -74 +160 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. - 9. Click **Next**. +After you set up the connector, you can use the following ticket management actions. @@ -75,0 +162,7 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. +Zendesk Suite available actions Action | Description +---|--- +Create Ticket | Create new ticket +List Search Results | Search tickets +List Tickets | View all tickets +Show Ticket | View ticket details +Update Ticket | Edit ticket details @@ -76,0 +170 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. +###### Note @@ -77,0 +172 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. +The actions that you can use depend on the permissions that are configured in your Zendesk account. @@ -79 +174 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`. -## Manage Zendesk integrations +## Troubleshooting @@ -81 +176 @@ Required OAuth scopes are `tickets:read`, `tickets:write`, and `read`.