From 2858e6eae78f57c4c25e819209672ec7b541f961 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 10 Jul 2025 14:08:58 -0400 Subject: [PATCH 1/8] New routes and updates for existing ones Added routes for compare/restore/remove operations on the deployed resources Included routes for override handling during the evaluation process Updated existing routes to reflect current set of possible response codes and changed payloads or returned structures Removing obsolete /version route --- specs/SHIELD.json | 681 +++++++++++++++++++++--- src/shield/TypeScript/package-lock.json | 4 +- src/shield/TypeScript/package.json | 2 +- 3 files changed, 609 insertions(+), 78 deletions(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index 77030ab..a95b147 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -95,6 +95,20 @@ "$ref": "#/components/schemas/SecurityClassList" } }, + "templateId": { + "description": "Reference to the specific configuration item that is deployed in the tenant.", + "in": "path", + "name": "templateId", + "required": true, + "schema": { + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "example": "42ff150d-2ff0-4b38-849e-fe6aa5eedb49" + } + }, "updateChannelName": { "description": "Name of the update channel that should be used when querying or downloading updates.", "in": "path", @@ -361,6 +375,263 @@ ], "type": "object" }, + "Deploy.ConfigurationTag": { + "title": "Deploy - Configuration Tag", + "description": "Definition of an object representing configuration tag used within architecture collections.", + "type": "object", + "properties": { + "advanced": { + "type": "boolean", + "description": "Flag indicating if additional challenges should be required before user can use this configuration item." + }, + "description": { + "type": "string", + "description": "Long form explanation what the tag is and/or does." + }, + "displayName": { + "type": "string", + "description": "Human friendly name of the config tag." + }, + "dependentTag": { + "type": "array", + "description": "List of configuration tags that are required to be selected if this one were to be selected. This property is primarily used for illustration to the end user or system.", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/Deploy.ConfigurationTag" + } + }, + "id": { + "type": "string", + "description": "Object ID of the config tag entity.", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + } + }, + "required": [ + "advanced", + "description", + "displayName", + "dependentTag", + "id" + ] + }, + "Deploy.ArchitectureData": { + "title": "Deploy - Architecture Data Record", + "description": "Collection of objects describing existing architectures available for selection.", + "type": "array", + "items": { + "description": "List of architecture tag objects with metadata to help UI present the information to the user.", + "type": "object", + "properties": { + "advanced": { + "type": "boolean", + "description": "Flag indicating if additional challenges should be required before user can select this architecture item." + }, + "configTagList": { + "type": "array", + "description": "List of configuration tags that are a part of this architecture.", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/Deploy.ConfigurationTag" + } + }, + "description": { + "type": "string", + "description": "Long form explanation what the architecture is and/or does." + }, + "displayName": { + "type": "string", + "description": "Human friendly name of the architecture tag." + }, + "id": { + "type": "string", + "description": "Object ID of the architecture tag entity.", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + } + }, + "required": [ + "advanced", + "configTagList", + "description", + "displayName", + "id" + ] + }, + "example": [ + { + "advanced": false, + "configTagList": [ + { + "advanced": false, + "description": "Default configuration that is applicable in most cases", + "displayName": "General Configuration", + "dependentTag": [], + "id": "7e4a2c9f-1b3d-4f6a-8e9c-2d5f3a7b6c1e" + } + ], + "description": "Default architecture that is applicable in most cases", + "displayName": "General Architecture", + "id": "2f6a1c9e-7b3d-4e8f-9a2c-5d1e3b7f4c6a" + }, + { + "advanced": true, + "configTagList": [ + { + "advanced": false, + "description": "Custom configuration to provision group container", + "displayName": "Custom Group", + "dependentTag": [], + "id": "3a9f2e1c-6b4d-4c7a-9f8e-1d2b5e3a7c6f" + }, + { + "advanced": true, + "description": "Custom configuration to create access policy", + "displayName": "Custom Policy", + "dependentTag": [ + { + "advanced": true, + "description": "Custom configuration to enable location control", + "displayName": "Location Control", + "dependentTag": [], + "id": "1b7e3c9a-4f2d-4a6e-9f8c-2d5a1b3f6c7e" + } + ], + "id": "6c3e1a9f-2b7d-4f8a-9e5c-1d4a3b7e6f2c" + } + ], + "description": "Custom architecture for discover process only", + "displayName": "Discover-only Architecture", + "id": "8c1f3a7e-2d4b-4f6a-9e5c-3b7d2a1f6c9e" + } + ] + }, + "Deploy.CompareResponse": { + "title": "Deploy - Compare Response Record", + "description": "Object with the details of the evaluation of the deployed infrastructure resources.", + "type": "object", + "properties": { + "invalid": { + "additionalProperties": { + "description": "String with details of the error response.", + "type": "string" + }, + "description": "Collection of the configuration items where request for resource data responded with an error.", + "type": "object" + }, + "lastRunTimestamp": { + "description": "Point in time expressed in ISO 8601 format when the evaluation results were generated. ", + "example": "2025-03-25T14:28:54Z", + "type": "string", + "format": "date-time", + "nullable": true + }, + "missing": { + "additionalProperties": { + "description": "String indicating name and description of the configuration item.", + "type": "string" + }, + "description": "Collection of the configuration items that are expected to be deployed but do not have resource reference id.", + "type": "object" + }, + "results": { + "additionalProperties": { + "items": { + "properties": { + "actions": { + "items": { + "type": "number" + }, + "description": "List of operations available to be performed on the entity.", + "type": "array", + "minItems": 1 + }, + "errorCode": { + "description": "Detailed information about the discrepancy for the entity.", + "type": "number" + }, + "path": { + "description": "Location in the object where evaluated property encountered an error.", + "type": "string" + } + }, + "type": "object", + "required": [ + "actions", + "errorCode", + "path" + ] + }, + "type": "array" + }, + "description": "Collection of the configuration items where discrepancies where found.", + "type": "object" + } + }, + "required": [ + "invalid", + "lastRunTimestamp", + "missing", + "results" + ], + "example": { + "invalid": { + "a14402b8-98c5-41e3-ba99-e5e1a536f68d": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found.", + "9af9209d-d191-4b42-9f65-dfd8b7882bba": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + }, + "lastRunTimestamp": "2025-03-25T14:28:54Z", + "missing": { + "78afd77c-c2a6-4328-9c61-b9fd44114823": "Microsoft.Policies.PowerToysMicrosoft.Policies.PowerToys - Version 0.86.0" + }, + "results": { + "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "groupPolicyUploadedLanguageFiles" + } + ], + "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "roleScopeTagIds/1" + } + ] + } + } + }, + "Deploy.PathIndicator": { + "title": "Deploy - Path Payload", + "description": "Payload with path data used in several endpoints", + "type": "object", + "properties": { + "path": { + "description": "Location of the target in the object structure of the configuration item flattened for predictable navigation.", + "type": "string", + "example": "/roleScopeTagIds" + } + }, + "required": [ + "path" + ] + }, "Discover.ExecutionStatus": { "title": "Discover - Status", "description": "Detailed status that indicates the current state of the Discover engine and its progress.", @@ -1114,7 +1385,7 @@ }, "description": "Deprive your threats of practical significance. Deploy the Securing Privilege Access architecture. All in a few seconds.", "title": "SHI Environment Lockdown and Defense", - "version": "3.0.4" + "version": "3.0.5" }, "openapi": "3.0.0", "paths": { @@ -1318,7 +1589,7 @@ }, "/Api/Update": { "get": { - "summary": "Check if an Update Is Pending", + "summary": "Checks if an Update Is Pending", "description": "Provides the state of the update engine. Where `true` means there is an update detected and `false` means there isn't an update available. This endpoint is available to all authorization levels.", "operationId": "/Api/Update/Get", "responses": { @@ -1340,7 +1611,7 @@ }, "/Api/Update/Check": { "get": { - "summary": "Check for a New Version", + "summary": "Checks for a New Version", "description": "Checks with data gateway and compares the reported version to the version that is locally installed. If there is a difference, a new update is marked as available. Always returns the latest version available on data gateway, even if that version is installed locally.\n\nThis endpoint requires the `Update.Read`, `Update.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Update/Check/Get", "responses": { @@ -1369,7 +1640,7 @@ }, "/Api/Update/Check/Channel/{Update Channel Name}": { "get": { - "summary": "Check for a New Version in Channel", + "summary": "Checks for a New Version in Channel", "description": "Checks with the SHI Data Gateway in the specified update channel and compares the reported version to the version that is locally installed. If there is a difference, a new update is marked as available. Always returns the latest version available on data gateway, even if that version is installed locally.\n\nThis endpoint requires the `Update.Read`, `Update.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Update/Check/Channel/UpdateChannelName/Get", "parameters": [ @@ -1438,7 +1709,7 @@ }, "/Api/Update/Upload": { "post": { - "summary": "Upload Custom Update Package", + "summary": "Uploads Custom Update Package", "description": "THIS API SHOULD ONLY BE USED IF INSTRUCTED BY SHI EMPLOYEES!\n\nUploads the specified ZIP package, validates signature and installs it if it matches. This ignores version numbers and will allow you to install the same version again if necessary.\n\nThis endpoint requires the `Update.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Update/Upload/Post", "requestBody": { @@ -1463,7 +1734,7 @@ }, "/Api/Discover/Status": { "get": { - "summary": "State of the Discover Module.", + "summary": "Returns State of the Discover Module", "description": "Provides a detailed breakdown of the current state of the discover module and it progress.\n\nThis endpoint requires the `Discover.Read`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Discover/Status/Get", "responses": { @@ -1485,7 +1756,7 @@ }, "/Api/Discover/Progress": { "get": { - "summary": "Current execution progress of the Discover module.", + "summary": "Returns Current Execution Progress of the Discover Module", "description": "Provides a detailed breakdown of the current progress of the discover module and it progress.\n\nThis endpoint requires the `Discover.Read`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Discover/Progress/Get", "responses": { @@ -1507,7 +1778,7 @@ }, "/Api/Discover/Report": { "get": { - "summary": "Start Discover's Report Generation", + "summary": "Starts Discover's Report Generation", "description": "Starts the Discover module's report collection engine to create a license report and upload it to the data gateway.\n\nThis endpoint requires the `Discover.Action.Run`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Discover/Report/Start", "responses": { @@ -1673,6 +1944,7 @@ }, "/Api/Deploy": { "get": { + "summary": "Gets the Current Status of the Infrastructure Deployment", "description": "Has the core infrastructure engine check if the config engine can initialize properly.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Deploy/Get", "responses": { @@ -1683,31 +1955,71 @@ "infra deployed": { "description": "All API calls should be available since the core infrastructure is deployed.", "summary": "Infrastructure is deployed", - "value": true + "value": { + "deployedArchitecture": "4a7f2e9c-1b3d-4c6a-9f8e-2d5b3e1a7c9f", + "deployedTags": [ + "5e2a9c1f-8b3d-4f6a-9e7c-2d1f3a6b4c8e", + "9c7f2e1a-3b6d-4a8e-9f5c-1d2a4b7e6c3f" + ], + "isDeploying": true + } }, "Infra not deployed": { "description": "Infrastructure is not deployed. Please run the deployment before attempting different API calls.", "summary": "Infrastructure is not deployed", - "value": false + "value": { + "deployedArchitecture": null, + "deployedTags": [], + "isDeploying": false + } } }, "schema": { - "type": "boolean" + "properties": { + "deployedArchitecture": { + "description": "Reference of the architecture type being deployed that defines what resources could be targeted.", + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "nullable": true + }, + "deployedTags": { + "description": "Collection of references to the groupings that list related or dependent resources to be deployed.", + "type": "array", + "items": { + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "minItems": 0 + }, + "isDeploying": { + "description": "Flag to indicate if process has started and ongoing (true) or not (false).", + "type": "boolean" + } + }, + "type": "object", + "required": [ + "deployedArchitecture", + "deployedTags", + "isDeploying" + ] } } }, "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" } }, - "summary": "Get the current status of the infrastructure deployment", "tags": [ - "Infrastructure Deployment" + "Deploy" ] }, "post": { + "summary": "Deploys the Core Infrastructure Architecture Specification", "description": "After the user consents, deploy the core security groups, scope tag, configurations and metadata.\n\nThis endpoint requires the `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Deploy/Post", "requestBody": { @@ -1723,68 +2035,100 @@ "description": "User did not agree to the terms and conditions. This post should not have been sent.", "summary": "User Did Not Consent", "value": { - "deploymentConsent": false + "deploymentConsent": false, + "architectureId": "3f9c1a2e-4b7e-4f5e-9c3e-8d2f7a1b6c9d", + "tagList": [ + "7a2e5b1f-9c4d-4e3a-8f1b-2d6c3e9a7f4e" + ], + "include": true } }, "User Consented": { "description": "User agreed to the terms and conditions and pressed the deploy button.", "summary": "User Consented", "value": { - "deploymentConsent": true + "deploymentConsent": true, + "architectureId": "1d4f9c7a-3e2b-4a6d-9f8e-7c2a1b5e3d9f", + "tagList": [ + "6b3e2f1a-8d9c-4f7e-9a3b-1c2d5e7f4a6b", + "9e1c3a7b-2f4d-4e6a-8c9f-3b7d1a5e2f6c" + ], + "include": false } } }, "schema": { "properties": { "deploymentConsent": { + "description": "Flag that indicates the end user has consented to deploying the architecture (`true`) or not (`false`).", + "type": "boolean" + }, + "architectureId": { + "description": "Reference of the architecture type being deployed that defines what resources could be targeted.", + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "tagList": { + "description": "Collection of references to the groupings that list related or dependent resources to be deployed.", + "type": "array", + "items": { + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "minItems": 0 + }, + "include": { + "description": "Flag to indicate if calculated resources should be included (true) or excluded (false) from the deploy.", "type": "boolean" } }, - "type": "object" + "type": "object", + "required": [ + "deploymentConsent", + "architectureId", + "tagList", + "include" + ] } } } }, "responses": { - "204": { - "content": { - "application/json": { - "examples": { - "Successful Deployment": { - "description": "When a deployment request is successfully executed, a boolean true is returned.", - "summary": "Successful Deployment", - "value": true - } - }, - "schema": { - "type": "boolean" - } - } - }, - "description": "OK" + "202": { + "description": "Request for deployment is accepted and process is running" }, - "401": { - "$ref": "#/components/responses/401" + "400": { + "description": "User information or choice are invalid for the operation" + }, + "409": { + "description": "Operation is already in progress" + }, + "503": { + "description": "System requirements have not been met!" } }, - "summary": "Deploy the core infrastructure architecture specification", "tags": [ - "Infrastructure Deployment" - ], - "security": [] + "Deploy" + ] } }, - "/Api/Deploy/Progress": { + "/Api/Deploy/Architecture": { "get": { - "summary": "Current execution progress of the Deploy module.", - "description": "Provides a detailed breakdown of the current progress of the deploy module and its sub-components, if any.\n\nThis endpoint requires the `Deploy.Read`, or the `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Progress/Get", + "summary": "Returns List of Available Architectures", + "description": "Retrieves the collection of possible architecture configurations to be deployed including all metadata accompanying these records.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Architecture/Get", "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Core.ProgressBar" + "$ref": "#/components/schemas/Deploy.ArchitectureData" } } }, @@ -1792,49 +2136,29 @@ } }, "tags": [ - "Infrastructure Deployment" + "Deploy" ] } }, - "/Api/Deploy/Version": { + "/Api/Deploy/Progress": { "get": { - "description": "Gets the version of the API server and the architecture version deployed as well as the supported version of the architecture spec from the server.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Version/Get", + "summary": "Returns Current Execution Progress of the Deploy Module", + "description": "Provides a detailed breakdown of the current progress of the deploy module and its sub-components, if any.\n\nThis endpoint requires the `Deploy.Read`, or the `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Progress/Get", "responses": { "200": { "content": { "application/json": { "schema": { - "properties": { - "apiVersion": { - "description": "Follows symantec versioning as laid out here: https://semver.org/. This number is the version of the API server.", - "example": "1.2.3", - "type": "string" - }, - "archSpecVersion": { - "description": "An incrementing number that describes the version of the architecture specification that the API supports.", - "example": 123, - "type": "number" - }, - "deployedArchVersion": { - "description": "The version of the architecture specification that is currently deployed.", - "example": 25, - "type": "number" - } - }, - "type": "object" + "$ref": "#/components/schemas/Core.ProgressBar" } } }, "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" } }, - "summary": "Gets the version of SHIELDs components", "tags": [ - "Infrastructure Deployment" + "Deploy" ] } }, @@ -2787,6 +3111,213 @@ "Marketplace" ] } + }, + "/Api/Deploy/Compare": { + "get": { + "summary": "Retrieves Cached Evaluation Results", + "description": "Returns results of the last performed comparison of the values in the existing resources and their original requested configurations. Resulting object consists of several categories and includes timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.Read`, or `Deploy.ReadWrite`, or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Compare/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.CompareResponse" + } + } + }, + "description": "OK" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Compare/Invoke": { + "post": { + "summary": "Requests to Run New Evaluation and Returns Results", + "description": "Resets all cached data and initiates process to compar the values in the existing resources and their original requested configurations. Returns resulting object split into several categories and including timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/DeployCompare/Invoke/Post", + "requestBody": { + "description": "No payload is expected or needed for this operation", + "content": { + "application/json": {} + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.CompareResponse" + } + } + }, + "description": "OK" + }, + "503": { + "description": "Deployed architecture is invalid or missing!" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Restore/{templateId}": { + "patch": { + "summary": "Restores the Details Of the Deployed Resource", + "description": "Calculates and applies a change to the deployed resource to restore original value from the entire configuration item or single property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Restore/:templateId/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/templateId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.PathIndicator" + } + } + } + }, + "responses": { + "204": { + "description": "Restoration of configuration item or its property is successful" + }, + "400": { + "description": "The body does not match expected format!" + }, + "404": { + "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Remove": { + "delete": { + "summary": "Removes All Provisioned Infrastructure Resources", + "description": "Deletes all resources in the tenant that were created during the initial deploy or any update operation since.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/DeployRemove/Delete", + "responses": { + "202": { + "description": "Request for removal is accepted and process initiated" + }, + "503": { + "description": "Deployed architecture is invalid or missing!" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Skip": { + "get": { + "summary": "Retrieves List of Existing Override Rules", + "description": "Retrieves the details of override property in the Settings Engine and returns list grouped by configuration item reference.\n\nThis endpoint requires `Deploy.Read`, or `Deploy.ReadWrite`, or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string", + "description": "Flat path representing entire item or specific nested property in the configuration item." + } + }, + "description": "Collection of references to configuration items (using templateId property as property name) and array of strings as value.", + "example": { + "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ + "/" + ], + "9c858901-8a57-4791-81fe-4c455b099bc9": [ + "/description", + "/name" + ] + } + } + } + }, + "description": "OK" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Skip/{templateId}": { + "post": { + "summary": "Records New Entry to Skip During Evaluation", + "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/:templateId/Post", + "parameters": [ + { + "$ref": "#/components/parameters/templateId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.PathIndicator" + } + } + } + }, + "responses": { + "204": { + "description": "Recorded successfully" + }, + "400": { + "description": "The body does not match expected format!" + } + }, + "tags": [ + "Deploy" + ] + }, + "delete": { + "summary": "Removes Existing Entry From Being Skipped", + "description": "Deletes the entry so it is no longer ignored during the evaluation process.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/:templateId/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/templateId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.PathIndicator" + } + } + } + }, + "responses": { + "204": { + "description": "Record has been removed successfully" + }, + "400": { + "description": "The body does not match expected format!" + } + }, + "tags": [ + "Deploy" + ] + } } }, "security": [ @@ -2830,8 +3361,8 @@ "name": "Marketplace" }, { - "description": "Checks the status and starts deployment of the core infrastructure.", - "name": "Infrastructure Deployment" + "description": "Collection of tasks to perform deploy or removal of the infrastructure entities, evaluate details of the resources, handle restoration steps, and support handling architecture/configuration choices from the user.", + "name": "Deploy" }, { "description": "Manage the updates for SHIELD and the policies deployed into the managed environment.", diff --git a/src/shield/TypeScript/package-lock.json b/src/shield/TypeScript/package-lock.json index 599d3bf..827ca61 100644 --- a/src/shield/TypeScript/package-lock.json +++ b/src/shield/TypeScript/package-lock.json @@ -1,12 +1,12 @@ { "name": "@shi-corp/sdk-shield", - "version": "3.0.4", + "version": "3.0.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@shi-corp/sdk-shield", - "version": "3.0.4", + "version": "3.0.5", "license": "MIT", "dependencies": { "@microsoft/kiota-authentication-azure": "~1.0.0-preview.93", diff --git a/src/shield/TypeScript/package.json b/src/shield/TypeScript/package.json index 89eb3bf..4a4f89c 100644 --- a/src/shield/TypeScript/package.json +++ b/src/shield/TypeScript/package.json @@ -1,6 +1,6 @@ { "name": "@shi-corp/sdk-shield", - "version": "3.0.4", + "version": "3.0.5", "type": "module", "main": "bin/index.js", "description": "SDK client used to interface with the SHIELD application.", From 264b296089270322809308d3774883f60610c9ac Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 17 Jul 2025 15:17:51 -0400 Subject: [PATCH 2/8] Enhancing descriptions for the Deploy operations Updating Get call to include another property being returned Adding Patch call for the tag handling and extra resource provisioning --- specs/SHIELD.json | 70 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index a95b147..6e84869 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -1957,6 +1957,7 @@ "summary": "Infrastructure is deployed", "value": { "deployedArchitecture": "4a7f2e9c-1b3d-4c6a-9f8e-2d5b3e1a7c9f", + "deployTagInclude": true, "deployedTags": [ "5e2a9c1f-8b3d-4f6a-9e7c-2d1f3a6b4c8e", "9c7f2e1a-3b6d-4a8e-9f5c-1d2a4b7e6c3f" @@ -1969,6 +1970,7 @@ "summary": "Infrastructure is not deployed", "value": { "deployedArchitecture": null, + "deployTagInclude": false, "deployedTags": [], "isDeploying": false } @@ -1985,6 +1987,10 @@ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "nullable": true }, + "deployTagInclude": { + "description": "Flag that indicates if the tag list has been set to be in inclusion mode (`true`) or exclusion mode (`false`).", + "type": "boolean" + }, "deployedTags": { "description": "Collection of references to the groupings that list related or dependent resources to be deployed.", "type": "array", @@ -2005,6 +2011,7 @@ "type": "object", "required": [ "deployedArchitecture", + "deployTagInclude", "deployedTags", "isDeploying" ] @@ -2116,6 +2123,69 @@ "tags": [ "Deploy" ] + }, + "patch": { + "summary": "Augments the list of tags set as deployed and provisions new resources", + "description": "Changes the list of tags based on include flags, calculates the list of matchings resources and deploys all the ones marked as not provisioned.\n\nThis endpoint requires the `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Patch", + "requestBody": { + "content": { + "application/json": { + "examples": { + "Invalid Request": { + "description": "User submits request with empty list.", + "summary": "Empty request", + "value": { + "tagList": [] + } + }, + "Acceptable Request": { + "description": "User provides one or more values for the list of tags.", + "summary": "Request with data", + "value": { + "tagList": [ + "f3b9c7e2-1a4d-4c2e-9f3e-8b6a1c2d9e7a", + "a7d2f1c4-3e8b-4b6f-9c1d-2f4e7a9b3c6d" + ] + } + } + }, + "schema": { + "type": "object", + "properties": { + "tagList": { + "type": "array", + "items": { + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "minItems": 1 + } + }, + "required": [ + "tagList" + ] + } + } + } + }, + "responses": { + "202": { + "description": "Request for changes is accepted and deployment of the additional resources is running" + }, + "400": { + "description": "User information is invalid/incomplete for the operation" + }, + "503": { + "description": "System requirements have not been met!" + } + }, + "tags": [ + "Deploy" + ] } }, "/Api/Deploy/Architecture": { From 481a6cbaa07650d66f7646e3bf174d3680718d01 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 17 Jul 2025 16:10:13 -0400 Subject: [PATCH 3/8] Changing output structures for Compare calls to reflect use of arrays to list records Compare and Compare/Invoke endpoints now return data as arrays instead of objects with dynamic property names --- specs/SHIELD.json | 213 ++++++++++++++++++++++++++++++---------------- 1 file changed, 140 insertions(+), 73 deletions(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index 6e84869..aebf3f4 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -516,12 +516,29 @@ "type": "object", "properties": { "invalid": { - "additionalProperties": { - "description": "String with details of the error response.", - "type": "string" - }, + "type": "array", "description": "Collection of the configuration items where request for resource data responded with an error.", - "type": "object" + "items": { + "type": "object", + "properties": { + "templateId": { + "type": "string", + "description": "Internal reference identifier of the resource.", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "message": { + "type": "string", + "description": "Text with the details of the error response." + } + }, + "required": [ + "templateId", + "message" + ] + } }, "lastRunTimestamp": { "description": "Point in time expressed in ISO 8601 format when the evaluation results were generated. ", @@ -531,45 +548,80 @@ "nullable": true }, "missing": { - "additionalProperties": { - "description": "String indicating name and description of the configuration item.", - "type": "string" - }, + "type": "array", "description": "Collection of the configuration items that are expected to be deployed but do not have resource reference id.", - "type": "object" + "items": { + "type": "object", + "properties": { + "templateId": { + "type": "string", + "description": "Internal reference identifier of the resource.", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "message": { + "type": "string", + "description": "Text containing details of the original configuration item definition." + } + }, + "required": [ + "templateId", + "message" + ] + } }, "results": { - "additionalProperties": { - "items": { - "properties": { - "actions": { - "items": { - "type": "number" + "type": "array", + "description": "Collection of the configuration items where discrepancies where found.", + "items": { + "type": "object", + "properties": { + "templateId": { + "type": "string", + "description": "Internal reference identifier of the resource.", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "variants": { + "type": "array", + "description": "List of individual parts of the resource where discrepancies were determined.", + "items": { + "type": "object", + "properties": { + "actions": { + "items": { + "type": "number" + }, + "description": "List of operations available to be performed on the entity.", + "type": "array", + "minItems": 1 + }, + "errorCode": { + "description": "Detailed information about the discrepancy for the entity.", + "type": "number" + }, + "path": { + "description": "Location in the object where evaluated property encountered an error.", + "type": "string" + } }, - "description": "List of operations available to be performed on the entity.", - "type": "array", - "minItems": 1 - }, - "errorCode": { - "description": "Detailed information about the discrepancy for the entity.", - "type": "number" - }, - "path": { - "description": "Location in the object where evaluated property encountered an error.", - "type": "string" + "required": [ + "actions", + "errorCode", + "path" + ] } - }, - "type": "object", - "required": [ - "actions", - "errorCode", - "path" - ] + } }, - "type": "array" - }, - "description": "Collection of the configuration items where discrepancies where found.", - "type": "object" + "required": [ + "templateId", + "variants" + ] + } } }, "required": [ @@ -579,42 +631,57 @@ "results" ], "example": { - "invalid": { - "a14402b8-98c5-41e3-ba99-e5e1a536f68d": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found.", - "9af9209d-d191-4b42-9f65-dfd8b7882bba": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." - }, + "invalid": [ + { + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + }, + { + "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", + "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + } + ], "lastRunTimestamp": "2025-03-25T14:28:54Z", - "missing": { - "78afd77c-c2a6-4328-9c61-b9fd44114823": "Microsoft.Policies.PowerToysMicrosoft.Policies.PowerToys - Version 0.86.0" - }, - "results": { - "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86": [ - { - "actions": [ - 2, - 3 - ], - "errorCode": 5, - "path": "displayName" - }, - { - "actions": [ - 2 - ], - "errorCode": 1, - "path": "groupPolicyUploadedLanguageFiles" - } - ], - "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4": [ - { - "actions": [ - 3 - ], - "errorCode": 3, - "path": "roleScopeTagIds/1" - } - ] - } + "missing": [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } + ], + "results": [ + { + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "groupPolicyUploadedLanguageFiles" + } + ] + }, + { + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "roleScopeTagIds/1" + } + ] + } + ] } }, "Deploy.PathIndicator": { From 2f26035fccb378ca6eb265d365aba3a11fbcf6ad Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 17 Jul 2025 16:24:28 -0400 Subject: [PATCH 4/8] Fixing typo Thanks copilot --- specs/SHIELD.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index aebf3f4..15b1559 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -574,7 +574,7 @@ }, "results": { "type": "array", - "description": "Collection of the configuration items where discrepancies where found.", + "description": "Collection of the configuration items where discrepancies were found.", "items": { "type": "object", "properties": { From b0c9a7b1f6ca1b21d9e977bfb0b0a928ec678b11 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Fri, 3 Oct 2025 13:20:53 -0400 Subject: [PATCH 5/8] Adding new endpoint Adding new endpoint to handle requests for list of configuration items Adjusting path on the request for the list of architectures --- specs/SHIELD.json | 189 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 187 insertions(+), 2 deletions(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index 75bbf57..244d5c3 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -684,6 +684,169 @@ ] } }, + "Deploy.ConfigurationItem": { + "title": "Deploy - Configuration Item List", + "description": "", + "type": "array", + "items": { + "description": "", + "type": "object", + "properties": { + "childDependencies": { + "type": "array", + "description": "List of Object IDs in UUID format that reference configuration items identified as entities dependent on the presence of the current item.", + "minItems": 0, + "items": { + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + } + }, + "compareFunction": { + "type": "string", + "description": "Name of the bound function to perform comparison action." + }, + "deployFunction": { + "type": "string", + "description": "Name of the bound function to perform deploy action." + }, + "groupTagList": { + "type": "array", + "description": "List of metadata tags that indicate which deployment sets the configuration item is compatible with.", + "minItems": 1, + "items": { + "type": "object", + "properties": { + "description": { + "type": "string", + "description": "Long form explanation what the tag is and/or does." + }, + "displayName": { + "type": "string", + "description": "Human friendly name of the tag." + }, + "tagId": { + "type": "string", + "description": "Object ID in the UUID format of the tag entity.", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + } + }, + "required": [ + "description", + "displayName", + "tagId" + ] + } + }, + "msCloudTypes": { + "type": "array", + "description": "List of Microsoft Sovereign Clouds the configuration items is compatible with.", + "minItems": 1, + "items": { + "type": "string" + } + }, + "parentDependencies": { + "type": "array", + "description": "List of Object IDs in UUID format that reference configuration items identified as entities which deploy and existence is required for the current item.", + "minItems": 0, + "items": { + "type": "string", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + } + }, + "removeFunction": { + "type": "string", + "description": "Name of the bound function to perform removal action." + }, + "restoreFunction": { + "type": "string", + "description": "Name of the bound function to perform restoration action." + }, + "templateId": { + "type": "string", + "description": "Internal Object ID in UUID format to uniquely identify this configuration item definition.", + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + }, + "urlPath": { + "type": "string", + "description": "Relative Graph Api path identifying where the resource to be located and managed." + } + }, + "required": [ + "childDependencies", + "compareFunction", + "deployFunction", + "groupTagList", + "msCloudTypes", + "parentDependencies", + "removeFunction", + "restoreFunction", + "templateId", + "urlPath" + ] + }, + "example": [ + { + "childDependencies": [ + "7e1a2b3c-4d5f-4a8b-9e6a-1c2b7f3d8e4a", + "9c2e7a1b-5d3f-4a8b-2c6e-7f1a3d9e8b5c" + ], + "compareFunction": "bound compareResource", + "deployFunction": "bound deployResource", + "groupTagList": [ + { + "description": "Collection of policies covering critical conditional access settings.", + "displayName": "Conditional Policy", + "tagId": "3b7e2a1c-4d5f-4a8b-9e6a-2c1b7f3d8e4a" + } + ], + "msCloudTypes": [ + "Public" + ], + "parentDependencies": [ + "8e6a1c2b-7f3d-4a8b-9c2e-5d3f7a1b2e4a" + ], + "removeFunction": "bound removeResource", + "restoreFunction": "bound restoreResource", + "templateId": "2a1c7e3b-5d4f-4a8b-9e6a-7f3d2b1c8e4a", + "urlPath": "/identity/conditionalAccess/policies" + }, + { + "childDependencies": [ + "1c2b5d3f-7a1b-4a8b-9e6a-2e4a3b7e8c5d" + ], + "compareFunction": "bound compareResourceCustom", + "deployFunction": "bound deployResourceCustom", + "groupTagList": [ + { + "description": "Principal containers that are used to provide assignments.", + "displayName": "Administrative Unit", + "tagId": "5d3f9c2e-7a1b-4a8b-2c6e-1a3d7e8b5c4a" + } + ], + "msCloudTypes": [ + "Public" + ], + "parentDependencies": [], + "removeFunction": "bound removeResource", + "restoreFunction": "bound restoreResource", + "templateId": "4a8b7e1a-2b3c-4d5f-9e6a-1c2b7f3d8e4a", + "urlPath": "/directory/administrativeUnits" + } + ] + }, "Deploy.PathIndicator": { "title": "Deploy - Path Payload", "description": "Payload with path data used in several endpoints", @@ -2303,11 +2466,11 @@ ] } }, - "/Api/Deploy/Architecture": { + "/Api/Deploy/Component/Architecture": { "get": { "summary": "Returns List of Available Architectures", "description": "Retrieves the collection of possible architecture configurations to be deployed including all metadata accompanying these records.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Architecture/Get", + "operationId": "/Api/Deploy/Component/Architecture/Get", "responses": { "200": { "content": { @@ -2325,6 +2488,28 @@ ] } }, + "/Api/Deploy/Component/ConfigurationItem": { + "get": { + "summary": "Returns List of Available Configuration Items", + "description": "Retrieves the collection of all existing configuration items with curated set of metadata.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Component/ConfigurationItem/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.ConfigurationItem" + } + } + }, + "description": "OK" + } + }, + "tags": [ + "Deploy" + ] + } + }, "/Api/Deploy/Progress": { "get": { "summary": "Returns Current Execution Progress of the Deploy Module", From 5126eb331e7232e6e117460db69a59c4e6519f78 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Mon, 6 Oct 2025 10:29:49 -0400 Subject: [PATCH 6/8] Remove reference for unnecessary properties Properties describing used plugins are not needed --- specs/SHIELD.json | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index 244d5c3..f669d82 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -704,14 +704,6 @@ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" } }, - "compareFunction": { - "type": "string", - "description": "Name of the bound function to perform comparison action." - }, - "deployFunction": { - "type": "string", - "description": "Name of the bound function to perform deploy action." - }, "groupTagList": { "type": "array", "description": "List of metadata tags that indicate which deployment sets the configuration item is compatible with.", @@ -763,14 +755,6 @@ "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" } }, - "removeFunction": { - "type": "string", - "description": "Name of the bound function to perform removal action." - }, - "restoreFunction": { - "type": "string", - "description": "Name of the bound function to perform restoration action." - }, "templateId": { "type": "string", "description": "Internal Object ID in UUID format to uniquely identify this configuration item definition.", @@ -786,13 +770,9 @@ }, "required": [ "childDependencies", - "compareFunction", - "deployFunction", "groupTagList", "msCloudTypes", "parentDependencies", - "removeFunction", - "restoreFunction", "templateId", "urlPath" ] @@ -803,8 +783,6 @@ "7e1a2b3c-4d5f-4a8b-9e6a-1c2b7f3d8e4a", "9c2e7a1b-5d3f-4a8b-2c6e-7f1a3d9e8b5c" ], - "compareFunction": "bound compareResource", - "deployFunction": "bound deployResource", "groupTagList": [ { "description": "Collection of policies covering critical conditional access settings.", @@ -818,8 +796,6 @@ "parentDependencies": [ "8e6a1c2b-7f3d-4a8b-9c2e-5d3f7a1b2e4a" ], - "removeFunction": "bound removeResource", - "restoreFunction": "bound restoreResource", "templateId": "2a1c7e3b-5d4f-4a8b-9e6a-7f3d2b1c8e4a", "urlPath": "/identity/conditionalAccess/policies" }, @@ -827,8 +803,6 @@ "childDependencies": [ "1c2b5d3f-7a1b-4a8b-9e6a-2e4a3b7e8c5d" ], - "compareFunction": "bound compareResourceCustom", - "deployFunction": "bound deployResourceCustom", "groupTagList": [ { "description": "Principal containers that are used to provide assignments.", @@ -840,8 +814,6 @@ "Public" ], "parentDependencies": [], - "removeFunction": "bound removeResource", - "restoreFunction": "bound restoreResource", "templateId": "4a8b7e1a-2b3c-4d5f-9e6a-1c2b7f3d8e4a", "urlPath": "/directory/administrativeUnits" } From ddae8b7843ed665a65707c426102546aec28f1c3 Mon Sep 17 00:00:00 2001 From: Pasha Zayko Date: Thu, 9 Oct 2025 15:05:37 -0400 Subject: [PATCH 7/8] Updating fields to satisfy version requirements Enhanced information presentation with elements expected in OpenApi spec v3.1 --- specs/SHIELD.json | 915 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 722 insertions(+), 193 deletions(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index ce36b53..2eb1fb1 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -163,7 +163,16 @@ "maxLength": 36, "minLength": 36, "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "example": "42ff150d-2ff0-4b38-849e-fe6aa5eedb49" + "examples": [ + "42ff150d-2ff0-4b38-849e-fe6aa5eedb49" + ] + }, + "examples": { + "valid template ID": { + "value": "7e2a1c3b-4d5f-4a8b-9e6a-2c1b7f3d8e4a", + "summary": "Example of a valid template ID", + "description": "An example of a correct template ID value in UUID format used in restoration and skip operations." + } } }, "updateChannelName": { @@ -573,15 +582,24 @@ "properties": { "advanced": { "type": "boolean", - "description": "Flag indicating if additional challenges should be required before user can use this configuration item." + "description": "Flag indicating if additional challenges should be required before user can use this configuration item.", + "examples": [ + false + ] }, "description": { "type": "string", - "description": "Long form explanation what the tag is and/or does." + "description": "Long form explanation what the tag is and/or does.", + "examples": [ + "This tag indicates specific collection and very important." + ] }, "displayName": { "type": "string", - "description": "Human friendly name of the config tag." + "description": "Human friendly name of the config tag.", + "examples": [ + "Important Collection" + ] }, "dependentTag": { "type": "array", @@ -589,7 +607,18 @@ "minItems": 0, "items": { "$ref": "#/components/schemas/Deploy.ConfigurationTag" - } + }, + "examples": [ + [ + { + "advanced": false, + "description": "This tag indicates specific collection and very important.", + "displayName": "Important Collection", + "dependentTag": [], + "id": "2c7e1a3b-5d4f-4a8b-9e6a-1c2b7f3d8e4a" + } + ] + ] }, "id": { "type": "string", @@ -597,7 +626,10 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "8b3e2a1c-7d4f-4a8b-9e6a-2c1b7f3d8e4a" + ] } }, "required": [ @@ -606,6 +638,15 @@ "displayName", "dependentTag", "id" + ], + "examples": [ + { + "advanced": true, + "description": "This tag indicates optional collection and can be skipped.", + "displayName": "Optional Collection", + "dependentTag": [], + "id": "4d1c7e2b-3a5f-4a8b-9e6a-7f2b3d1c9e45" + } ] }, "Deploy.ArchitectureData": { @@ -618,7 +659,10 @@ "properties": { "advanced": { "type": "boolean", - "description": "Flag indicating if additional challenges should be required before user can select this architecture item." + "description": "Flag indicating if additional challenges should be required before user can select this architecture item.", + "examples": [ + false + ] }, "configTagList": { "type": "array", @@ -626,15 +670,32 @@ "minItems": 0, "items": { "$ref": "#/components/schemas/Deploy.ConfigurationTag" - } + }, + "examples": [ + [ + { + "advanced": false, + "description": "Default configuration that is applicable in most cases", + "displayName": "General Configuration", + "dependentTag": [], + "id": "7e4a2c9f-1b3d-4f6a-8e9c-2d5f3a7b6c1e" + } + ] + ] }, "description": { "type": "string", - "description": "Long form explanation what the architecture is and/or does." + "description": "Long form explanation what the architecture is and/or does.", + "examples": [ + "Default architecture that is applicable in most cases" + ] }, "displayName": { "type": "string", - "description": "Human friendly name of the architecture tag." + "description": "Human friendly name of the architecture tag.", + "examples": [ + "General Architecture" + ] }, "id": { "type": "string", @@ -642,7 +703,10 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "2f6a1c9e-7b3d-4e8f-9a2c-5d1e3b7f4c6a" + ] } }, "required": [ @@ -651,54 +715,73 @@ "description", "displayName", "id" + ], + "examples": [ + { + "advanced": false, + "configTagList": [ + { + "advanced": false, + "description": "Default configuration that is applicable in most cases", + "displayName": "General Configuration", + "dependentTag": [], + "id": "7e4a2c9f-1b3d-4f6a-8e9c-2d5f3a7b6c1e" + } + ], + "description": "Default architecture that is applicable in most cases", + "displayName": "General Architecture", + "id": "2f6a1c9e-7b3d-4e8f-9a2c-5d1e3b7f4c6a" + } ] }, - "example": [ - { - "advanced": false, - "configTagList": [ - { - "advanced": false, - "description": "Default configuration that is applicable in most cases", - "displayName": "General Configuration", - "dependentTag": [], - "id": "7e4a2c9f-1b3d-4f6a-8e9c-2d5f3a7b6c1e" - } - ], - "description": "Default architecture that is applicable in most cases", - "displayName": "General Architecture", - "id": "2f6a1c9e-7b3d-4e8f-9a2c-5d1e3b7f4c6a" - }, - { - "advanced": true, - "configTagList": [ - { - "advanced": false, - "description": "Custom configuration to provision group container", - "displayName": "Custom Group", - "dependentTag": [], - "id": "3a9f2e1c-6b4d-4c7a-9f8e-1d2b5e3a7c6f" - }, - { - "advanced": true, - "description": "Custom configuration to create access policy", - "displayName": "Custom Policy", - "dependentTag": [ - { - "advanced": true, - "description": "Custom configuration to enable location control", - "displayName": "Location Control", - "dependentTag": [], - "id": "1b7e3c9a-4f2d-4a6e-9f8c-2d5a1b3f6c7e" - } - ], - "id": "6c3e1a9f-2b7d-4f8a-9e5c-1d4a3b7e6f2c" - } - ], - "description": "Custom architecture for discover process only", - "displayName": "Discover-only Architecture", - "id": "8c1f3a7e-2d4b-4f6a-9e5c-3b7d2a1f6c9e" - } + "examples": [ + [ + { + "advanced": false, + "configTagList": [ + { + "advanced": false, + "description": "Default configuration that is applicable in most cases", + "displayName": "General Configuration", + "dependentTag": [], + "id": "7e4a2c9f-1b3d-4f6a-8e9c-2d5f3a7b6c1e" + } + ], + "description": "Default architecture that is applicable in most cases", + "displayName": "General Architecture", + "id": "2f6a1c9e-7b3d-4e8f-9a2c-5d1e3b7f4c6a" + }, + { + "advanced": true, + "configTagList": [ + { + "advanced": false, + "description": "Custom configuration to provision group container", + "displayName": "Custom Group", + "dependentTag": [], + "id": "3a9f2e1c-6b4d-4c7a-9f8e-1d2b5e3a7c6f" + }, + { + "advanced": true, + "description": "Custom configuration to create access policy", + "displayName": "Custom Policy", + "dependentTag": [ + { + "advanced": true, + "description": "Custom configuration to enable location control", + "displayName": "Location Control", + "dependentTag": [], + "id": "1b7e3c9a-4f2d-4a6e-9f8c-2d5a1b3f6c7e" + } + ], + "id": "6c3e1a9f-2b7d-4f8a-9e5c-1d4a3b7e6f2c" + } + ], + "description": "Custom architecture for discover process only", + "displayName": "Discover-only Architecture", + "id": "8c1f3a7e-2d4b-4f6a-9e5c-3b7d2a1f6c9e" + } + ] ] }, "Deploy.CompareResponse": { @@ -718,25 +801,53 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "a14402b8-98c5-41e3-ba99-e5e1a536f68d" + ] }, "message": { "type": "string", - "description": "Text with the details of the error response." + "description": "Text with the details of the error response.", + "examples": [ + "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + ] } }, "required": [ "templateId", "message" + ], + "examples": [ + { + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + } ] - } + }, + "examples": [ + [ + { + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + }, + { + "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", + "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + } + ] + ] }, "lastRunTimestamp": { "description": "Point in time expressed in ISO 8601 format when the evaluation results were generated. ", - "example": "2025-03-25T14:28:54Z", - "type": "string", - "format": "date-time", - "nullable": true + "examples": [ + "2025-03-25T14:28:54Z" + ], + "type": [ + "string", + "null" + ], + "format": "date-time" }, "missing": { "type": "array", @@ -750,18 +861,38 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "78afd77c-c2a6-4328-9c61-b9fd44114823" + ] }, "message": { "type": "string", - "description": "Text containing details of the original configuration item definition." + "description": "Text containing details of the original configuration item definition.", + "examples": [ + "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + ] } }, "required": [ "templateId", "message" + ], + "examples": [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } ] - } + }, + "examples": [ + [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } + ] + ] }, "results": { "type": "array", @@ -775,7 +906,10 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86" + ] }, "variants": { "type": "array", @@ -785,95 +919,197 @@ "properties": { "actions": { "items": { - "type": "number" + "type": "number", + "examples": [ + 2 + ] }, "description": "List of operations available to be performed on the entity.", "type": "array", - "minItems": 1 + "minItems": 1, + "examples": [ + [ + 2, + 3 + ] + ] }, "errorCode": { "description": "Detailed information about the discrepancy for the entity.", - "type": "number" + "type": "number", + "examples": [ + 5 + ] }, "path": { "description": "Location in the object where evaluated property encountered an error.", - "type": "string" + "type": "string", + "examples": [ + "/displayName" + ] } }, "required": [ "actions", "errorCode", "path" + ], + "examples": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + } ] - } + }, + "examples": [ + [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + } + ] + ] } }, "required": [ "templateId", "variants" - ] - } - } - }, - "required": [ - "invalid", - "lastRunTimestamp", - "missing", - "results" - ], - "example": { - "invalid": [ - { - "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", - "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." - }, - { - "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", - "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." - } - ], - "lastRunTimestamp": "2025-03-25T14:28:54Z", - "missing": [ - { - "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", - "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" - } - ], - "results": [ - { - "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", - "variants": [ + ], + "examples": [ { - "actions": [ - 2, - 3 - ], - "errorCode": 5, - "path": "displayName" + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + } + ] }, { - "actions": [ - 2 - ], - "errorCode": 1, - "path": "groupPolicyUploadedLanguageFiles" + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "/roleScopeTagIds/1" + } + ] } ] }, - { - "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", - "variants": [ + "examples": [ + [ { - "actions": [ - 3 - ], - "errorCode": 3, - "path": "roleScopeTagIds/1" + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "/groupPolicyUploadedLanguageFiles" + } + ] + }, + { + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "/roleScopeTagIds/1" + } + ] } ] - } - ] - } + ] + } + }, + "required": [ + "invalid", + "lastRunTimestamp", + "missing", + "results" + ], + "examples": [ + { + "invalid": [ + { + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + }, + { + "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", + "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + } + ], + "lastRunTimestamp": "2025-03-25T14:28:54Z", + "missing": [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } + ], + "results": [ + { + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "/groupPolicyUploadedLanguageFiles" + } + ] + }, + { + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "/roleScopeTagIds/1" + } + ] + } + ] + } + ] }, "Deploy.ConfigurationItem": { "title": "Deploy - Configuration Item List", @@ -892,8 +1128,17 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" - } + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "7e1a2b3c-4d5f-4a8b-9e6a-1c2b7f3d8e4a" + ] + }, + "examples": [ + [ + "7e1a2b3c-4d5f-4a8b-9e6a-1c2b7f3d8e4a", + "9c2e7a1b-5d3f-4a8b-2c6e-7f1a3d9e8b5c" + ] + ] }, "groupTagList": { "type": "array", @@ -904,11 +1149,17 @@ "properties": { "description": { "type": "string", - "description": "Long form explanation what the tag is and/or does." + "description": "Long form explanation what the tag is and/or does.", + "examples": [ + "Collection of policies covering critical conditional access settings." + ] }, "displayName": { "type": "string", - "description": "Human friendly name of the tag." + "description": "Human friendly name of the tag.", + "examples": [ + "Conditional Policy" + ] }, "tagId": { "type": "string", @@ -916,23 +1167,50 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "3b7e2a1c-4d5f-4a8b-9e6a-2c1b7f3d8e4a" + ] } }, "required": [ "description", "displayName", "tagId" + ], + "examples": [ + { + "description": "Collection of policies covering critical conditional access settings.", + "displayName": "Conditional Policy", + "tagId": "3b7e2a1c-4d5f-4a8b-9e6a-2c1b7f3d8e4a" + } ] - } + }, + "examples": [ + [ + { + "description": "Collection of policies covering critical conditional access settings.", + "displayName": "Conditional Policy", + "tagId": "3b7e2a1c-4d5f-4a8b-9e6a-2c1b7f3d8e4a" + } + ] + ] }, "msCloudTypes": { "type": "array", "description": "List of Microsoft Sovereign Clouds the configuration items is compatible with.", "minItems": 1, "items": { - "type": "string" - } + "type": "string", + "examples": [ + "USGov" + ] + }, + "examples": [ + [ + "Public" + ] + ] }, "parentDependencies": { "type": "array", @@ -943,8 +1221,16 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" - } + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "8e6a1c2b-7f3d-4a8b-9c2e-5d3f7a1b2e4a" + ] + }, + "examples": [ + [ + "8e6a1c2b-7f3d-4a8b-9c2e-5d3f7a1b2e4a" + ] + ] }, "templateId": { "type": "string", @@ -952,11 +1238,17 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "2a1c7e3b-5d4f-4a8b-9e6a-7f3d2b1c8e4a" + ] }, "urlPath": { "type": "string", - "description": "Relative Graph Api path identifying where the resource to be located and managed." + "description": "Relative Graph Api path identifying where the resource to be located and managed.", + "examples": [ + "/identity/conditionalAccess/policies" + ] } }, "required": [ @@ -966,48 +1258,73 @@ "parentDependencies", "templateId", "urlPath" + ], + "examples": [ + { + "childDependencies": [ + "7e1a2b3c-4d5f-4a8b-9e6a-1c2b7f3d8e4a", + "9c2e7a1b-5d3f-4a8b-2c6e-7f1a3d9e8b5c" + ], + "groupTagList": [ + { + "description": "Collection of policies covering critical conditional access settings.", + "displayName": "Conditional Policy", + "tagId": "3b7e2a1c-4d5f-4a8b-9e6a-2c1b7f3d8e4a" + } + ], + "msCloudTypes": [ + "Public" + ], + "parentDependencies": [ + "8e6a1c2b-7f3d-4a8b-9c2e-5d3f7a1b2e4a" + ], + "templateId": "2a1c7e3b-5d4f-4a8b-9e6a-7f3d2b1c8e4a", + "urlPath": "/identity/conditionalAccess/policies" + } ] }, - "example": [ - { - "childDependencies": [ - "7e1a2b3c-4d5f-4a8b-9e6a-1c2b7f3d8e4a", - "9c2e7a1b-5d3f-4a8b-2c6e-7f1a3d9e8b5c" - ], - "groupTagList": [ - { - "description": "Collection of policies covering critical conditional access settings.", - "displayName": "Conditional Policy", - "tagId": "3b7e2a1c-4d5f-4a8b-9e6a-2c1b7f3d8e4a" - } - ], - "msCloudTypes": [ - "Public" - ], - "parentDependencies": [ - "8e6a1c2b-7f3d-4a8b-9c2e-5d3f7a1b2e4a" - ], - "templateId": "2a1c7e3b-5d4f-4a8b-9e6a-7f3d2b1c8e4a", - "urlPath": "/identity/conditionalAccess/policies" - }, - { - "childDependencies": [ - "1c2b5d3f-7a1b-4a8b-9e6a-2e4a3b7e8c5d" - ], - "groupTagList": [ - { - "description": "Principal containers that are used to provide assignments.", - "displayName": "Administrative Unit", - "tagId": "5d3f9c2e-7a1b-4a8b-2c6e-1a3d7e8b5c4a" - } - ], - "msCloudTypes": [ - "Public" - ], - "parentDependencies": [], - "templateId": "4a8b7e1a-2b3c-4d5f-9e6a-1c2b7f3d8e4a", - "urlPath": "/directory/administrativeUnits" - } + "examples": [ + [ + { + "childDependencies": [ + "7e1a2b3c-4d5f-4a8b-9e6a-1c2b7f3d8e4a", + "9c2e7a1b-5d3f-4a8b-2c6e-7f1a3d9e8b5c" + ], + "groupTagList": [ + { + "description": "Collection of policies covering critical conditional access settings.", + "displayName": "Conditional Policy", + "tagId": "3b7e2a1c-4d5f-4a8b-9e6a-2c1b7f3d8e4a" + } + ], + "msCloudTypes": [ + "Public" + ], + "parentDependencies": [ + "8e6a1c2b-7f3d-4a8b-9c2e-5d3f7a1b2e4a" + ], + "templateId": "2a1c7e3b-5d4f-4a8b-9e6a-7f3d2b1c8e4a", + "urlPath": "/identity/conditionalAccess/policies" + }, + { + "childDependencies": [ + "1c2b5d3f-7a1b-4a8b-9e6a-2e4a3b7e8c5d" + ], + "groupTagList": [ + { + "description": "Principal containers that are used to provide assignments.", + "displayName": "Administrative Unit", + "tagId": "5d3f9c2e-7a1b-4a8b-2c6e-1a3d7e8b5c4a" + } + ], + "msCloudTypes": [ + "Public" + ], + "parentDependencies": [], + "templateId": "4a8b7e1a-2b3c-4d5f-9e6a-1c2b7f3d8e4a", + "urlPath": "/directory/administrativeUnits" + } + ] ] }, "Deploy.PathIndicator": { @@ -1018,11 +1335,18 @@ "path": { "description": "Location of the target in the object structure of the configuration item flattened for predictable navigation.", "type": "string", - "example": "/roleScopeTagIds" + "examples": [ + "/roleScopeTagIds" + ] } }, "required": [ "path" + ], + "examples": [ + { + "path": "/roleScopeTagIds" + } ] }, "Discover.ExecutionStatus": { @@ -3187,9 +3511,18 @@ "format": "uuid", "maxLength": 36, "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$" + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "examples": [ + "f3b9c7e2-1a4d-4c2e-9f3e-8b6a1c2d9e7a" + ] }, - "minItems": 1 + "minItems": 1, + "examples": [ + [ + "f3b9c7e2-1a4d-4c2e-9f3e-8b6a1c2d9e7a", + "a7d2f1c4-3e8b-4b6f-9c1d-2f4e7a9b3c6d" + ] + ] } }, "required": [ @@ -3224,6 +3557,32 @@ "200": { "content": { "application/json": { + "examples": { + "Sample List of Available Architectures": { + "description": "Sample list of architecture records available to be deployed.", + "summary": "Available Architectures", + "value": [ + { + "id": "4a7f2e9c-1b3d-4c6a-9f8e-2d5b3e1a7c9f", + "name": "Standard Security Baseline", + "description": "Provides a standard security baseline for most organizations with core security groups, scope tags and configurations.", + "version": "1.0.0", + "isActive": true, + "createdAt": "2024-01-15T12:00:00Z", + "updatedAt": "2024-06-20T08:30:00Z" + }, + { + "id": "7e2a5b1f-9c4d-4e3a-8f1b-2d6c3e9a7f4e", + "name": "Enhanced Security Posture", + "description": "An enhanced security posture architecture with additional configurations and stricter access controls.", + "version": "2.1.0", + "isActive": true, + "createdAt": "2024-03-10T09:15:00Z", + "updatedAt": "2024-07-05T14:45:00Z" + } + ] + } + }, "schema": { "$ref": "#/components/schemas/Deploy.ArchitectureData" } @@ -3246,6 +3605,32 @@ "200": { "content": { "application/json": { + "examples": { + "Sample List of Available Configuration Items": { + "description": "Sample list of configuration item records available to be deployed.", + "summary": "Available Configuration Items", + "value": [ + { + "id": "5e2a9c1f-8b3d-4f6a-9e7c-2d1f3a6b4c8e", + "name": "Core Security Group", + "description": "A core security group that contains essential security roles and permissions.", + "type": "SecurityGroup", + "isActive": true, + "createdAt": "2024-02-20T10:00:00Z", + "updatedAt": "2024-05-15T11:30:00Z" + }, + { + "id": "9c7f2e1a-3b6d-4a8e-9f5c-1d2a4b7e6c3f", + "name": "Scope Tag - Confidential Data", + "description": "A scope tag designed to restrict access to confidential data resources.", + "type": "ScopeTag", + "isActive": true, + "createdAt": "2024-04-12T14:20:00Z", + "updatedAt": "2024-07-01T09:50:00Z" + } + ] + } + }, "schema": { "$ref": "#/components/schemas/Deploy.ConfigurationItem" } @@ -4861,6 +5246,65 @@ "200": { "content": { "application/json": { + "examples": { + "Response with Cached Data": { + "summary": "Example of the comparison results", + "description": "An example of the cached results from the previous comparison operation.", + "value": { + "invalid": [ + { + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + }, + { + "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", + "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + } + ], + "lastRunTimestamp": "2025-03-25T14:28:54Z", + "missing": [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } + ], + "results": [ + { + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "/groupPolicyUploadedLanguageFiles" + } + ] + }, + { + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "/roleScopeTagIds/1" + } + ] + } + ] + } + } + }, "schema": { "$ref": "#/components/schemas/Deploy.CompareResponse" } @@ -4889,6 +5333,65 @@ "200": { "content": { "application/json": { + "examples": { + "Response with New Data": { + "summary": "Example of the comparison results", + "description": "An example of the newly calculated results after performing comparison operation.", + "value": { + "invalid": [ + { + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + }, + { + "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", + "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + } + ], + "lastRunTimestamp": "2025-03-25T14:28:54Z", + "missing": [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } + ], + "results": [ + { + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "/groupPolicyUploadedLanguageFiles" + } + ] + }, + { + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "/roleScopeTagIds/1" + } + ] + } + ] + } + } + }, "schema": { "$ref": "#/components/schemas/Deploy.CompareResponse" } @@ -4967,25 +5470,51 @@ "200": { "content": { "application/json": { + "examples": { + "Example Response with Current Rules": { + "summary": "Example of the returned list of the skipped items", + "description": "An example of the list indicating configuration items and the properties that are designed to be ignored during the comparison operation.", + "value": { + "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ + "/" + ], + "9c858901-8a57-4791-81fe-4c455b099bc9": [ + "/description", + "/name" + ] + } + } + }, "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string", - "description": "Flat path representing entire item or specific nested property in the configuration item." - } + "description": "Flat path representing entire item or specific nested property in the configuration item.", + "examples": [ + "/description" + ] + }, + "examples": [ + [ + "/", + "/description" + ] + ] }, "description": "Collection of references to configuration items (using templateId property as property name) and array of strings as value.", - "example": { - "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ - "/" - ], - "9c858901-8a57-4791-81fe-4c455b099bc9": [ - "/description", - "/name" - ] - } + "examples": [ + { + "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ + "/" + ], + "9c858901-8a57-4791-81fe-4c455b099bc9": [ + "/description", + "/name" + ] + } + ] } } }, From 12f288dc9dc17236d671ecffc6e3f9609fe61fb2 Mon Sep 17 00:00:00 2001 From: Elliot Huffman Date: Tue, 14 Oct 2025 10:30:36 -0400 Subject: [PATCH 8/8] Polish Add missing route ("operationId": "/Api/Deploy/Remove/Get"). Move all the deploy operations next to each other so that the reading party doesn't have to bounce around the doc. Update permission wording. --- specs/SHIELD.json | 2203 +++++++++++++++++++++++---------------------- 1 file changed, 1119 insertions(+), 1084 deletions(-) diff --git a/specs/SHIELD.json b/specs/SHIELD.json index 2eb1fb1..ea95271 100644 --- a/specs/SHIELD.json +++ b/specs/SHIELD.json @@ -3647,7 +3647,7 @@ "/Api/Deploy/Progress": { "get": { "summary": "Returns Current Execution Progress of the Deploy Module", - "description": "Provides a detailed breakdown of the current progress of the deploy module and its sub-components, if any.\n\nThis endpoint requires the `Deploy.Read`, or the `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "description": "Provides a detailed breakdown of the current progress of the deploy module and its sub-components, if any.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", "operationId": "/Api/Deploy/Progress/Get", "responses": { "200": { @@ -3688,250 +3688,405 @@ ] } }, - "/Api/Defend/Intermediary/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { + "/Api/Deploy/Compare": { "get": { - "description": "Retrieves a list of all AVD intermediaries for the specified security class filter. Next links may be provided for pagination to allow for good performance on larger environments. If a nextLink is return, not all data was returned on this query and the next link can be sent back to the API to get the next page of data.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/Type/:securityClass/Offering/AVD/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/nextLink" - }, - { - "$ref": "#/components/parameters/search" - } - ], + "summary": "Retrieves Cached Evaluation Results", + "description": "Returns results of the last performed comparison of the values in the existing resources and their original requested configurations. Resulting object consists of several categories and includes timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.Read`, or `Deploy.ReadWrite`, or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Compare/Get", "responses": { "200": { "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" - }, "examples": { - "Paged AVD intermediaries": { - "summary": "Example paged AVD intermediary list", - "description": "An example paged AVD intermediary list returned that represents the current page of all AVD intermediary instances form the specified security class.", + "Response with Cached Data": { + "summary": "Example of the comparison results", + "description": "An example of the cached results from the previous comparison operation.", "value": { - "@odata.count": 1, - "@odata.nextLink": "1", - "value": [ + "invalid": [ { - "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "kind": "AVD", - "name": "Legacy Reach Back", - "securityClass": "Privileged", - "addressRangeCIDR": "172.16.1.0/24", - "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", - "index": 0, - "location": "East US 2", - "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", - "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + }, + { + "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", + "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + } + ], + "lastRunTimestamp": "2025-03-25T14:28:54Z", + "missing": [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } + ], + "results": [ + { + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "/groupPolicyUploadedLanguageFiles" + } + ] + }, + { + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "/roleScopeTagIds/1" + } + ] } ] } } + }, + "schema": { + "$ref": "#/components/schemas/Deploy.CompareResponse" } } }, "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "525": { - "$ref": "#/components/responses/525" } }, - "summary": "Retrieves all AVD Intermediary Instances", "tags": [ - "Intermediary" + "Deploy" ] } }, - "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { - "delete": { - "description": "Deletes the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" + "/Api/Deploy/Compare/Invoke": { + "post": { + "summary": "Requests to Run New Evaluation and Returns Results", + "description": "Resets all cached data and initiates process to compar the values in the existing resources and their original requested configurations. Returns resulting object split into several categories and including timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/DeployCompare/Invoke/Post", + "requestBody": { + "description": "No payload is expected or needed for this operation", + "content": { + "application/json": {} } - ], + }, "responses": { - "204": { - "description": "OK: Deleted successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" + "200": { + "content": { + "application/json": { + "examples": { + "Response with New Data": { + "summary": "Example of the comparison results", + "description": "An example of the newly calculated results after performing comparison operation.", + "value": { + "invalid": [ + { + "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", + "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." + }, + { + "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", + "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." + } + ], + "lastRunTimestamp": "2025-03-25T14:28:54Z", + "missing": [ + { + "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", + "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" + } + ], + "results": [ + { + "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", + "variants": [ + { + "actions": [ + 2, + 3 + ], + "errorCode": 5, + "path": "/displayName" + }, + { + "actions": [ + 2 + ], + "errorCode": 1, + "path": "/groupPolicyUploadedLanguageFiles" + } + ] + }, + { + "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", + "variants": [ + { + "actions": [ + 3 + ], + "errorCode": 3, + "path": "/roleScopeTagIds/1" + } + ] + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/Deploy.CompareResponse" + } + } + }, + "description": "OK" }, - "525": { - "$ref": "#/components/responses/525" + "503": { + "description": "Deployed architecture is invalid or missing!" } }, - "summary": "Deletes a Single AVD Intermediary Instance", "tags": [ - "Intermediary" + "Deploy" ] - }, + } + }, + "/Api/Deploy/Skip": { "get": { - "description": "Retrieves the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - } - ], + "summary": "Retrieves List of Existing Override Rules", + "description": "Retrieves the details of override property in the Settings Engine and returns list grouped by configuration item reference.\n\nThis endpoint requires `Deploy.Read`, or `Deploy.ReadWrite`, or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/Get", "responses": { "200": { "content": { "application/json": { - "schema": { - "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" - }, "examples": { - "Paged AVD intermediary result": { - "summary": "Example paged result of a AVD intermediary list", - "description": "An example paged result that represents the current page of retrieved AVD intermediary list from a parent group filtered by specified class.", + "Example Response with Current Rules": { + "summary": "Example of the returned list of the skipped items", + "description": "An example of the list indicating configuration items and the properties that are designed to be ignored during the comparison operation.", "value": { - "@odata.count": 1, - "@odata.nextLink": "1", - "value": [ - { - "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "kind": "AVD", - "name": "Legacy Reach Back", - "securityClass": "Privileged", - "addressRangeCIDR": "172.16.1.0/24", - "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", - "index": 0, - "location": "East US 2", - "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", - "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } + "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ + "/" + ], + "9c858901-8a57-4791-81fe-4c455b099bc9": [ + "/description", + "/name" ] } } + }, + "schema": { + "type": "object", + "additionalProperties": { + "type": "array", + "items": { + "type": "string", + "description": "Flat path representing entire item or specific nested property in the configuration item.", + "examples": [ + "/description" + ] + }, + "examples": [ + [ + "/", + "/description" + ] + ] + }, + "description": "Collection of references to configuration items (using templateId property as property name) and array of strings as value.", + "examples": [ + { + "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ + "/" + ], + "9c858901-8a57-4791-81fe-4c455b099bc9": [ + "/description", + "/name" + ] + } + ] } } }, "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" } }, - "summary": "Retrieves a Single AVD Intermediary Instance", "tags": [ - "Intermediary" + "Deploy" ] } }, - "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign": { - "delete": { - "description": "Removes the specified user(s) as identified by their Object ID from the AVD cluster and deletes their corresponding session host(s).\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Delete", + "/Api/Deploy/Skip/{templateId}": { + "post": { + "summary": "Records New Entry to Skip During Evaluation", + "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/:templateId/Post", "parameters": [ { - "$ref": "#/components/parameters/securityClass" + "$ref": "#/components/parameters/templateId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.PathIndicator" + } + } + } + }, + "responses": { + "204": { + "description": "Recorded successfully" }, + "400": { + "description": "The body does not match expected format!" + } + }, + "tags": [ + "Deploy" + ] + }, + "delete": { + "summary": "Removes Existing Entry From Being Skipped", + "description": "Deletes the entry so it is no longer ignored during the evaluation process.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Skip/:templateId/Delete", + "parameters": [ { - "$ref": "#/components/parameters/intermediaryId" + "$ref": "#/components/parameters/templateId" } ], "requestBody": { "content": { "application/json": { - "examples": { - "One user": { - "description": "Removes 1 session host, and removed the requested user from the assignments security group.", - "summary": "Remove Single User", - "value": { - "userList": [ - "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" - ] - } - }, - "Two users": { - "description": "Removes 3 session hosts, and removed the requested users from the assignments security group.", - "summary": "Remove Multiple Users", - "value": { - "userList": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc", - "dd27937c-6287-45b3-98de-387725b068f3", - "989d3dc1-43f4-4ff7-82ba-43661f94a428" - ] - } - } - }, "schema": { - "properties": { - "userList": { - "items": { - "format": "uuid", - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" - }, - "type": "array" - } - }, - "type": "object" + "$ref": "#/components/schemas/Deploy.PathIndicator" + } + } + } + }, + "responses": { + "204": { + "description": "Record has been removed successfully" + }, + "400": { + "description": "The body does not match expected format!" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Restore/{templateId}": { + "patch": { + "summary": "Restores the Details Of the Deployed Resource", + "description": "Calculates and applies a change to the deployed resource to restore original value from the entire configuration item or single property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Restore/:templateId/Patch", + "parameters": [ + { + "$ref": "#/components/parameters/templateId" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Deploy.PathIndicator" } } } }, "responses": { "204": { - "description": "OK: Deleted successfully" + "description": "Restoration of configuration item or its property is successful" }, - "401": { - "$ref": "#/components/responses/401" + "400": { + "description": "The body does not match expected format!" }, "404": { "$ref": "#/components/responses/404" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Deploy/Remove": { + "get": { + "summary": "Indicates if the Remove Function Can Be Ran", + "description": "Provides a flag that indicates if the core infrastructure removal command can be ran or not.\n\nThis endpoint requires the `Deploy.Read`, `Deploy.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Deploy/Remove/Get", + "responses": { + "200": { + "content": { + "application/json": { + "schema": { + "type": "boolean" + }, + "examples": { + "Remove Ready": { + "value": true, + "summary": "Removal Ready", + "description": "Flag that indicates that no dependent components are present and the core infra can be removed." + }, + "Remove Not Ready": { + "value": false, + "summary": "Removal Not Ready", + "description": "Flag that indicates that dependent components are present and the core infra should not be removed." + } + } + } + }, + "description": "OK" }, - "525": { - "$ref": "#/components/responses/525" + "503": { + "description": "Deployed architecture is invalid or missing!" } }, - "summary": "Removes the assignment of the specified users", "tags": [ - "Intermediary" + "Deploy" ] }, + "delete": { + "summary": "Removes All Provisioned Infrastructure Resources", + "description": "Deletes all resources in the tenant that were created during the initial deploy or any update operation since.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/DeployRemove/Delete", + "responses": { + "202": { + "description": "Request for removal is accepted and process initiated" + }, + "503": { + "description": "Deployed architecture is invalid or missing!" + } + }, + "tags": [ + "Deploy" + ] + } + }, + "/Api/Defend/Intermediary/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { "get": { - "description": "Gets the list of assigned user from the specified AVD Intermediary.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Get", + "description": "Retrieves a list of all AVD intermediaries for the specified security class filter. Next links may be provided for pagination to allow for good performance on larger environments. If a nextLink is return, not all data was returned on this query and the next link can be sent back to the API to get the next page of data.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/Type/:securityClass/Offering/AVD/Get", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { - "$ref": "#/components/parameters/intermediaryId" + "$ref": "#/components/parameters/nextLink" }, { - "$ref": "#/components/parameters/nextLink" + "$ref": "#/components/parameters/search" } ], "responses": { @@ -3939,65 +4094,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ObjectPage.ManagedUser" + "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" }, "examples": { - "Managed user page": { - "summary": "Example paged user result", - "description": "An example of paged user result that represents the current page of assigned user list retrieved from the specified AVD intermediary.", + "Paged AVD intermediaries": { + "summary": "Example paged AVD intermediary list", + "description": "An example paged AVD intermediary list returned that represents the current page of all AVD intermediary instances form the specified security class.", "value": { - "@odata.count": 3, - "@odata.nextLink": "2", + "@odata.count": 1, + "@odata.nextLink": "1", "value": [ { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - }, - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "deviceAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", - "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", - "temporaryAccessPass": "BCKTSN#E2R&5" + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" } ] } @@ -4010,128 +4129,31 @@ "401": { "$ref": "#/components/responses/401" }, - "404": { - "$ref": "#/components/responses/404" - }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "List all assigned users (paginated)", + "summary": "Retrieves all AVD Intermediary Instances", "tags": [ - "Intermediary" - ] - }, - "post": { - "description": "Assigns the specified user(s) as identified by their Object ID to the AVD cluster and create corresponding session host(s) for them.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Post", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/intermediaryId" - } - ], - "requestBody": { - "content": { - "application/json": { - "examples": { - "One user": { - "description": "Creates 1 session host, and added the requested user to the assignments security group.", - "summary": "Assign Single User", - "value": { - "userList": [ - "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" - ] - } - }, - "Two users": { - "description": "Creates 3 session hosts, and added the requested users to the assignments security group.", - "summary": "Assign Multiple Users", - "value": { - "userList": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc", - "dd27937c-6287-45b3-98de-387725b068f3", - "989d3dc1-43f4-4ff7-82ba-43661f94a428" - ] - } - } - }, - "schema": { - "properties": { - "userList": { - "items": { - "format": "uuid", - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string", - "examples": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc" - ] - }, - "type": "array", - "examples": [ - [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc" - ] - ] - } - }, - "type": "object", - "examples": [ - { - "userList": [ - "0c56b055-9042-4f54-8e6e-6510e12a81dc" - ] - } - ] - } - } - } - }, - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/ManagedObject.User" - }, - "minItems": 0, - "type": "array" - }, - "examples": { - "Managed user": { - "summary": "Example managed users returned", - "description": "An example of managed user array returned that represents the users has been assigned to the specified AVD cluster and created corresponding session host successfully.", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - ] - } - } - } - }, - "description": "OK" + "Intermediary" + ] + } + }, + "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f": { + "delete": { + "description": "Deletes the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + } + ], + "responses": { + "204": { + "description": "OK: Deleted successfully" }, "401": { "$ref": "#/components/responses/401" @@ -4143,25 +4165,20 @@ "$ref": "#/components/responses/525" } }, - "summary": "Assigns the list of specified users", + "summary": "Deletes a Single AVD Intermediary Instance", "tags": [ "Intermediary" ] - } - }, - "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign/{userId}": { + }, "get": { - "description": "Get the specified managed user(s) from the specified AVD intermediary assignment list.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/:userId/Get", + "description": "Retrieves the specified intermediary (by the parent group's Entra ID Object ID) using the requested security class as a filter.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Get", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { "$ref": "#/components/parameters/intermediaryId" - }, - { - "$ref": "#/components/parameters/userId" } ], "responses": { @@ -4169,65 +4186,29 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ObjectPage.ManagedUser" + "$ref": "#/components/schemas/ObjectPage.Intermediary.Avd" }, "examples": { - "Assigned users": { - "summary": "Example assigned user list", - "description": "An example paged assigned user list that represents the current page retrieved from specified AVD intermediary assignment list.", + "Paged AVD intermediary result": { + "summary": "Example paged result of a AVD intermediary list", + "description": "An example paged result that represents the current page of retrieved AVD intermediary list from a parent group filtered by specified class.", "value": { - "@odata.count": 3, - "@odata.nextLink": "2", + "@odata.count": 1, + "@odata.nextLink": "1", "value": [ { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - }, - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "deviceAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", - "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", - "temporaryAccessPass": "BCKTSN#E2R&5" + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" } ] } @@ -4247,41 +4228,45 @@ "$ref": "#/components/responses/525" } }, - "summary": "Get a specific assigned user", + "summary": "Retrieves a Single AVD Intermediary Instance", "tags": [ "Intermediary" ] } }, - "/Api/Defend/Device/{deviceId}/Type/Privileged/Assign": { + "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign": { "delete": { - "description": "Remove the specified user list from the device.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Delete", + "description": "Removes the specified user(s) as identified by their Object ID from the AVD cluster and deletes their corresponding session host(s).\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Delete", "parameters": [ { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" } ], "requestBody": { "content": { "application/json": { "examples": { - "Multiple Users": { - "description": "Remove multiple user assignments from a managed device.", - "summary": "Unassign multiple users", + "One user": { + "description": "Removes 1 session host, and removed the requested user from the assignments security group.", + "summary": "Remove Single User", "value": { "userList": [ - "0674276a-31e8-4773-8ed9-6fb49dbd0fa8", - "66714224-b1a6-4fd6-b9d8-5263fdf755fc" + "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" ] } }, - "Single User": { - "description": "Remove a single user assignment from a managed device.", - "summary": "Unassign one user", + "Two users": { + "description": "Removes 3 session hosts, and removed the requested users from the assignments security group.", + "summary": "Remove Multiple Users", "value": { "userList": [ - "01ebf268-cf28-4607-954a-261dfd480453" + "0c56b055-9042-4f54-8e6e-6510e12a81dc", + "dd27937c-6287-45b3-98de-387725b068f3", + "989d3dc1-43f4-4ff7-82ba-43661f94a428" ] } } @@ -4290,95 +4275,49 @@ "properties": { "userList": { "items": { - "examples": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ], "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", "type": "string" }, - "type": "array", - "examples": [ - [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ] - ] + "type": "array" } }, - "type": "object", - "examples": [ - { - "userList": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ] - } - ] + "type": "object" } } } }, "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "items": { - "$ref": "#/components/schemas/ManagedObject.User" - }, - "minItems": 0, - "type": "array" - }, - "examples": { - "Removed user list": { - "summary": "Example removed user list", - "description": "An example array of ManagedObject.User that represents those removed from specific privileged device assignment.", - "value": [ - { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } - ] - } - } - } - }, - "description": "OK" + "204": { + "description": "OK: Deleted successfully" }, "401": { "$ref": "#/components/responses/401" }, + "404": { + "$ref": "#/components/responses/404" + }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "Remove User Assignments", + "summary": "Removes the assignment of the specified users", "tags": [ - "Device Management" + "Intermediary" ] }, "get": { - "description": "Lists all of the users that are currently assigned to the specified device.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Get", + "description": "Gets the list of assigned user from the specified AVD Intermediary.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Get", "parameters": [ { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" + }, + { + "$ref": "#/components/parameters/nextLink" } ], "responses": { @@ -4389,9 +4328,9 @@ "$ref": "#/components/schemas/ObjectPage.ManagedUser" }, "examples": { - "Example response": { - "summary": "Example paged response", - "description": "An example of ObjectPage.ManagedUser returned that represents the list of users assigned to specific privileged device.", + "Managed user page": { + "summary": "Example paged user result", + "description": "An example of paged user result that represents the current page of assigned user list retrieved from the specified AVD intermediary.", "value": { "@odata.count": 3, "@odata.nextLink": "2", @@ -4457,43 +4396,50 @@ "401": { "$ref": "#/components/responses/401" }, + "404": { + "$ref": "#/components/responses/404" + }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "List User Assignments", + "summary": "List all assigned users (paginated)", "tags": [ - "Device Management" + "Intermediary" ] }, "post": { - "description": "Adds the specified list of users to the list of users that are allowed to log in on the specific privileged device.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Post", + "description": "Assigns the specified user(s) as identified by their Object ID to the AVD cluster and create corresponding session host(s) for them.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/Post", "parameters": [ { - "$ref": "#/components/parameters/deviceId" + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/intermediaryId" } ], "requestBody": { "content": { "application/json": { "examples": { - "1:1 map": { - "description": "This example is the security best practice of having only one user mapped to a managed device.", - "summary": "1:1 User Mapping", + "One user": { + "description": "Creates 1 session host, and added the requested user to the assignments security group.", + "summary": "Assign Single User", "value": { "userList": [ - "0674276a-31e8-4773-8ed9-6fb49dbd0fa8" + "cf5b12a9-b939-4d5c-a380-fb62e4fe88ef" ] } }, - "Multi-User Managed Device": { - "description": "This example is the security best practice of having multiple users mapped to a managed device.", - "summary": "Multi-User Assignment", + "Two users": { + "description": "Creates 3 session hosts, and added the requested users to the assignments security group.", + "summary": "Assign Multiple Users", "value": { "userList": [ - "0674276a-31e8-4773-8ed9-6fb49dbd0fa8", - "66714224-b1a6-4fd6-b9d8-5263fdf755fc" + "0c56b055-9042-4f54-8e6e-6510e12a81dc", + "dd27937c-6287-45b3-98de-387725b068f3", + "989d3dc1-43f4-4ff7-82ba-43661f94a428" ] } } @@ -4502,17 +4448,17 @@ "properties": { "userList": { "items": { - "examples": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" - ], "format": "uuid", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + "type": "string", + "examples": [ + "0c56b055-9042-4f54-8e6e-6510e12a81dc" + ] }, "type": "array", "examples": [ [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + "0c56b055-9042-4f54-8e6e-6510e12a81dc" ] ] } @@ -4521,7 +4467,7 @@ "examples": [ { "userList": [ - "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + "0c56b055-9042-4f54-8e6e-6510e12a81dc" ] } ] @@ -4541,9 +4487,9 @@ "type": "array" }, "examples": { - "List of Managed Users": { - "summary": "Users assigned to the privileged device", - "description": "An example of ManagedObject.User array that represents the list of users which successfully assigned to the specified privileged device.", + "Managed user": { + "summary": "Example managed users returned", + "description": "An example of managed user array returned that represents the users has been assigned to the specified AVD cluster and created corresponding session host successfully.", "value": [ { "creationDate": "2023-10-21T15:24:47.970Z", @@ -4576,29 +4522,32 @@ "401": { "$ref": "#/components/responses/401" }, + "404": { + "$ref": "#/components/responses/404" + }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "Add User Assignments", + "summary": "Assigns the list of specified users", "tags": [ - "Device Management" + "Intermediary" ] } }, - "/Api/Defend/Device/Type/{securityClass}": { + "/Api/Defend/Intermediary/{intermediaryId}/Type/{securityClass}/Offering/8a921026-ec06-4e08-af19-8812e161e61f/Assign/{userId}": { "get": { - "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", - "operationId": "/Api/Defend/Device/Type/:securityClass/Get", + "description": "Get the specified managed user(s) from the specified AVD intermediary assignment list.\n\nThis endpoint requires the `Intermediary.Privileged.Read`, `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.Read`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, `Intermediary.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Intermediary/:intermediaryId/Type/:securityClass/Offering/AVD/Assign/:userId/Get", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { - "$ref": "#/components/parameters/nextLink" + "$ref": "#/components/parameters/intermediaryId" }, { - "$ref": "#/components/parameters/search" + "$ref": "#/components/parameters/userId" } ], "responses": { @@ -4606,38 +4555,65 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ObjectPage.ManagedDevice" + "$ref": "#/components/schemas/ObjectPage.ManagedUser" }, "examples": { - "Managed device list": { - "summary": "Example list of managed devices", - "description": "An example paged result returned that represents a specific page of managed device list.", + "Assigned users": { + "summary": "Example assigned user list", + "description": "An example paged assigned user list that represents the current page retrieved from specified AVD intermediary assignment list.", "value": { "@odata.count": 3, "@odata.nextLink": "2", "value": [ { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "upn": "priv-user@example.com", "securityClass": "Privileged", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] }, { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", - "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", + "upn": "priv-user@example.com", "securityClass": "Privileged", - "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", - "userAssignmentList": [ - "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", - "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", - "c54d4854-9254-4689-8a22-1cc80a3dae4e" - ] + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "deviceAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", + "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", + "temporaryAccessPass": "BCKTSN#E2R&5" } ] } @@ -4650,56 +4626,77 @@ "401": { "$ref": "#/components/responses/401" }, + "404": { + "$ref": "#/components/responses/404" + }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "Get All Devices", + "summary": "Get a specific assigned user", "tags": [ - "Device Management" + "Intermediary" ] - }, - "post": { - "description": "Commissions a new device, into the device hierarchy and appends appropriate metadata and initial policies. Appends required metadata to proper locations.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Device/Type/:securityClass/Post", + } + }, + "/Api/Defend/Device/{deviceId}/Type/Privileged/Assign": { + "delete": { + "description": "Remove the specified user list from the device.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Delete", "parameters": [ { - "$ref": "#/components/parameters/securityClass" + "$ref": "#/components/parameters/deviceId" } ], "requestBody": { "content": { "application/json": { "examples": { - "Request body": { + "Multiple Users": { + "description": "Remove multiple user assignments from a managed device.", + "summary": "Unassign multiple users", "value": { - "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" - }, - "summary": "Example request body", - "description": "An example request body object that represents a request to commission the device specified in the deviceId field." + "userList": [ + "0674276a-31e8-4773-8ed9-6fb49dbd0fa8", + "66714224-b1a6-4fd6-b9d8-5263fdf755fc" + ] + } + }, + "Single User": { + "description": "Remove a single user assignment from a managed device.", + "summary": "Unassign one user", + "value": { + "userList": [ + "01ebf268-cf28-4607-954a-261dfd480453" + ] + } } }, "schema": { "properties": { - "deviceId": { - "description": "The SHIELD ID (Entra ID Device ID) of the device to target.", + "userList": { + "items": { + "examples": [ + "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + ], + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "type": "array", "examples": [ - "75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + [ + "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + ] + ] } }, - "required": [ - "deviceId" - ], "type": "object", "examples": [ { - "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" + "userList": [ + "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + ] } ] } @@ -4711,103 +4708,39 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ManagedObject.Device" - }, - "examples": { - "Commissioned managed device": { - "summary": "Example managed device info", - "description": "An example managed device object returned that represents a successfully commissioned device.", - "value": { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "securityClass": "Privileged", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" - } - } - } - } - }, - "description": "OK" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Commission a New Device", - "tags": [ - "Device Management" - ] - } - }, - "/Api/Defend/Device/{deviceId}/Type/{securityClass}": { - "delete": { - "description": "Removes the device from the management hierarchy, removes metadata tagging and issues the wipe command to the devices.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Delete", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/deviceId" - } - ], - "responses": { - "204": { - "description": "OK: Deleted successfully" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "404": { - "$ref": "#/components/responses/404" - }, - "525": { - "$ref": "#/components/responses/525" - } - }, - "summary": "Decommission Specified Device", - "tags": [ - "Device Management" - ] - }, - "get": { - "description": "Get the specified managed device by its Entra ID Device ID.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Get", - "parameters": [ - { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/deviceId" - } - ], - "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ManagedObject.Device" + "items": { + "$ref": "#/components/schemas/ManagedObject.User" + }, + "minItems": 0, + "type": "array" }, "examples": { - "Managed device": { - "summary": "Example managed device", - "description": "An example of ManagedObject.Device object returned that represents a managed device queried by a device ID with specified security class.", - "value": { - "commissionedDate": "2023-02-04T05:06:09.601Z", - "displayName": "Priv-01534962354", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", - "securityClass": "Privileged", - "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" - } + "Removed user list": { + "summary": "Example removed user list", + "description": "An example array of ManagedObject.User that represents those removed from specific privileged device assignment.", + "value": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + } + ] } } } @@ -4817,32 +4750,21 @@ "401": { "$ref": "#/components/responses/401" }, - "404": { - "$ref": "#/components/responses/404" - }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "Get Specified Device by ID", + "summary": "Remove User Assignments", "tags": [ "Device Management" ] - } - }, - "/Api/Defend/User/Type/{securityClass}": { + }, "get": { - "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", - "operationId": "/Api/Defend/User/Type/:securityClass/Get", + "description": "Lists all of the users that are currently assigned to the specified device.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Get", "parameters": [ { - "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/nextLink" - }, - { - "$ref": "#/components/parameters/search" + "$ref": "#/components/parameters/deviceId" } ], "responses": { @@ -4853,9 +4775,9 @@ "$ref": "#/components/schemas/ObjectPage.ManagedUser" }, "examples": { - "Managed user": { - "summary": "Example paged user list", - "description": "An examples of ObjectPage.ManagedUser returned that represents a page of a managed user list.", + "Example response": { + "summary": "Example paged response", + "description": "An example of ObjectPage.ManagedUser returned that represents the list of users assigned to specific privileged device.", "value": { "@odata.count": 3, "@odata.nextLink": "2", @@ -4925,52 +4847,68 @@ "$ref": "#/components/responses/525" } }, - "summary": "Get All Users", + "summary": "List User Assignments", "tags": [ - "User Management" + "Device Management" ] }, "post": { - "description": "For Specialized or Enterprise, adds existing user into management. For Privileged, securely clones the specified user's properties into a new managed user object in the privileged baselines.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/User/Type/:securityClass/Post", + "description": "Adds the specified list of users to the list of users that are allowed to log in on the specific privileged device.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, or the `Everything.ReadWrite` scope (permission).", + "operationId": "/Api/Defend/Device/:deviceId/Type/Privileged/Assign/Post", "parameters": [ { - "$ref": "#/components/parameters/securityClass" + "$ref": "#/components/parameters/deviceId" } ], "requestBody": { "content": { "application/json": { "examples": { - "Request body": { + "1:1 map": { + "description": "This example is the security best practice of having only one user mapped to a managed device.", + "summary": "1:1 User Mapping", "value": { - "userId": "d886680d-a283-4fc2-803f-370d81d62366" - }, - "summary": "Example request body", - "description": "An example object that represents a request to assign the specified user to target security class." + "userList": [ + "0674276a-31e8-4773-8ed9-6fb49dbd0fa8" + ] + } + }, + "Multi-User Managed Device": { + "description": "This example is the security best practice of having multiple users mapped to a managed device.", + "summary": "Multi-User Assignment", + "value": { + "userList": [ + "0674276a-31e8-4773-8ed9-6fb49dbd0fa8", + "66714224-b1a6-4fd6-b9d8-5263fdf755fc" + ] + } } }, "schema": { "properties": { - "userId": { - "description": "The Entra ID object ID of the user to clone.", + "userList": { + "items": { + "examples": [ + "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + ], + "format": "uuid", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + }, + "type": "array", "examples": [ - "264a8bed-0714-48fd-8b9d-0e4c4715cee5" - ], - "format": "uuid", - "maxLength": 36, - "minLength": 36, - "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", - "type": "string" + [ + "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + ] + ] } }, - "required": [ - "userId" - ], "type": "object", "examples": [ { - "userId": "264a8bed-0714-48fd-8b9d-0e4c4715cee5" + "userList": [ + "d1bc9d1a-5a30-4d66-898a-1dd300e707bc" + ] } ] } @@ -4982,33 +4920,39 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ManagedObject.User" + "items": { + "$ref": "#/components/schemas/ManagedObject.User" + }, + "minItems": 0, + "type": "array" }, "examples": { - "Created or cloned user": { - "summary": "Example user created/cloned", - "description": "An example managed user object returned that represents the user brought into management successfully.", - "value": { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", - "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", - "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] - } + "List of Managed Users": { + "summary": "Users assigned to the privileged device", + "description": "An example of ManagedObject.User array that represents the list of users which successfully assigned to the specified privileged device.", + "value": [ + { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + } + ] } } } @@ -5018,95 +4962,154 @@ "401": { "$ref": "#/components/responses/401" }, - "404": { - "$ref": "#/components/responses/404" - }, - "409": { - "description": "User is already managed." - }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "Create/Bring User Into Management", + "summary": "Add User Assignments", "tags": [ - "User Management" + "Device Management" ] } }, - "/Api/Defend/User/{userId}/Type/{securityClass}": { - "delete": { - "description": "Deletes the user account and removes the management artifacts.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Delete", + "/Api/Defend/Device/Type/{securityClass}": { + "get": { + "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", + "operationId": "/Api/Defend/Device/Type/:securityClass/Get", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { - "$ref": "#/components/parameters/userId" + "$ref": "#/components/parameters/nextLink" + }, + { + "$ref": "#/components/parameters/search" } ], "responses": { - "204": { - "description": "OK: Deleted successfully" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ObjectPage.ManagedDevice" + }, + "examples": { + "Managed device list": { + "summary": "Example list of managed devices", + "description": "An example paged result returned that represents a specific page of managed device list.", + "value": { + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" + }, + { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "groupAssignmentId": "830d8b6f-2f6f-41f7-8800-0c07445abd36", + "securityClass": "Privileged", + "userAssignmentId": "146964e0-8ca4-4af0-9c2a-894b32912463", + "userAssignmentList": [ + "56d0d4e1-96f6-4cfb-a5e9-a4ee923169a8", + "94a9d681-a8d2-43eb-a83b-d4bfe90259ff", + "c54d4854-9254-4689-8a22-1cc80a3dae4e" + ] + } + ] + } + } + } + } + }, + "description": "OK" }, "401": { "$ref": "#/components/responses/401" }, - "404": { - "$ref": "#/components/responses/404" - }, "525": { "$ref": "#/components/responses/525" } }, - "summary": "Delete Managed User by ID", + "summary": "Get All Devices", "tags": [ - "User Management" + "Device Management" ] }, - "get": { - "description": "Retrieves the specified managed user by its Entra ID User ID.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Get", + "post": { + "description": "Commissions a new device, into the device hierarchy and appends appropriate metadata and initial policies. Appends required metadata to proper locations.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Device/Type/:securityClass/Post", "parameters": [ { "$ref": "#/components/parameters/securityClass" - }, - { - "$ref": "#/components/parameters/userId" } ], + "requestBody": { + "content": { + "application/json": { + "examples": { + "Request body": { + "value": { + "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" + }, + "summary": "Example request body", + "description": "An example request body object that represents a request to commission the device specified in the deviceId field." + } + }, + "schema": { + "properties": { + "deviceId": { + "description": "The SHIELD ID (Entra ID Device ID) of the device to target.", + "examples": [ + "75da7fa4-4a04-44c8-8f2c-c1b2fa29aa51" + ], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + } + }, + "required": [ + "deviceId" + ], + "type": "object", + "examples": [ + { + "deviceId": "f7e1a66f-ce2e-4351-83df-2776813ef95d" + } + ] + } + } + } + }, "responses": { "200": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ManagedObject.User" + "$ref": "#/components/schemas/ManagedObject.Device" }, "examples": { - "Removed user": { - "summary": "Example removed user", - "description": "An example of managed user returned that represents the user has been removed from specified security class successfully.", + "Commissioned managed device": { + "summary": "Example managed device info", + "description": "An example managed device object returned that represents a successfully commissioned device.", "value": { - "creationDate": "2023-10-21T15:24:47.970Z", - "displayName": "Example User (Priv)", - "firstName": "John", - "lastName": "Doe", + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", - "upn": "priv-user@example.com", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", "securityClass": "Privileged", - "uiEducation": false, - "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", - "intermediaryAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ], - "siloAssignmentList": [ - "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", - "593d97dc-9a43-4bc7-9d79-ecde407d7782", - "995f3b39-1e01-40d4-9368-ee956343e97c" - ] + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" } } } @@ -5124,102 +5127,27 @@ "$ref": "#/components/responses/525" } }, - "summary": "Gets Managed User by ID", + "summary": "Commission a New Device", "tags": [ - "User Management" + "Device Management" ] } }, - "/Api/Defend/Marketplace/Type/{securityClass}/Offering/{offeringId}": { - "post": { - "description": "Creates the offering with the requested settings. In the body payload, the `type` property in the `property` object is ignored. See the AVD example.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", - "operationId": "/Api/Defend/Marketplace/Type/:securityClass/Offering/:offeringId/Post", + "/Api/Defend/Device/{deviceId}/Type/{securityClass}": { + "delete": { + "description": "Removes the device from the management hierarchy, removes metadata tagging and issues the wipe command to the devices.\n\nThis endpoint requires the `Device.Privileged.ReadWrite`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Delete", "parameters": [ { "$ref": "#/components/parameters/securityClass" }, { - "$ref": "#/components/parameters/offeringId" + "$ref": "#/components/parameters/deviceId" } ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "allOf": [ - { - "$ref": "#/components/schemas/ManagedObject.Intermediary" - }, - { - "properties": { - "properties": { - "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" - } - }, - "type": "object" - } - ], - "examples": [ - { - "name": "Legacy Reach Back", - "properties": { - "addressRangeCIDR": "172.16.1.0/24", - "index": 0, - "location": "East US 2", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - } - ] - }, - "examples": { - "Example intermediary object request": { - "summary": "Example Intermediary object request", - "description": "An example of create offering request body with minimal fields.", - "value": { - "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", - "kind": "AVD", - "name": "Legacy Reach Back", - "securityClass": "Privileged", - "properties": { - "addressRangeCIDR": "172.16.1.0/24", - "index": 0, - "location": "East US 2", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - } - } - } - } - } - }, "responses": { - "200": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" - }, - "examples": { - "Returned AVD intermediary": { - "summary": "Example AVD intermediary returned", - "description": "An example of AVD intermediary object returned that represents an successfully deployed offering.", - "value": { - "addressRangeCIDR": "172.16.1.0/24", - "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", - "index": 0, - "location": "East US 2", - "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", - "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", - "sessionHostPrefix": "Reach", - "vmSku": "Standard_D2s_v5" - } - } - } - } - }, - "description": "OK" + "204": { + "description": "OK: Deleted successfully" }, "401": { "$ref": "#/components/responses/401" @@ -5231,360 +5159,467 @@ "$ref": "#/components/responses/525" } }, - "summary": "Deploy Marketplace Offering", + "summary": "Decommission Specified Device", "tags": [ - "Marketplace" + "Device Management" ] - } - }, - "/Api/Deploy/Compare": { + }, "get": { - "summary": "Retrieves Cached Evaluation Results", - "description": "Returns results of the last performed comparison of the values in the existing resources and their original requested configurations. Resulting object consists of several categories and includes timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.Read`, or `Deploy.ReadWrite`, or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Compare/Get", + "description": "Get the specified managed device by its Entra ID Device ID.\n\nThis endpoint requires the `Device.Privileged.Read`, `Device.Privileged.ReadWrite`, `Device.Specialized.Read`, `Device.Specialized.ReadWrite`, `Device.Enterprise.ReadWrite`, `Device.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Device/:deviceId/Type/:securityClass/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/deviceId" + } + ], "responses": { "200": { - "content": { - "application/json": { - "examples": { - "Response with Cached Data": { - "summary": "Example of the comparison results", - "description": "An example of the cached results from the previous comparison operation.", - "value": { - "invalid": [ - { - "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", - "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." - }, - { - "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", - "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." - } - ], - "lastRunTimestamp": "2025-03-25T14:28:54Z", - "missing": [ - { - "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", - "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" - } - ], - "results": [ - { - "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", - "variants": [ - { - "actions": [ - 2, - 3 - ], - "errorCode": 5, - "path": "/displayName" - }, - { - "actions": [ - 2 - ], - "errorCode": 1, - "path": "/groupPolicyUploadedLanguageFiles" - } - ] - }, - { - "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", - "variants": [ - { - "actions": [ - 3 - ], - "errorCode": 3, - "path": "/roleScopeTagIds/1" - } - ] - } - ] + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.Device" + }, + "examples": { + "Managed device": { + "summary": "Example managed device", + "description": "An example of ManagedObject.Device object returned that represents a managed device queried by a device ID with specified security class.", + "value": { + "commissionedDate": "2023-02-04T05:06:09.601Z", + "displayName": "Priv-01534962354", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "parentDeviceId": "81682cf5-0405-491d-8ab8-e07c778d7eaf", + "securityClass": "Privileged", + "uniqueGroupId": "146964e0-8ca4-4af0-9c2a-894b32912463" } } - }, - "schema": { - "$ref": "#/components/schemas/Deploy.CompareResponse" } } }, "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" } }, + "summary": "Get Specified Device by ID", "tags": [ - "Deploy" + "Device Management" ] } }, - "/Api/Deploy/Compare/Invoke": { - "post": { - "summary": "Requests to Run New Evaluation and Returns Results", - "description": "Resets all cached data and initiates process to compar the values in the existing resources and their original requested configurations. Returns resulting object split into several categories and including timestamp when the evaluation was performed.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/DeployCompare/Invoke/Post", - "requestBody": { - "description": "No payload is expected or needed for this operation", - "content": { - "application/json": {} + "/Api/Defend/User/Type/{securityClass}": { + "get": { + "description": "Returns a list of all devices managed or unmanaged.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL. When reading the `unmanaged` objects, any security class permission can read them, no need for a specific `unmanaged` class assignment.", + "operationId": "/Api/Defend/User/Type/:securityClass/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/nextLink" + }, + { + "$ref": "#/components/parameters/search" } - }, + ], "responses": { "200": { "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/ObjectPage.ManagedUser" + }, "examples": { - "Response with New Data": { - "summary": "Example of the comparison results", - "description": "An example of the newly calculated results after performing comparison operation.", + "Managed user": { + "summary": "Example paged user list", + "description": "An examples of ObjectPage.ManagedUser returned that represents a page of a managed user list.", "value": { - "invalid": [ - { - "templateId": "a14402b8-98c5-41e3-ba99-e5e1a536f68d", - "message": "Setting ID '58246273-d366-40d5-ac3d-daacb8bc2655' - Item not found." - }, - { - "templateId": "9af9209d-d191-4b42-9f65-dfd8b7882bba", - "message": "Setting ID 'f6f5d07b-230c-4818-93de-e407b8ca9537' - Insufficient access to view this data." - } - ], - "lastRunTimestamp": "2025-03-25T14:28:54Z", - "missing": [ - { - "templateId": "78afd77c-c2a6-4328-9c61-b9fd44114823", - "message": "{\"displayName\":\"Privileged Objects\",\"description\":\"Privileged objects managed by application.\",\"membershipType\":\"Assigned\"}" - } - ], - "results": [ + "@odata.count": 3, + "@odata.nextLink": "2", + "value": [ { - "templateId": "c47c20bd-46fa-4dfe-b971-3e5b1ce34a86", - "variants": [ - { - "actions": [ - 2, - 3 - ], - "errorCode": 5, - "path": "/displayName" - }, - { - "actions": [ - 2 - ], - "errorCode": 1, - "path": "/groupPolicyUploadedLanguageFiles" - } + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" ] }, { - "templateId": "4b26b6f6-9cb3-4384-bd1e-6d298455c2c4", - "variants": [ - { - "actions": [ - 3 - ], - "errorCode": 3, - "path": "/roleScopeTagIds/1" - } - ] + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "deviceAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "generatedPassword": "GY_w7bZUKRgpIXctD0S2wg", + "parentId": "e59a3a64-dc36-4368-80ec-c205eb176ef6", + "temporaryAccessPass": "BCKTSN#E2R&5" } ] } } - }, - "schema": { - "$ref": "#/components/schemas/Deploy.CompareResponse" } } }, "description": "OK" }, - "503": { - "description": "Deployed architecture is invalid or missing!" + "401": { + "$ref": "#/components/responses/401" + }, + "525": { + "$ref": "#/components/responses/525" } }, + "summary": "Get All Users", "tags": [ - "Deploy" + "User Management" ] - } - }, - "/Api/Deploy/Restore/{templateId}": { - "patch": { - "summary": "Restores the Details Of the Deployed Resource", - "description": "Calculates and applies a change to the deployed resource to restore original value from the entire configuration item or single property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Restore/:templateId/Patch", + }, + "post": { + "description": "For Specialized or Enterprise, adds existing user into management. For Privileged, securely clones the specified user's properties into a new managed user object in the privileged baselines.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/User/Type/:securityClass/Post", "parameters": [ { - "$ref": "#/components/parameters/templateId" + "$ref": "#/components/parameters/securityClass" } ], "requestBody": { "content": { "application/json": { + "examples": { + "Request body": { + "value": { + "userId": "d886680d-a283-4fc2-803f-370d81d62366" + }, + "summary": "Example request body", + "description": "An example object that represents a request to assign the specified user to target security class." + } + }, "schema": { - "$ref": "#/components/schemas/Deploy.PathIndicator" + "properties": { + "userId": { + "description": "The Entra ID object ID of the user to clone.", + "examples": [ + "264a8bed-0714-48fd-8b9d-0e4c4715cee5" + ], + "format": "uuid", + "maxLength": 36, + "minLength": 36, + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-5][0-9a-f]{3}-[089ab][0-9a-f]{3}-[0-9a-f]{12}$", + "type": "string" + } + }, + "required": [ + "userId" + ], + "type": "object", + "examples": [ + { + "userId": "264a8bed-0714-48fd-8b9d-0e4c4715cee5" + } + ] } } } }, "responses": { - "204": { - "description": "Restoration of configuration item or its property is successful" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.User" + }, + "examples": { + "Created or cloned user": { + "summary": "Example user created/cloned", + "description": "An example managed user object returned that represents the user brought into management successfully.", + "value": { + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ], + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" + ] + } + } + } + } + }, + "description": "OK" }, - "400": { - "description": "The body does not match expected format!" + "401": { + "$ref": "#/components/responses/401" }, "404": { "$ref": "#/components/responses/404" + }, + "409": { + "description": "User is already managed." + }, + "525": { + "$ref": "#/components/responses/525" } }, + "summary": "Create/Bring User Into Management", "tags": [ - "Deploy" + "User Management" ] } }, - "/Api/Deploy/Remove": { + "/Api/Defend/User/{userId}/Type/{securityClass}": { "delete": { - "summary": "Removes All Provisioned Infrastructure Resources", - "description": "Deletes all resources in the tenant that were created during the initial deploy or any update operation since.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/DeployRemove/Delete", + "description": "Deletes the user account and removes the management artifacts.\n\nThis endpoint requires the `User.Privileged.ReadWrite`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/userId" + } + ], "responses": { - "202": { - "description": "Request for removal is accepted and process initiated" + "204": { + "description": "OK: Deleted successfully" }, - "503": { - "description": "Deployed architecture is invalid or missing!" + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" } }, + "summary": "Delete Managed User by ID", "tags": [ - "Deploy" + "User Management" ] - } - }, - "/Api/Deploy/Skip": { + }, "get": { - "summary": "Retrieves List of Existing Override Rules", - "description": "Retrieves the details of override property in the Settings Engine and returns list grouped by configuration item reference.\n\nThis endpoint requires `Deploy.Read`, or `Deploy.ReadWrite`, or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Skip/Get", + "description": "Retrieves the specified managed user by its Entra ID User ID.\n\nThis endpoint requires the `User.Privileged.Read`, `User.Privileged.ReadWrite`, `User.Specialized.Read`, `User.Specialized.ReadWrite`, `User.Enterprise.ReadWrite`, `User.Enterprise.Read`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/User/:userId/Type/:securityClass/Get", + "parameters": [ + { + "$ref": "#/components/parameters/securityClass" + }, + { + "$ref": "#/components/parameters/userId" + } + ], "responses": { "200": { "content": { "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.User" + }, "examples": { - "Example Response with Current Rules": { - "summary": "Example of the returned list of the skipped items", - "description": "An example of the list indicating configuration items and the properties that are designed to be ignored during the comparison operation.", + "Removed user": { + "summary": "Example removed user", + "description": "An example of managed user returned that represents the user has been removed from specified security class successfully.", "value": { - "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ - "/" + "creationDate": "2023-10-21T15:24:47.970Z", + "displayName": "Example User (Priv)", + "firstName": "John", + "lastName": "Doe", + "id": "9f237e13-9a04-4daf-b3d4-6d2beec3c2bf", + "upn": "priv-user@example.com", + "securityClass": "Privileged", + "uiEducation": false, + "uniqueGroupId": "ad402c42-1bc9-4ba5-9419-7dbfb46a9c4d", + "intermediaryAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" ], - "9c858901-8a57-4791-81fe-4c455b099bc9": [ - "/description", - "/name" + "siloAssignmentList": [ + "0390fb3e-c58b-4d73-b02c-eae41ec5e4a5", + "593d97dc-9a43-4bc7-9d79-ecde407d7782", + "995f3b39-1e01-40d4-9368-ee956343e97c" ] } } - }, - "schema": { - "type": "object", - "additionalProperties": { - "type": "array", - "items": { - "type": "string", - "description": "Flat path representing entire item or specific nested property in the configuration item.", - "examples": [ - "/description" - ] - }, - "examples": [ - [ - "/", - "/description" - ] - ] - }, - "description": "Collection of references to configuration items (using templateId property as property name) and array of strings as value.", - "examples": [ - { - "f47ac10b-58cc-4372-a567-0e02b2c3d479": [ - "/" - ], - "9c858901-8a57-4791-81fe-4c455b099bc9": [ - "/description", - "/name" - ] - } - ] } } }, "description": "OK" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" } }, + "summary": "Gets Managed User by ID", "tags": [ - "Deploy" + "User Management" ] } }, - "/Api/Deploy/Skip/{templateId}": { + "/Api/Defend/Marketplace/Type/{securityClass}/Offering/{offeringId}": { "post": { - "summary": "Records New Entry to Skip During Evaluation", - "description": "Stores the reference to the entity to be skipped during the evaluation process. Could be entire configuration item or a specific property.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Skip/:templateId/Post", + "description": "Creates the offering with the requested settings. In the body payload, the `type` property in the `property` object is ignored. See the AVD example.\n\nThis endpoint requires the `Intermediary.Privileged.ReadWrite`, `Intermediary.Specialized.ReadWrite`, `Intermediary.Enterprise.ReadWrite`, or the `Everything.ReadWrite` scope (permission). The security class parameter in the URL path corresponds to the same permission in the scope. That means if you are granted a privileged role, you can only call the privilege class URL.", + "operationId": "/Api/Defend/Marketplace/Type/:securityClass/Offering/:offeringId/Post", "parameters": [ { - "$ref": "#/components/parameters/templateId" - } - ], - "requestBody": { - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Deploy.PathIndicator" - } - } - } - }, - "responses": { - "204": { - "description": "Recorded successfully" + "$ref": "#/components/parameters/securityClass" }, - "400": { - "description": "The body does not match expected format!" - } - }, - "tags": [ - "Deploy" - ] - }, - "delete": { - "summary": "Removes Existing Entry From Being Skipped", - "description": "Deletes the entry so it is no longer ignored during the evaluation process.\n\nThis endpoint requires the `Deploy.ReadWrite` or `Everything.ReadWrite` scope (permission).", - "operationId": "/Api/Deploy/Skip/:templateId/Delete", - "parameters": [ { - "$ref": "#/components/parameters/templateId" + "$ref": "#/components/parameters/offeringId" } ], "requestBody": { "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/Deploy.PathIndicator" + "allOf": [ + { + "$ref": "#/components/schemas/ManagedObject.Intermediary" + }, + { + "properties": { + "properties": { + "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" + } + }, + "type": "object" + } + ], + "examples": [ + { + "name": "Legacy Reach Back", + "properties": { + "addressRangeCIDR": "172.16.1.0/24", + "index": 0, + "location": "East US 2", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + } + ] + }, + "examples": { + "Example intermediary object request": { + "summary": "Example Intermediary object request", + "description": "An example of create offering request body with minimal fields.", + "value": { + "id": "e097a3f5-9599-44a2-8923-fd3276c83ae1", + "kind": "AVD", + "name": "Legacy Reach Back", + "securityClass": "Privileged", + "properties": { + "addressRangeCIDR": "172.16.1.0/24", + "index": 0, + "location": "East US 2", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + } + } } } } }, "responses": { - "204": { - "description": "Record has been removed successfully" + "200": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ManagedObject.AvdIntermediary" + }, + "examples": { + "Returned AVD intermediary": { + "summary": "Example AVD intermediary returned", + "description": "An example of AVD intermediary object returned that represents an successfully deployed offering.", + "value": { + "addressRangeCIDR": "172.16.1.0/24", + "assignmentGroup": "68873e26-3c35-465c-9422-0884a00beb36", + "index": 0, + "location": "East US 2", + "resourceId": "/subscriptions/742f0d26-daa0-4f84-8d4f-fb052f89f639/resourceGroups/SHIELD_-_PSM-Legacy_Reach_Back/providers/Microsoft.DesktopVirtualization/hostpools/SHIELD_-_PSM-Cluster-Legacy_Reach_Back", + "sessionHostGroup": "f99f0918-da9b-4c58-9a8d-9346abc5d9ec", + "sessionHostPrefix": "Reach", + "vmSku": "Standard_D2s_v5" + } + } + } + } + }, + "description": "OK" }, - "400": { - "description": "The body does not match expected format!" + "401": { + "$ref": "#/components/responses/401" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "525": { + "$ref": "#/components/responses/525" } }, + "summary": "Deploy Marketplace Offering", "tags": [ - "Deploy" + "Marketplace" ] } }