AWS quick documentation change
Summary
Updated documentation for Atlassian Confluence Cloud knowledge base integration, adding detailed instructions for document-level access controls (ACLs), including requirements for Atlassian admin credentials, setup steps, and troubleshooting for ACL-related issues.
Security assessment
This change adds comprehensive documentation for a security feature (document-level access controls) that enables fine-grained authorization. It explains how to configure ACLs using admin credentials to ensure users only see answers from documents they're authorized to access in Confluence. The change enhances security documentation but doesn't indicate it's addressing a specific security vulnerability or incident.
Diff
diff --git a/quick/latest/userguide/confluence-knowledge-base.md b/quick/latest/userguide/confluence-knowledge-base.md index e44a95fdf..fb655e767 100644 --- a//quick/latest/userguide/confluence-knowledge-base.md +++ b//quick/latest/userguide/confluence-knowledge-base.md @@ -7 +7 @@ -Before you beginAuthenticationSet up the knowledge base integrationSupported content typesAccess controlsManage knowledge basesTroubleshoot +Before you beginSet up the knowledge base integrationSupported content typesManage knowledge basesTroubleshoot @@ -11 +11 @@ Before you beginAuthenticationSet up the knowledge base integrationSupported con -Use the Atlassian Confluence Cloud knowledge base integration to index Confluence content so that Amazon Quick agents can search and answer questions about it. +Use the Atlassian Confluence Cloud knowledge base integration to index Confluence content so that Amazon Quick agents can search and answer questions about it. Amazon Quick supports optional document-level access controls (ACLs) for Confluence knowledge bases. When enabled, users only see answers from documents they are authorized to access in Confluence. For more information, see [Document-level access controls](./confluence-kb-acl.html). @@ -17 +17 @@ Make sure you have the following before you set up the integration. - * Atlassian Confluence Cloud. + * An Atlassian Confluence Cloud instance. @@ -19 +19 @@ Make sure you have the following before you set up the integration. - * For subscription requirements, see [Set up integrations in the console](./integration-console-setup-process.html). + * For Quick subscription requirements, see [Set up integrations in the console](./integration-console-setup-process.html). @@ -24 +24 @@ Make sure you have the following before you set up the integration. -## Authentication +If you plan to enable document-level access controls, you must provide Atlassian admin credentials during setup. These credentials allow Amazon Quick to access all user and group information regardless of individual email visibility settings. Without admin credentials, the ACL option is not available during knowledge base creation. To provide admin credentials, you need the following from your Atlassian organization administrator: @@ -26 +26 @@ Make sure you have the following before you set up the integration. -For knowledge base integrations, Amazon Quick handles authentication through a popup flow during setup. Complete the following steps. + * **Atlassian admin API key** – An alphanumeric string generated in the Atlassian admin portal. @@ -28 +28 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 1. Complete the Confluence Cloud authentication popup that appears. + * **Organization ID (UUID)** – The unique identifier for your Atlassian organization. You can find this in your browser URL when signed in to the admin portal: `admin.atlassian.com/o/`orgId``. @@ -30 +30 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 2. Grant permissions for Amazon Quick to access your Confluence content. + * **Directory ID (UUID)** – The unique identifier for your user directory. Retrieve this value using the Atlassian Admin Workspace API. @@ -32 +31,0 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 3. Review and complete the authentication process. @@ -35,0 +35 @@ For knowledge base integrations, Amazon Quick handles authentication through a p +For detailed steps to obtain these credentials, see [Obtain Atlassian admin credentials](./confluence-kb-acl.html#confluence-kb-atlassian-admin-credentials). @@ -38,0 +39,4 @@ For knowledge base integrations, Amazon Quick handles authentication through a p +The setup wizard has three steps: authentication, knowledge base creation, and additional settings. + +### Authenticate your account + @@ -41 +45 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 2. Choose **Atlassian Confluence Cloud** and choose the Add (plus "+") button. + 2. Under **Knowledge** , choose **Atlassian Confluence Cloud** and choose the Add (plus "+") button. @@ -43 +47 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 3. In the **Create Confluence knowledge base** dialog, under **Connected account** , complete the following fields: + 3. In the **Create Confluence knowledge base** dialog, under **Authentication method** , choose an existing connected account from the **Name** dropdown, or choose **Add account** to create a new connection. @@ -45 +49 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - * **Name** – A descriptive name for your data access integration. + 4. If you are adding a new account, complete the following fields: @@ -47 +51 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - * **Confluence URL** – The URL of your Atlassian site (for example, ``your-site`.atlassian.net`). + * **Name** – A descriptive name for your connection. @@ -49 +53 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 4. Choose **Sign in** and complete the Confluence Cloud authentication flow in the popup window. + * **Description** (Optional) – Notes about the connection. @@ -51 +55 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 5. Under **Create knowledge base** , complete the following fields: + * **Confluence URL** – The URL of your Atlassian site (for example, `https://`your-site`.atlassian.net`). @@ -53 +57 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - * **Name** – A name for your knowledge base. + 5. (Optional) Under **ACL Management** , select **Use Atlassian admin credentials** to provide Atlassian admin credentials. When selected, enter the following: @@ -55 +59 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - * **Description** (Optional) – Notes about how the knowledge base will be used. + * **API key** – The Atlassian admin API key. @@ -57 +61 @@ For knowledge base integrations, Amazon Quick handles authentication through a p - 6. Under **Content** , paste the URLs of the Confluence spaces, blogs, or pages that you want to include. Choose **Add** after each URL. + * **OrganizationID (UUID)** – Your Atlassian organization ID. @@ -59 +63 @@ For knowledge base integrations, Amazon Quick handles authentication through a p -###### Note + * **Directory ID (UUID)** – Your Atlassian user directory ID. @@ -61 +65 @@ For knowledge base integrations, Amazon Quick handles authentication through a p -URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`space-key`/overview` are treated as page URLs. +###### Important @@ -63 +67 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa - 7. Choose **Create**. +Atlassian admin credentials are required to enable document-level access controls (ACLs) in **Additional settings**. Without admin credentials, the ACL option is disabled. Admin credentials cannot be added after the knowledge base is created. For steps to obtain these credentials, see [Obtain Atlassian admin credentials](./confluence-kb-acl.html#confluence-kb-atlassian-admin-credentials). @@ -64,0 +69 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa + 6. Choose **Next**. @@ -65,0 +71 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa + 7. Complete the Confluence Cloud authentication popup that appears. Review the requested permissions and choose **Accept** to authorize Amazon Quick to access your Confluence content. @@ -68 +73,0 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa -## Supported content types @@ -70 +74,0 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa - * Confluence pages and blog posts @@ -72 +76,11 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa - * Spaces content +### Create the knowledge base + + 1. Under **Create knowledge base** , enter a **Name** for your knowledge base. + + 2. (Optional) Enter a **Description** with notes about how the knowledge base will be used. + + 3. Under **Confluence URLs** , paste the URLs of the Confluence spaces, blogs, or pages that you want to include. Choose **Add** after each URL. + +###### Note + +URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`space-key`/overview` are treated as page URLs, not space URLs. To index an entire space, use the space URL without `/overview` (for example, `https://`company`.atlassian.net/wiki/spaces/`space-key``). @@ -74 +88 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa - * Page and blog attachments + 4. Choose **Next: Additional settings** to configure access controls and indexing options, or choose **Create** to create the knowledge base with default settings. @@ -79 +93,5 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa -## Access controls +### Configure additional settings + + 1. To enable document-level access controls, select **Control document access with ACLs**. This option is only available if you provided Atlassian admin credentials in **Authentication method**. When enabled, Amazon Quick syncs access control lists from Confluence and verifies each user's permissions at query time. For more information about how access controls work, see [Document-level access controls](./confluence-kb-acl.html). + +If you do not enable ACLs, access is controlled at the knowledge base level. Anyone who has access to the knowledge base can get insights from all of the content within it. When ACLs are enabled, access is controlled at the document level. Users who have access to the knowledge base only see answers from documents that they are authorized to access in Confluence. @@ -83 +101,31 @@ URLs that follow the structure `https://`company`.atlassian.net/wiki/spaces/`spa -Amazon Quick doesn't sync access control lists (ACLs) from data sources. When you create a knowledge base in Amazon Quick, by default, only you can get insights from the knowledge base. For shared content, you can provide access to different users and groups by updating the knowledge base permissions. +ACL management cannot be changed after the knowledge base is created. If you need to change this setting, you must create a new knowledge base. + +###### Note + +If you did not provide Atlassian admin credentials in **Authentication method** , this option is disabled. To enable ACLs, choose **Back** or cancel the wizard and start again with a connected account that includes admin credentials. + + 2. Under **Multi-media content, file size, and file patterns** , configure the following indexing options as needed: + + * **Visual content in documents** – Index visual content such as images and charts embedded in documents. + + * **Audio files** – Index audio file attachments. + + * **Video files** – Index video file attachments. + + * **Maximum single file size** – The maximum file size for individual attachments (default: 50 MB). + + 3. Choose **Create**. + + + + +## Supported content types + + * Confluence pages and blog posts + + * Page and blog post attachments + + + + +When you add a Confluence space URL, Amazon Quick crawls all pages and blog posts within that space. For supported attachment file types and size limits, see [File size and content limits](./knowledge-base-integrations.html#file-size-and-content-limits). @@ -112 +160 @@ For general knowledge base troubleshooting, including sync issues and missing do - * Clicking **Accept** in the consent dialog has no effect. + * Choosing **Accept** in the consent dialog has no effect. @@ -195,0 +244,20 @@ While user-installed apps are unblocked (Option 2), any user on the site can aut +### ACL-related issues + +**No results from ACL-enabled knowledge base** + + * Verify that the end user has signed in to Confluence when prompted during their first query. The sign-in is required for real-time permission verification. + + * Verify that the end user has access to the relevant Confluence content in their Confluence instance. + + + + +**Documents skipped during sync** + + * If sync reports show items with status SKIPPED, verify that the authenticating user has access to the Confluence spaces and pages included in the knowledge base. + + * For more information about verifying document access, see [Check document access (ACL verification)](./sync-reports-observability.html#sync-reports-acl-verification). + + + + @@ -204 +272 @@ Action integration -Atlassian Jira Cloud integration +Document-level access controls