AWS quick documentation change
Summary
Comprehensive rewrite of Smartsheet integration documentation, adding detailed prerequisites, authentication configuration steps (OAuth and API key), OAuth scopes, setup instructions, available actions, and troubleshooting guidance.
Security assessment
The changes add significant security documentation including authentication methods, secure token handling warnings, OAuth scopes, and permission considerations. However, there is no evidence this addresses a specific security vulnerability or incident - it appears to be routine documentation enhancement for a new integration feature.
Diff
diff --git a/quick/latest/userguide/smartsheet-integration.md b/quick/latest/userguide/smartsheet-integration.md index 3396feacc..92f74628c 100644 --- a//quick/latest/userguide/smartsheet-integration.md +++ b//quick/latest/userguide/smartsheet-integration.md @@ -5 +5 @@ -What you can doSet up Smartsheet integrationManage Smartsheet integrations +PrerequisitesConfigure Smartsheet Developer ToolsOAuth access scopesSet up the integration in Amazon QuickAvailable actionsManage and troubleshoot @@ -9 +9 @@ What you can doSet up Smartsheet integrationManage Smartsheet integrations -With Smartsheet integration in Amazon Quick, you can perform actions within Smartsheet workspaces, including managing sheets, rows, and collaborative work. This integration supports action execution only and requires Amazon Quick Pro tier or higher. +Use the Smartsheet action connector to manage sheets, rows, reports, and search across your Smartsheet workspaces directly in Amazon Quick through natural language. This integration uses the Smartsheet API. For more information, see [Smartsheet API introduction](https://developers.smartsheet.com/api/smartsheet/introduction) in the Smartsheet documentation. @@ -11 +11 @@ With Smartsheet integration in Amazon Quick, you can perform actions within Smar -## What you can do +Setting up this integration involves two steps. First, you configure credentials in Smartsheet for your chosen authentication method. Then, you create the integration in Amazon Quick and connect it to your Smartsheet account. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](./quick-action-auth.html). @@ -13 +13 @@ With Smartsheet integration in Amazon Quick, you can perform actions within Smar -With Smartsheet integration, you can perform actions within your Smartsheet workspaces through the action connector. +## Prerequisites @@ -15 +15 @@ With Smartsheet integration, you can perform actions within your Smartsheet work -**Action connector** +Before you set up the integration, make sure that you meet the following requirements: @@ -16,0 +17 @@ With Smartsheet integration, you can perform actions within your Smartsheet work + * A Smartsheet account with a Business or Enterprise plan. Free accounts cannot generate API access tokens or register OAuth apps. For more information, see [Smartsheet pricing](https://www.smartsheet.com/pricing) on the Smartsheet website. @@ -18 +19 @@ With Smartsheet integration, you can perform actions within your Smartsheet work -Create, update, and manage sheets, rows, columns, and collaborative features through the Smartsheet API. + * Access to [Smartsheet Developer Tools](https://developers.smartsheet.com/) activated for your account. To register, go to the [Developer Tools Registration](https://developers.smartsheet.com/register) page. @@ -20 +21 @@ Create, update, and manage sheets, rows, columns, and collaborative features thr -## Set up Smartsheet integration + * For subscription requirements, see [Set up integrations in the console](./integration-console-setup-process.html). @@ -22 +23,91 @@ Create, update, and manage sheets, rows, columns, and collaborative features thr -Follow these steps to create your Smartsheet integration: + + + +## Configure Smartsheet Developer Tools + +Before you configure Amazon Quick, set up credentials in Smartsheet. The steps you complete depend on which authentication method you plan to use. Amazon Quick supports two authentication methods for Smartsheet. For more information about these methods, see [Authentication methods](./quick-action-auth.html). + + * **User authentication (OAuth)** – Each user signs in with their own Smartsheet account. Actions run with that user's permissions. This method uses [Custom user-based authentication](./quick-action-auth.html#quick-custom-user-auth). Complete the Register for Developer Tools and create a developer profile and Register the OAuth application sections below. + + * **Service authentication (API key)** – All actions run using a single API token. This method uses [API key authentication](./quick-action-auth.html#quick-actions-api-key-auth). Complete the Generate an API access token (service authentication only) section below. + + + + +For more information about Smartsheet OAuth, see [OAuth](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth) in the Smartsheet API documentation. + +### Register for Developer Tools and create a developer profile + + 1. Go to the [Developer Tools Registration](https://developers.smartsheet.com/register) page and register the Smartsheet account you want to use with your apps. For more information, see [Register for Developer Tools](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#register-for-developer-tools) in the Smartsheet API documentation. + + 2. After Smartsheet activates Developer Tools, sign in to the Smartsheet application and choose your **Account** icon in the lower-left corner, then choose **Developer Tools**. + + 3. Choose **Create Developer Profile** and enter a profile name. For more information, see [Create your developer profile](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#create-your-developer-profile) in the Smartsheet API documentation. + + + + +###### Tip + +Smartsheet recommends using a dedicated service account for OAuth apps rather than a personal account. + +### Register the OAuth application + + 1. In Smartsheet Developer Tools, choose **Create New App**. + + 2. Complete the form: + + * **App name** – A name to identify your app to users. + + * **App description** – A brief description of the integration. + + * **App URL** – The URL that launches your app, or a landing page. + + * **App contact/support** – Support contact information. + + * **App redirect URL** – `https://`{region}`.quicksight.aws.amazon.com/sn/oauthcallback` + +Replace `{region}` with your AWS Region (for example, `us-east-1`). + + 3. Choose **Save**. Smartsheet generates the **App client ID** and **App secret**. + + 4. Copy the **Client ID** and **Client Secret** values. You need these when you configure the integration in Amazon Quick. + + + + +For more information, see [Register an app](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#register-an-app) in the Smartsheet API documentation. + +### Generate an API access token (service authentication only) + +If you plan to use service authentication instead of OAuth, generate an API access token. You must have a Business or Enterprise plan to generate tokens. For more information, see [Generate an API access token](https://help.smartsheet.com/articles/2482389-generate-API-key) in the Smartsheet Help Center. + + 1. In the Smartsheet application, choose your **Account** (profile image) at the bottom of the left navigation bar, then choose **Personal Settings**. + + 2. Choose the **API Access** tab and choose **Generate new access token**. + + 3. Name the token and choose **OK**. Copy the token value immediately — this is the only time it's visible. + + + + +###### Important + +Store your access token securely. Anyone with the token can access all Smartsheet data that the token owner has access to. Do not commit tokens to version control systems. For best practices on storing tokens, see [Authentication](https://developers.smartsheet.com/api/smartsheet/guides/basics/authentication) in the Smartsheet API documentation. + +## OAuth access scopes + +When you configure user authentication (OAuth), the integration requests the following access scopes from Smartsheet. These scopes determine what the integration can do on behalf of the authenticated user. If you use service authentication (API key) instead, the integration uses the full permissions of the token owner and scopes do not apply. For more information, see [Access scopes](https://developers.smartsheet.com/api/smartsheet/guides/advanced-topics/oauth#access-scopes) in the Smartsheet API documentation. + +Smartsheet OAuth access scopes Scope | Description +---|--- +`READ_SHEETS` | Read all sheet data, including attachments, discussions, and cell data. +`WRITE_SHEETS` | Insert and modify sheet data, including attachments, discussions, and cell data. + +###### Note + +Access scopes don't override existing sharing permissions. For example, having the `WRITE_SHEETS` scope doesn't allow the integration to update a sheet on which the user has only viewer-level access. For more information, see [Resource access levels](https://developers.smartsheet.com/api/smartsheet/guides/basics/resource-access-levels) in the Smartsheet API documentation. + +## Set up the integration in Amazon Quick + +After you complete the Smartsheet Developer Tools configuration, create the integration in Amazon Quick. @@ -26 +117,31 @@ Follow these steps to create your Smartsheet integration: - 2. Choose **Smartsheet** from the integration options, click the Add (plus "+") button. + 2. Choose **Smartsheet** and choose the Add (plus "+") button. + + 3. Enter the integration details: + + * **Name** – Descriptive name for your Smartsheet integration. + + * **Description** (Optional) – Purpose of the integration. + + 4. Choose your connection type and fill in the connection settings. For more information about these authentication methods, see [Authentication methods](./quick-action-auth.html). + + 1. For **User authentication (OAuth)** , use the Client ID and Client Secret from your Smartsheet Developer Tools app registration. Configure the following fields: + + * **Base URL** – `https://api.smartsheet.com/2.0` + + * **Client ID** – App client ID from your Smartsheet Developer Tools app registration. + + * **Client Secret** – App secret from your Smartsheet Developer Tools app registration. + + * **Token URL** – `https://api.smartsheet.com/2.0/token` + + * **Auth URL** – `https://app.smartsheet.com/b/authorize` + + * **Redirect URL** – `https://`{region}`.quicksight.aws.amazon.com/sn/oauthcallback` + + 2. For **Service authentication (API key)** , use the API access token from your Smartsheet Personal Settings. Configure the following fields: + + * **API Key** – Smartsheet API access token generated from your Personal Settings. + + * **Base URL** – `https://api.smartsheet.com/2.0` + + * **Email** – Email address associated with the Smartsheet account that generated the token. @@ -28 +149 @@ Follow these steps to create your Smartsheet integration: - 3. Fill in the integration details: + 5. Choose **Create and continue**. @@ -30 +151 @@ Follow these steps to create your Smartsheet integration: - * **Name** \- Descriptive name for your Smartsheet integration. + 6. Choose users to share the integration with. @@ -32 +153 @@ Follow these steps to create your Smartsheet integration: - * **Description** (Optional) - Purpose of the integration. + 7. Choose **Next**. @@ -34 +154,0 @@ Follow these steps to create your Smartsheet integration: - 4. Choose your connection type: @@ -36 +155,0 @@ Follow these steps to create your Smartsheet integration: - * **User authentication** \- OAuth-based authentication for individual user access. @@ -38 +156,0 @@ Follow these steps to create your Smartsheet integration: - * **Service authentication** \- API key-based authentication for service access. @@ -40 +158 @@ Follow these steps to create your Smartsheet integration: - 5. Fill in the connection settings based on your selected authentication method (either user or service): +For user authentication, go to **Integrations** > **Actions** > your Smartsheet integration name, and choose **Sign in** to complete the OAuth authorization flow. In the Smartsheet consent window, choose **Allow** to grant access. @@ -42 +160 @@ Follow these steps to create your Smartsheet integration: - 1. For **User authentication (OAuth)** , configure the following fields: +###### Important @@ -44 +162 @@ Follow these steps to create your Smartsheet integration: - * **Base URL** \- Smartsheet API base URL. +With service authentication, all actions run using the API token owner's permissions. Any Amazon Quick user with access to this integration can perform actions on all Smartsheet resources that the token owner can access. Scope the token permissions appropriately for your organization's security requirements. @@ -46 +164 @@ Follow these steps to create your Smartsheet integration: - * **Client ID** \- Smartsheet OAuth app client ID. +###### Note @@ -48 +166 @@ Follow these steps to create your Smartsheet integration: - * **Client Secret** \- Smartsheet OAuth app client secret. +If you use Smartsheet Gov, Smartsheet Regions Europe, or Smartsheet Regions Australia, use the corresponding base URL for your environment: @@ -50 +168,6 @@ Follow these steps to create your Smartsheet integration: - * **Token URL** \- Smartsheet OAuth token endpoint. +Smartsheet regional base URLs Environment | Base URL +---|--- +Smartsheet | `https://api.smartsheet.com/2.0` +Smartsheet Gov | `https://api.smartsheetgov.com/2.0` +Smartsheet Regions Europe | `https://api.smartsheet.eu/2.0` +Smartsheet Regions Australia | `https://api.smartsheet.au/2.0` @@ -52 +175 @@ Follow these steps to create your Smartsheet integration: - * **Auth URL** \- Smartsheet OAuth authorization endpoint. +For more information, see [Base URL](https://developers.smartsheet.com/api/smartsheet/guides/basics/base-url) in the Smartsheet API documentation. @@ -54 +177 @@ Follow these steps to create your Smartsheet integration: - * **Redirect URL** \- OAuth redirect URI. +## Available actions @@ -56 +179 @@ Follow these steps to create your Smartsheet integration: -Required OAuth scopes are `READ_SHEETS` and `WRITE_SHEETS`. +After you set up the integration, the following actions are available.