AWS quick medium security documentation change
Summary
Updated Jira Cloud integration documentation to focus on OAuth 2.0 (3LO) app setup in Atlassian Developer Console, added detailed permission scopes, and restructured authentication configuration steps. Removed API token references in favor of OAuth-based authentication.
Security assessment
Changes include explicit guidance for OAuth scopes configuration (read/write permissions), warnings about Jira's behavior with revoked tokens (JRACLOUD-82932), and removal of less secure API token authentication documentation. The emphasis on granular permission scopes and OAuth callback URL validation improves security posture.
Diff
diff --git a/quick/latest/userguide/jira-integration.md b/quick/latest/userguide/jira-integration.md index 4a2a52373..fa026b3e8 100644 --- a//quick/latest/userguide/jira-integration.md +++ b//quick/latest/userguide/jira-integration.md @@ -5 +5 @@ -What you can doBefore you beginCreate a Jira API tokenSet up Jira integrationConfigure authenticationAvailable actionsShare integrationsManage Jira integrations +Before you beginConfigure the Atlassian Developer ConsoleSet up the integration in Amazon QuickAvailable actionsManage and troubleshoot @@ -7 +7 @@ What you can doBefore you beginCreate a Jira API tokenSet up Jira integrationCon -# Jira Cloud integration +# Atlassian Jira Cloud integration @@ -9 +9 @@ What you can doBefore you beginCreate a Jira API tokenSet up Jira integrationCon -Connect Amazon Quick to your Jira Cloud instance to manage issues, projects, and other Jira objects. You can create, update, and query Jira content without leaving your Amazon Quick environment. This integration requires Amazon Quick Pro tier or higher. +Use the Atlassian Jira Cloud action connector to create, update, search, and manage Jira issues, projects, sprints, and users directly in Amazon Quick through natural language. @@ -11,12 +11 @@ Connect Amazon Quick to your Jira Cloud instance to manage issues, projects, and -## What you can do - -With Jira Cloud integration, you can perform actions within your Jira instances through the Jira REST API. - -**Action connector** - - -Create, update, and query Jira issues, projects, and other objects through the Jira REST API. - -###### Note - -This integration supports action execution only. You can't use it to create knowledge bases or access Jira data for search purposes. +Setting up this integration involves two steps. First, you create an OAuth 2.0 (3LO) app in the Atlassian Developer Console and configure its permissions. Then, you create the integration in Amazon Quick and connect it to your Atlassian app. For information about the authentication methods that Amazon Quick supports, see [Authentication methods](./quick-action-auth.html). @@ -26 +15 @@ This integration supports action execution only. You can't use it to create know -You need the following to set up Jira integration: +Make sure you have the following before you set up the integration. @@ -28 +17 @@ You need the following to set up Jira integration: - * Jira Cloud instance with appropriate permissions. + * Atlassian Jira Cloud. @@ -30 +19 @@ You need the following to set up Jira integration: - * Jira user account or API token credentials. + * Access to the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) to create or manage an OAuth app. @@ -32 +21 @@ You need the following to set up Jira integration: - * Amazon Quick Author or higher. + * For subscription requirements, see [Set up integrations in the console](./integration-console-setup-process.html). @@ -34 +22,0 @@ You need the following to set up Jira integration: - * Administrative access to configure OAuth applications (for user authentication). @@ -37,0 +26 @@ You need the following to set up Jira integration: +## Configure the Atlassian Developer Console @@ -39 +28 @@ You need the following to set up Jira integration: -## Create a Jira API token +If you plan to use user authentication (3LO), create an OAuth 2.0 app in the Atlassian Developer Console before you configure Amazon Quick. Complete all of the following steps before moving to the Amazon Quick console. @@ -41 +30 @@ You need the following to set up Jira integration: -To use API key authentication, create an API token in your Atlassian account. +If you plan to use service authentication (API Key) only, you can skip this section and proceed to Set up the integration in Amazon Quick. @@ -43 +32 @@ To use API key authentication, create an API token in your Atlassian account. - 1. Go to your Atlassian account settings and choose **Security**. +For more information about OAuth 2.0 (3LO) apps, see [OAuth 2.0 (3LO) apps](https://developer.atlassian.com/cloud/jira/platform/oauth-2-3lo-apps/) in the Atlassian developer documentation. @@ -45 +34 @@ To use API key authentication, create an API token in your Atlassian account. - 2. Create a new API token for Amazon Quick integration. +### Create an OAuth 2.0 (3LO) app @@ -47 +36 @@ To use API key authentication, create an API token in your Atlassian account. - 3. Copy the generated token to use in your Amazon Quick integration setup. +Amazon Quick uses an Atlassian OAuth 2.0 (3LO) app to authenticate with your Atlassian Cloud product on behalf of your users. Create this app in the Atlassian Developer Console before you configure Amazon Quick. @@ -49 +38 @@ To use API key authentication, create an API token in your Atlassian account. - 4. Note your Jira Cloud instance URL and user email address. Your Jira Cloud instance URL is a special value for API calls that can be found by navigating to `https://`your-domain`.atlassian.net/_edge/tenant_info`. + 1. Open the [Atlassian Developer Console](https://developer.atlassian.com/console/myapps/) and sign in with your Atlassian account. @@ -50,0 +40 @@ To use API key authentication, create an API token in your Atlassian account. + 2. Choose **Create** , then choose **OAuth 2.0 integration**. @@ -51,0 +42 @@ To use API key authentication, create an API token in your Atlassian account. + 3. For **Name** , enter a descriptive name for your integration, for example ``your-app-name` connector`. @@ -52,0 +44 @@ To use API key authentication, create an API token in your Atlassian account. + 4. Review and accept the Atlassian developer terms. @@ -54,11 +46 @@ To use API key authentication, create an API token in your Atlassian account. -###### Important - -Jira Cloud may return HTTP 200 success responses even when API tokens are revoked or improperly configured. For more infomration see [JRACLOUD-82932](https://jira.atlassian.com/browse/JRACLOUD-82932). If your integration appears to connect successfully but actions fail unexpectedly, verify that your API token is valid and has not been revoked. - -## Set up Jira integration - -Follow these steps to connect Amazon Quick to your Jira Cloud instance. - - 1. In the Amazon Quick console, choose **Integrations**. - - 2. Click **Add** (plus "+" button). + 5. Choose **Create**. @@ -66 +47,0 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - 3. Complete the integration details: @@ -68 +48,0 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Name** \- Enter a descriptive name for your Jira integration. @@ -70 +49,0 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Description** (Optional) - Describe the purpose of this integration. @@ -72 +51 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - 4. Choose connection type (user or service authentication). +### Configure permissions @@ -74 +53 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - 5. Complete the connection settings based on authentication method: +After you create the OAuth 2.0 app, add the API permissions that Amazon Quick needs to interact with your Atlassian product. @@ -76 +55 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **For User authentication (OAuth):** + 1. From your app in the Atlassian Developer Console, choose **Permissions** in the left navigation. @@ -78 +57 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Base URL** \- Your Jira Cloud instance URL. This must be provided in the following format: `https://api.atlassian.com/ex/jira/`instanceid``. Your `instanceid` can be found by navigating to `https://`your-domain`.atlassian.net/_edge/tenant_info`. + 2. Find the API for your Atlassian product (for example, **Jira API** or **Confluence API**) and choose **Add**. The button changes to **Configure** after the API is added. @@ -80 +59 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Client ID** \- Your Atlassian OAuth app client ID. + 3. Choose **Configure**. The scopes page opens with **Classic scopes** and **Granular scopes** tabs. @@ -82 +61 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Client Secret** \- Your Atlassian OAuth app client secret. + 4. On the **Classic scopes** tab, choose **Edit Scopes**. Select the required classic scopes and choose **Save**. @@ -84 +63 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Token URL** \- Atlassian OAuth token endpoint. + 5. Choose the **Granular scopes** tab, then choose **Edit Scopes**. Select the required granular scopes and choose **Save**. @@ -86 +64,0 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Auth URL** \- Atlassian OAuth authorization endpoint. @@ -88 +65,0 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Redirect URL** \- OAuth redirect URI. @@ -90 +66,0 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **For Service authentication (API Key):** @@ -92 +68 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Base URL** \- Your Jira Cloud instance URL. +For the specific scopes required for your integration, see the scopes section that follows. @@ -94 +70 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **API Key** \- Your Jira API token. +### Configure API permissions @@ -96 +72 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - * **Email** \- Email address associated with your Jira user account. +Add the following scopes to your OAuth 2.0 app for the Jira Cloud action integration. @@ -98 +74 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - 6. Select **Create and continue**. +**Classic scopes** @@ -100 +76 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - 7. Select users to share the integration with. +On the **Classic scopes** tab, choose **Edit Scopes** and select the following scopes. @@ -102 +78,8 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. - 8. Click **Next**. +Jira action integration – classic scopes Scope | Description +---|--- +`read:jira-work` | Read Jira project and issue data, search for issues, and objects associated with issues like attachments and worklogs. +`manage:jira-project` | Create and edit project settings and create new project-level objects (for example, versions and components). +`manage:jira-configuration` | Take Jira administration actions (for example, create projects and custom fields, view workflows, manage issue link types). +`read:jira-user` | View user information in Jira that the user has access to, including usernames, email addresses, and avatars. +`write:jira-work` | Create and edit issues in Jira, post comments as the user, create worklogs, and delete issues. +`manage:jira-webhook` | Fetch, register, refresh, and delete dynamically declared Jira webhooks. @@ -103,0 +87 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. +**Granular scopes** @@ -104,0 +89 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. +Choose the **Granular scopes** tab, then choose **Edit Scopes**. Use the search bar to find the scopes below. For example, search for `sprint:jira-software` to find sprint-related scopes. @@ -105,0 +91,8 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. +Jira action integration – granular scopes Scope | Description +---|--- +`read:board-scope:jira-software` | Read board configurations. +`read:sprint:jira-software` | Read sprint information. +`write:sprint:jira-software` | Create and modify sprints. +`delete:sprint:jira-software` | Delete sprints. +`write:board-scope:jira-software` | Manage board configurations. +`read:project:jira` | Read project details. @@ -107 +100 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. -## Configure authentication +### Configure authorization @@ -109 +102 @@ Follow these steps to connect Amazon Quick to your Jira Cloud instance. -Jira Cloud integration supports two authentication methods. Choose the method that works best for your organization. +Set the callback URL so that Atlassian can redirect users back to Amazon Quick after they authorize the app. @@ -111 +104 @@ Jira Cloud integration supports two authentication methods. Choose the method th -**User authentication (OAuth)** + 1. From your app in the Atlassian Developer Console, choose **Authorization** in the left navigation. @@ -112,0 +106 @@ Jira Cloud integration supports two authentication methods. Choose the method th + 2. Next to **OAuth 2.0 (3LO)** , choose **Add**. @@ -114 +108 @@ Jira Cloud integration supports two authentication methods. Choose the method th -Use OAuth when you want actions to be performed under individual user identities. Configure these fields: + 3. For **Callback URLs** , enter `https://`region`.quicksight.aws.amazon.com/sn/oauthcallback`. Replace `region` with the AWS Region where your Amazon Quick instance is deployed, for example `us-east-1`. @@ -116 +110 @@ Use OAuth when you want actions to be performed under individual user identities - * **Base URL** \- Your Jira Cloud instance URL. + 4. Choose **Save changes**. @@ -118 +111,0 @@ Use OAuth when you want actions to be performed under individual user identities - * **Client ID** \- Your Atlassian OAuth app client ID. @@ -120 +112,0 @@ Use OAuth when you want actions to be performed under individual user identities - * **Client Secret** \- Your Atlassian OAuth app client secret. @@ -122 +113,0 @@ Use OAuth when you want actions to be performed under individual user identities - * **Token URL** \- Atlassian OAuth token endpoint. @@ -124 +115 @@ Use OAuth when you want actions to be performed under individual user identities - * **Auth URL** \- Atlassian OAuth authorization endpoint. +### Record your credentials @@ -126 +117 @@ Use OAuth when you want actions to be performed under individual user identities - * **Redirect URL** \- OAuth redirect URI. +Before you leave the Atlassian Developer Console, confirm that you have the following values. You need them for the Amazon Quick configuration. @@ -127,0 +119 @@ Use OAuth when you want actions to be performed under individual user identities + 1. From your app in the Atlassian Developer Console, choose **Settings** in the left navigation. @@ -128,0 +121 @@ Use OAuth when you want actions to be performed under individual user identities + 2. Under **Authentication details** , copy the **Client ID** and **Secret** values. @@ -131 +123,0 @@ Use OAuth when you want actions to be performed under individual user identities -**Required OAuth scopes:** @@ -133 +124,0 @@ Use OAuth when you want actions to be performed under individual user identities - * `read:jira-user` \- Read user information. @@ -135 +126,4 @@ Use OAuth when you want actions to be performed under individual user identities - * `read:jira-work` \- Read issues, projects, and work items. +Required credentials from Atlassian Developer Console Value | Where to find it +---|--- +Client ID | Settings page, under Authentication details +Secret | Settings page, under Authentication details @@ -137 +131 @@ Use OAuth when you want actions to be performed under individual user identities - * `write:jira-work` \- Create and modify issues and work items. +## Set up the integration in Amazon Quick @@ -139 +133 @@ Use OAuth when you want actions to be performed under individual user identities - * `manage:jira-project` \- Manage project settings. +After you prepare your authentication credentials, create the integration in Amazon Quick.