[MM-61756] Attribute Based Access Control - Phase 1 (#30785)

Attribute Based Access Control - Base
* MM-63662

* MM-63919

* MM-63954

* MM-63955 

* MM-63425

* MM-63426

* MM-63458

* MM-63459

* MM-63603

* MM-63845

* MM-64146

* MM-64199

* MM-64201

* MM-64233

* MM-64247

* MM-64268

---------

Co-authored-by: Harshil Sharma <harshilsharma63@gmail.com>
Co-authored-by: Pablo Andrés Vélez Vidal <pablovv2012@gmail.com>
Co-authored-by: abhijit-singh <abhijitsingh0702@gmail.com>
Co-authored-by: Harrison Healey <harrisonmhealey@gmail.com>

api/Makefile

@@ -60,6 +60,7 @@ build-v4: node_modules playbooks
 	@cat $(V4_SRC)/scheduled_post.yaml >> $(V4_YAML)
 	@cat $(V4_SRC)/custom_profile_attributes.yaml >> $(V4_YAML)
 	@cat $(V4_SRC)/audit_logging.yaml >> $(V4_YAML)
+	@cat $(V4_SRC)/access_control.yaml >> $(V4_YAML)
 	@if [ -r $(PLAYBOOKS_SRC)/paths.yaml ]; then cat $(PLAYBOOKS_SRC)/paths.yaml >> $(V4_YAML); fi
 	@if [ -r $(PLAYBOOKS_SRC)/merged-definitions.yaml ]; then cat $(PLAYBOOKS_SRC)/merged-definitions.yaml >> $(V4_YAML); else cat $(V4_SRC)/definitions.yaml >> $(V4_YAML); fi
 	@echo Extracting code samples

api/v4/source/access_control.yaml

@@ -0,0 +1,524 @@
+  /api/v4/access_control_policies:
+    put:
+      tags:
+        - access control
+      summary: Create an access control policy
+      description: |
+        Creates a new access control policy.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: CreateAccessControlPolicy
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccessControlPolicy"
+      responses:
+        "200":
+          description: Access control policy created successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPolicy"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/check:
+    post:
+      tags:
+        - access control
+      summary: Check an access control policy expression
+      description: |
+        Checks the syntax and validity of an access control policy expression.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: CheckAccessControlPolicyExpression
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                expression:
+                  type: string
+                  description: The expression to check.
+      responses:
+        "200":
+          description: Expression check result.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/ExpressionError"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/test:
+    post:
+      tags:
+        - access control
+      summary: Test an access control policy expression
+      description: |
+        Tests an access control policy expression against users to see who would be affected.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: TestAccessControlPolicyExpression
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/QueryExpressionParams"
+      responses:
+        "200":
+          description: Expression test result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPolicyTestResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/search:
+    post:
+      tags:
+        - access control
+      summary: Search access control policies
+      description: |
+        Searches for access control policies based on given criteria.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: SearchAccessControlPolicies
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AccessControlPolicySearch"
+      responses:
+        "200":
+          description: Search results for access control policies.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPoliciesWithCount"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/autocomplete/fields:
+    get:
+      tags:
+        - access control
+      summary: Get autocomplete fields for access control policies
+      description: |
+        Provides a list of fields that can be used for autocompletion when creating/editing access control policy expressions.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetAccessControlPolicyAutocompleteFields
+      parameters:
+        - name: after
+          in: query
+          description: The field ID to start after for pagination.
+          required: false
+          schema:
+            type: string
+        - name: limit
+          in: query
+          description: The maximum number of fields to return.
+          required: true
+          schema:
+            type: integer
+            default: 60
+      responses:
+        "200":
+          description: Autocomplete fields retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlFieldsAutocompleteResponse"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}":
+    get:
+      tags:
+        - access control
+      summary: Get an access control policy
+      description: |
+        Gets a specific access control policy by its ID.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          description: Access control policy retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccessControlPolicy"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+    delete:
+      tags:
+        - access control
+      summary: Delete an access control policy
+      description: |
+        Deletes an access control policy by its ID.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: DeleteAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      responses:
+        "200":
+          description: Access control policy deleted successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/activate":
+    get:
+      tags:
+        - access control
+      summary: Activate or deactivate an access control policy
+      description: |
+        Updates the active status of an access control policy.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: UpdateAccessControlPolicyActiveStatus
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      - name: active
+        in: query
+        description: Set to "true" to activate, "false" to deactivate.
+        required: true
+        schema:
+          type: boolean
+      responses:
+        "200":
+          description: Policy active status updated successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/assign":
+    post:
+      tags:
+        - access control
+      summary: Assign an access control policy to channels
+      description: |
+        Assigns an access control policy to a list of channels.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: AssignAccessControlPolicyToChannels
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                channel_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: The IDs of the channels to assign the policy to.
+      responses:
+        "200":
+          description: Policy assigned to channels successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/unassign":
+    delete:
+      tags:
+        - access control
+      summary: Unassign an access control policy from channels
+      description: |
+        Unassigns an access control policy from a list of channels.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: UnassignAccessControlPolicyFromChannels
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                channel_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: The IDs of the channels to unassign the policy from.
+      responses:
+        "200":
+          description: Policy unassigned from channels successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StatusOK"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/resources/channels":
+    get:
+      tags:
+        - access control
+      summary: Get channels for an access control policy
+      description: |
+        Retrieves a paginated list of channels to which a specific access control policy is applied.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetChannelsForAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      - name: after
+        in: query
+        description: The channel ID to start after for pagination.
+        required: false
+        schema:
+          type: string
+      - name: limit
+        in: query
+        description: The maximum number of channels to return.
+        required: true
+        schema:
+          type: integer
+          default: 60
+      responses:
+        "200":
+          description: Channels retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChannelsWithCount"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/access_control_policies/{policy_id}/resources/channels/search":
+    post:
+      tags:
+        - access control
+      summary: Search channels for an access control policy
+      description: |
+        Searches for channels associated with a specific access control policy based on search criteria.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: SearchChannelsForAccessControlPolicy
+      parameters:
+      - name: policy_id
+        in: path
+        description: The ID of the access control policy.
+        required: true
+        schema:
+          type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ChannelSearch"
+      responses:
+        "200":
+          description: Channel search results retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ChannelsWithCount"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  "/api/v4/channels/{channel_id}/access_control/attributes":
+    get:
+      tags:
+        - access control
+        - channels
+      summary: Get access control attributes for a channel
+      description: |
+        Retrieves the effective access control policy attributes for a specific channel.
+        This can be used to understand what attributes are currently being applied to the channel by the access control system.
+        ##### Permissions
+        Must have `read_channel` permission for the specified channel.
+      operationId: GetChannelAccessControlAttributes
+      parameters:
+        - name: channel_id
+          in: path
+          description: The ID of the channel.
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Access control attributes retrieved successfully.
+          content:
+            application/json:
+              schema:
+                type: object # Placeholder - define more specifically if the structure is known
+                additionalProperties: true
+                description: A map of attribute names to their values as applied to the channel.
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+  /api/v4/access_control_policies/cel/visual_ast:
+    post:
+      tags:
+        - access control
+      summary: Get the visual AST for a CEL expression
+      description: |
+        Retrieves the visual AST for a CEL expression.
+        ##### Permissions
+        Must have the `manage_system` permission.
+      operationId: GetCELVisualAST
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CELExpression"
+      responses:
+        "200":
+          description: Visual AST retrieved successfully.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/VisualExpression" 
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"

api/v4/source/definitions.yaml

@@ -174,8 +174,6 @@ components:
           type: string
         total_member_count:
           type: integer
-        active_member_count:
-          type: integer
     TeamExists:
       type: object
       properties:
@@ -3935,6 +3933,181 @@ components:
           description: Explains the error behind why a scheduled post could not have been sent
         metadata:
           $ref: "#/components/schemas/PostMetadata"
+    AccessControlFieldsAutocompleteResponse:
+      type: object
+      properties:
+        fields:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+                description: The name of the field.
+              description:
+                type: string
+                description: A description of the field.
+    AccessControlPoliciesWithCount:
+      type: object
+      properties:
+        policies:
+          type: array
+          items:
+            $ref: "#/components/schemas/AccessControlPolicy"
+        total_count:
+          type: integer
+          description: The total number of policies.
+    AccessControlPolicy:
+      type: object
+      properties:
+        id:
+          type: string
+          description: The unique identifier of the policy.
+        name:
+          type: string
+          description: The unique name for the policy.
+        display_name:
+          type: string
+          description: The human-readable name for the policy.
+        description:
+          type: string
+          description: A description of the policy.
+        expression:
+          type: string
+          description: The CEL expression defining the policy rules.
+        is_active:
+          type: boolean
+          description: Whether the policy is currently active and enforced.
+        create_at:
+          type: integer
+          format: int64
+          description: The time in milliseconds the policy was created.
+        update_at:
+          type: integer
+          format: int64
+          description: The time in milliseconds the policy was last updated.
+        delete_at:
+          type: integer
+          format: int64
+          description: The time in milliseconds the policy was deleted.
+    AccessControlPolicySearch:
+      type: object
+      properties:
+        term:
+          type: string
+          description: The search term to match against policy names or display names.
+        is_active:
+          type: boolean
+          description: Filter policies by active status.
+        page:
+          type: integer
+          description: The page number to return.
+        per_page:
+          type: integer
+          description: The number of policies to return per page.
+        # Add other potential search/filter fields like sort_by, sort_direction
+    AccessControlPolicyTestResponse:
+      type: object
+      properties:
+        users:
+          type: array
+          items:
+            $ref: "#/components/schemas/User"
+          description: A list of users affected by the policy expression.
+        total_count:
+          type: integer
+          description: The total number of users affected.
+    ChannelSearch: # Added based on dataretention.yaml and access_control.go usage
+      type: object
+      properties:
+        term:
+          type: string
+          description: The string to search in the channel name, display name, and purpose.
+        team_ids:
+          type: array
+          items:
+            type: string
+          description: Filters results to channels belonging to the given team ids.
+        public:
+          type: boolean
+          description: Filters results to only return Public / Open channels.
+        private:
+          type: boolean
+          description: Filters results to only return Private channels.
+        deleted:
+          type: boolean
+          description: Filters results to only return deleted / archived channels.
+        include_deleted:
+          type: boolean
+          description: Whether to include deleted channels in the search results.
+        # Add other potential search fields like not_associated_to_group, exclude_default_channels etc.
+    ChannelsWithCount: # Added based on access_control.go usage
+      type: object
+      properties:
+        channels:
+          $ref: "#/components/schemas/ChannelListWithTeamData" # Referencing existing type used in similar contexts
+        total_count:
+          type: integer
+          description: The total number of channels.
+    ExpressionError:
+      type: object
+      properties:
+        message:
+          type: string
+          description: The error message.
+        field:
+          type: string
+          description: The field related to the error, if applicable.
+        line:
+          type: integer
+          description: The line number where the error occurred in the expression.
+        column:
+          type: integer
+          description: The column number where the error occurred in the expression.
+    QueryExpressionParams:
+      type: object
+      properties:
+        expression:
+          type: string
+          description: The policy expression to test.
+        term:
+          type: string
+          description: A search term to filter users against whom the expression is tested.
+        limit:
+          type: integer
+          description: The maximum number of users to return.
+        after:
+          type: string
+          description: The ID of the user to start the test after (for pagination).
+    CELExpression:
+      type: object
+      properties:
+        expression:
+          type: string
+          description: The CEL expression to visualize.
+    VisualExpression:
+      type: object
+      properties:
+        conditions:
+          type: array
+          items:
+            $ref: "#/components/schemas/Condition"
+          description: The visual AST for the CEL expression
+    Condition:
+      type: object
+      properties:
+        attribute:
+          type: string
+          description: The attribute name.
+        operator:
+          type: string
+          description: The operator of a single condition.
+        value:
+          type: string
+          description: The value.
+        value_type:
+          type: string
+          description: The value type.
 externalDocs:
   description: Find out more about Mattermost
   url: 'https://about.mattermost.com'