AWS directoryservice documentation change
Summary
Added documentation for the new StartADAssessment API, including request/response syntax, parameters, errors, examples, and operational details for initiating directory assessments to validate hybrid domain join environments
Security assessment
The change documents a new API for validating security configurations (network connectivity, security groups, DNS) in hybrid AD environments. While it relates to security posture validation, there is no evidence of addressing a specific vulnerability or incident. The documentation proactively describes security-related configuration checks rather than responding to a known issue.
Diff
diff --git a/directoryservice/latest/devguide/API_StartADAssessment.md b/directoryservice/latest/devguide/API_StartADAssessment.md index 8b1378917..7d3f990b9 100644 --- a//directoryservice/latest/devguide/API_StartADAssessment.md +++ b//directoryservice/latest/devguide/API_StartADAssessment.md @@ -0,0 +1 @@ +[](/pdfs/directoryservice/latest/devguide/directoryservice-api.pdf#API_StartADAssessment "Open PDF") @@ -1,0 +3,250 @@ +[Documentation](/index.html)[AWS Directory Service](/directory-service/index.html)[API Reference](welcome.html) + +Request SyntaxRequest ParametersResponse SyntaxResponse ElementsErrorsExamplesSee Also + +# StartADAssessment + +Initiates a directory assessment to validate your self-managed AD environment for hybrid domain join. The assessment checks compatibility and connectivity of the self-managed AD environment. + +A directory assessment is automatically created when you create a hybrid directory. There are two types of assessments: `CUSTOMER` and `SYSTEM`. Your AWS account has a limit of 100 `CUSTOMER` directory assessments. + +The assessment process typically takes 30 minutes or more to complete. The assessment process is asynchronous and you can monitor it with `DescribeADAssessment`. + +The `InstanceIds` must have a one-to-one correspondence with `CustomerDnsIps`, meaning that if the IP address for instance i-10243410 is 10.24.34.100 and the IP address for instance i-10243420 is 10.24.34.200, then the input arrays must maintain the same order relationship, either [10.24.34.100, 10.24.34.200] paired with [i-10243410, i-10243420] or [10.24.34.200, 10.24.34.100] paired with [i-10243420, i-10243410]. + +Note: You must provide exactly one `DirectoryId` or `AssessmentConfiguration`. + +## Request Syntax + + + { + "AssessmentConfiguration": { + "[CustomerDnsIps](./API_AssessmentConfiguration.html#DirectoryService-Type-AssessmentConfiguration-CustomerDnsIps)": [ "string" ], + "[DnsName](./API_AssessmentConfiguration.html#DirectoryService-Type-AssessmentConfiguration-DnsName)": "string", + "[InstanceIds](./API_AssessmentConfiguration.html#DirectoryService-Type-AssessmentConfiguration-InstanceIds)": [ "string" ], + "[SecurityGroupIds](./API_AssessmentConfiguration.html#DirectoryService-Type-AssessmentConfiguration-SecurityGroupIds)": [ "string" ], + "[VpcSettings](./API_AssessmentConfiguration.html#DirectoryService-Type-AssessmentConfiguration-VpcSettings)": { + "[SubnetIds](./API_DirectoryVpcSettings.html#DirectoryService-Type-DirectoryVpcSettings-SubnetIds)": [ "string" ], + "[VpcId](./API_DirectoryVpcSettings.html#DirectoryService-Type-DirectoryVpcSettings-VpcId)": "string" + } + }, + "DirectoryId": "string" + } + +## Request Parameters + +The request accepts the following data in JSON format. + +**AssessmentConfiguration ** + + +Configuration parameters for the directory assessment, including DNS server information, domain name, Amazon VPC subnet, and AWS System Manager managed node details. + +Type: [AssessmentConfiguration](./API_AssessmentConfiguration.html) object + +Required: No + +**DirectoryId ** + + +The identifier of the directory for which to perform the assessment. This should be an existing directory. If the assessment is not for an existing directory, this parameter should be omitted. + +Type: String + +Pattern: `^d-[0-9a-f]{10}$` + +Required: No + +## Response Syntax + + + { + "AssessmentId": "**_string_** " + } + +## Response Elements + +If the action is successful, the service sends back an HTTP 200 response. + +The following data is returned in JSON format by the service. + +**AssessmentId ** + + +The unique identifier of the newly started directory assessment. Use this identifier to monitor assessment progress and retrieve results. + +Type: String + +Pattern: `^da-[0-9a-f]{18}$` + +## Errors + +For information about the errors that are common to all actions, see [Common Errors](./CommonErrors.html). + +**ADAssessmentLimitExceededException** + + +A directory assessment is automatically created when you create a hybrid directory. There are two types of assessments: `CUSTOMER` and `SYSTEM`. Your AWS account has a limit of 100 `CUSTOMER` directory assessments. + +If you attempt to create a hybrid directory; and you already have 100 `CUSTOMER` directory assessments;, you will encounter an error. Delete assessments to free up capacity before trying again. + +You can request an increase to your `CUSTOMER` directory assessment quota by contacting customer support or delete existing CUSTOMER directory assessments; to free up capacity. + +HTTP Status Code: 400 + +**ClientException** + + +A client exception has occurred. + +HTTP Status Code: 400 + +**DirectoryDoesNotExistException** + + +The specified directory does not exist in the system. + +HTTP Status Code: 400 + +**InvalidParameterException** + + +One or more parameters are not valid. + +HTTP Status Code: 400 + +**ServiceException** + + +An exception has occurred in AWS Directory Service. + +HTTP Status Code: 500 + +**UnsupportedOperationException** + + +The operation is not supported. + +HTTP Status Code: 400 + +## Examples + +The following examples are formatted for legibility. + +### Example Pre-join Request + +This example illustrates one usage of StartADAssessment. + + + POST / HTTP/1.1 + Host: ds.us-west-2.amazonaws.com + Accept-Encoding: identity + Content-Length: 312 + X-Amz-Target: DirectoryService_20150416.StartADAssessment + X-Amz-Date: 20231212T212029Z + User-Agent: aws-cli/2.0.0 Python/3.8.0 Linux/5.4.0 botocore/2.0.0 + Content-Type: application/x-amz-json-1.1 + Authorization: AWS4-HMAC-SHA256 + Credential=AKIAI7E3BYXS3example/20231212/us-west-2/ds/aws4_request, + SignedHeaders=content-type;host;x-amz-date;x-amz-target, + Signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 + // Request - prejoin + { + "AssessmentConfiguration": { + "CustomerDnsIps": ["10.24.34.100", "10.24.34.200"], + "DnsName": "ad.example.com", + "VpcSettings": { + "VpcId": "vpc-04c978example126f", + "SubnetIds": ["subnet-0994bexampled9ea7", "subnet-095e06examplee7e7"] + }, + "InstanceIds": ["i-10243410", "i-10243420"], + "SecurityGroupIds": ["sg-0fbb77examplef199"] + } + } + +### Example Post-join Request + +This example illustrates one usage of StartADAssessment. + + + POST / HTTP/1.1 + Host: ds.us-west-2.amazonaws.com + Accept-Encoding: identity + Content-Length: 312 + X-Amz-Target: DirectoryService_20150416.StartADAssessment + X-Amz-Date: 20231212T212029Z + User-Agent: aws-cli/2.0.0 Python/3.8.0 Linux/5.4.0 botocore/2.0.0 + Content-Type: application/x-amz-json-1.1 + Authorization: AWS4-HMAC-SHA256 + Credential=AKIAI7E3BYXS3example/20231212/us-west-2/ds/aws4_request, + SignedHeaders=content-type;host;x-amz-date;x-amz-target, + Signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 + + // Request - postjoin + { + "DirectoryId": "d-926example" + } + +### Example Response + +This example illustrates one usage of StartADAssessment. + + + HTTP/1.1 200 OK