AWS amazonq documentation change
Summary
Restructured documentation with expanded sections on Jira permissions inheritance, ACL mapping strategies for different project types, and failure handling. Added detailed explanations of Team-Managed vs Company-Managed project access controls and security considerations.
Security assessment
The changes document security-related features like ACL mapping, permission inheritance, and access control mechanisms, but there's no evidence of addressing a specific security vulnerability. The content explains existing security controls rather than patching weaknesses.
Diff
diff --git a/amazonq/latest/qbusiness-ug/jira-user-management.md b/amazonq/latest/qbusiness-ug/jira-user-management.md index 4fe60ddd4..296dff1b9 100644 --- a//amazonq/latest/qbusiness-ug/jira-user-management.md +++ b//amazonq/latest/qbusiness-ug/jira-user-management.md @@ -4,0 +5,2 @@ +ProjectsIdentity crawlingPermissions inheritanceACL mappingChange managementFailure handlingMore information + @@ -13 +15,7 @@ Jira organizes work into Projects, which serve as containers for Issues—the co -**Identity crawling** : The connector extracts project-level permissions based on the project key. It identifies direct users and group members, capturing their account IDs and emails. Federated groups, synchronized from external identity providers, appear as local groups in Jira but are managed externally. The connector respects Jira’s permission structure, ensuring that permissions remain intact even when users are removed and later reinstated. Suspended users are included in API responses but marked as inactive, preventing unauthorized access. +## Projects + +Jira organizes work into Projects, which serve as containers for Issues—the core tasks, bugs, or stories that teams track. Each issue belongs to a project and can have Comments, Attachments, and Worklogs to facilitate collaboration, provide context, and track time spent. Projects can be Team-Managed (private, limited, or open) or Company-Managed, offering flexibility in workflows and permissions. When you connect an Jira data source to Amazon Q Business, Amazon Q Business crawls ACL information attached to a document (user and group information) from your Jira instance. If you choose to activate ACL crawling, the information can be used to filter chat responses to your end user's document access level. + +## Identity crawling + +The Jira connector extracts project-level permissions based on the project key. It identifies direct users and group members, capturing their account IDs and emails. Federated groups, synchronized from external identity providers, appear as local groups in Jira but are managed externally. The connector respects Jira’s permission structure, ensuring that permissions remain intact even when users are removed and later reinstated. Suspended users are included in API responses but marked as inactive, preventing unauthorized access. @@ -19 +27,43 @@ For all types of projects, you must have at least 'Browse Projects' permissions -**Permissions Inheritance** : Global Permissions determine who can access the Jira instance and perform high-level actions. Project Permissions, governed by permission schemes, define user access within projects, such as viewing, editing, or assigning issues. In Company-Managed Projects, permissions flow from the Jira instance down to projects and further to issues, attachments, comments, and worklogs. Issue Security Schemes further restrict access to specific issues within a project. In Team-Managed Projects, access is defined by project roles and project visibility settings: Open (accessible to all), Limited (viewable by all but editable only by members), and Private (restricted to project members). While permissions in Company-Managed Projects follow a structured hierarchy, Team-Managed Projects rely on role-based access. Inheritance applies at the project level, meaning that issues, comments, attachments, and worklogs inherit permissions from their parent project. However, Issue Security Levels can override project permissions by restricting visibility at an issue level. +## Permissions inheritance + +Global Permissions determine who can access the Jira instance and perform high-level actions. Project Permissions, governed by permission schemes, define user access within projects, such as viewing, editing, or assigning issues. In Company-Managed projects, permissions flow from the Jira instance down to projects and further to issues, attachments, comments, and worklogs. Issue Security Schemes further restrict access to specific issues within a project. In Team-Managed projects, access is defined by project roles and project visibility settings: **Open** (accessible to all), **Limited** (viewable by all but editable only by members), and **Private** (restricted to project members). While permissions in Company-Managed projects follow a structured hierarchy, Team-Managed projects rely on role-based access. Inheritance applies at the project level, meaning that issues, comments, attachments, and worklogs inherit permissions from their parent project. However, Issue Security Levels can override project permissions by restricting visibility at an issue level. + +## ACL mapping + +Before enabling ACL-based document access for Jira within Amazon Q Business, it is important to understand how permissions and groups are mapped between Jira and Amazon Q, especially given the structural differences between Team-Managed and Company-Managed projects. + +**Team-Managed Projects** : For Team-Managed projects in Jira Software Cloud, ACL mapping is straightforward. The permissions for such projects are configured on the **Project Settings > Access** tab, where you will find a list of users and groups along with their associated project roles. For these projects, a single group is created in Amazon Q Business using the format `projectKey:[ProjectKey]` (for example, `projectKey:TestProject`). This group is attached to all documents under the project, including the project-level document, issues, comments, worklogs, and attachments. All users listed in the **Access** tab will have visibility into all project documents, regardless of their roles. + +**Company-Managed Projects** : Company-Managed projects offer more granular access control and therefore require a more complex mapping strategy. To determine document visibility, it is necessary to review two areas within the Jira project: + + * **Project Settings > People**, which lists users and groups along with their project roles. Inclusion in this list does not guarantee document access even for Administrator roles. + + * **Project Settings > Permissions** The **Browse Projects** permission governs who can view the project and its issues. This setting can include a variety of grant types, such as specific groups, project roles, individual users, or dynamic conditions like issue assignees. Ensure users have all necessary permissions listed in [ Prerequisites](amazonq/latest/qbusiness-ug/jira-prereqs.html). + + + + +Jira also supports issue-level security, which can override the broader **Browse Projects** settings by enforcing granular access rules on a per-issue basis. You need to consider this label during ACL mapping. + +Following is an example of how group mappings in Amazon Q Business for Company-Managed projects are established: + + * **Project** : A group named `TestProject` is created, comprising all users who have been granted **Browse Projects** permission, regardless of grant type. + + * **Issue-Level Document** : In the example issue `Test1`, group assignments depend on permissions: + + * * If a user gains access through project-level permissions, the group `ProjectBasedBrowseKey:Test` is used. + + * If access is granted through dynamic conditions such as the user being the assignee, the group `IssueBasedBrowseKey:Test1` is used. + + * If both types of access mechanisms exist, users may belong to both groups. + + * **Issue with Issue-Level Security Enabled** : Access requires both project/issue-based browse permissions and issue-specific security clearance. The condition becomes: `(ProjectBasedBrowseKey:Test OR IssueBasedBrowseKey:Test1) AND IssueLevelKey:Test1`. + + * **Comments, Attachments, and Worklog** s: These documents inherit the same access control as the associated issue. Therefore, the same issue-level logic applies.. + + + + +## Change management + +Change Log Mode in Amazon Q Business enables incremental updates by capturing modifications made to content in Jira. Instead of re-indexing all documents, it indexes only newly added, updated, or deleted items since the last crawl. Any changes to user or group access permissions are also recorded, ensuring accurate and up-to-date indexing. @@ -21 +71 @@ For all types of projects, you must have at least 'Browse Projects' permissions -**ACL Mapping** : ACL mapping rules differ between company-managed and team-managed projects. In company-managed projects, project permissions and issue-level security must be met for access. If issue-level security is disabled, only project-level permissions apply. In team-managed projects, users must meet specific conditions. Private projects require explicit role membership, while limited and open-access projects do not. The Jira connector inherits ACLs from parent entities without custom logic. The connector supports ACLs for both company-managed projects and open/limited access team-managed projects. Federated groups are treated as local groups after syncing, with no duplicate issues. Email visibility must be set to "Anyone" for user context filtering to work. Ownership does not translate to automatic access; access is granted at the project level. Admins do not need explicit ACLs on every document. Jira does not support explicit deny permissions, and shared links still require users to be part of the project. +## Failure handling @@ -23 +73 @@ For all types of projects, you must have at least 'Browse Projects' permissions -**Change Management** : Change Log Mode in Amazon Q Business enables incremental updates by capturing modifications made to content in Jira. Instead of re-indexing all documents, it indexes only newly added, updated, or deleted items since the last crawl. Any changes to user or group access permissions are also recorded, ensuring accurate and up-to-date indexing. +The Jira connector follows a fail-close approach, skipping documents from ingestion in case of API failures or permission-related issues. If a document has no ACLs attached and ACL enforcement is enabled by the admin, it will be ingested and made publicly accessible to configured users. @@ -25 +75 @@ For all types of projects, you must have at least 'Browse Projects' permissions -**Failure handling** : The connector follows a fail-close approach, skipping documents from ingestion in case of API failures or permission-related issues. Please note that if a document has no ACLs attached and ACL enforcement is enabled by the admin, it will be ingested and made publicly accessible to configured users. +## More information @@ -27 +77 @@ For all types of projects, you must have at least 'Browse Projects' permissions -For more information, see: +For more information about ACLs, see: @@ -44 +94 @@ To use the Amazon Web Services Documentation, Javascript must be enabled. Please -Using the AWS CloudFormation +Using AWS CloudFormation