AWS directoryservice documentation change

Service: directoryservice · 2025-08-01 · Documentation low

File: directoryservice/latest/devguide/API_CreateHybridAD.md

Summary

Added documentation for CreateHybridAD API operation including request/response syntax, parameters, errors, examples, and security requirements for hybrid directory creation

Security assessment

The documentation introduces security-related parameters like SecretArn which requires secure credential storage in AWS Secrets Manager, and mandates pre-requisite security assessments. However, there is no evidence this addresses a specific existing security vulnerability - rather it documents standard security practices for a new API operation.

Diff

diff --git a/directoryservice/latest/devguide/API_CreateHybridAD.md b/directoryservice/latest/devguide/API_CreateHybridAD.md
index 8b1378917..25abd00d7 100644
--- a//directoryservice/latest/devguide/API_CreateHybridAD.md
+++ b//directoryservice/latest/devguide/API_CreateHybridAD.md
@@ -0,0 +1 @@
+[](/pdfs/directoryservice/latest/devguide/directoryservice-api.pdf#API_CreateHybridAD "Open PDF")
@@ -1,0 +3,236 @@
+[Documentation](/index.html)[AWS Directory Service](/directory-service/index.html)[API Reference](welcome.html)
+
+Request SyntaxRequest ParametersResponse SyntaxResponse ElementsErrorsExamplesSee Also
+
+# CreateHybridAD
+
+Creates a hybrid directory that connects your self-managed Active Directory (AD) infrastructure and AWS.
+
+You must have a successful directory assessment using [StartADAssessment](./API_StartADAssessment.html) to validate your environment compatibility before you use this operation.
+
+Updates are applied asynchronously. Use [DescribeDirectories](./API_DescribeDirectories.html) to monitor the progress of directory creation.
+
+## Request Syntax
+    
+    
+    {
+       "AssessmentId": "string",
+       "SecretArn": "string",
+       "Tags": [ 
+          { 
+             "[Key](./API_Tag.html#DirectoryService-Type-Tag-Key)": "string",
+             "[Value](./API_Tag.html#DirectoryService-Type-Tag-Value)": "string"
+          }
+       ]
+    }
+
+## Request Parameters
+
+The request accepts the following data in JSON format.
+
+**AssessmentId **
+    
+
+The unique identifier of the successful directory assessment that validates your self-managed AD environment. You must have a successful directory assessment before you create a hybrid directory.
+
+Type: String
+
+Pattern: `^da-[0-9a-f]{18}$`
+
+Required: Yes
+
+**SecretArn **
+    
+
+The Amazon Resource Name (ARN) of the AWS Secrets Manager secret that contains the credentials for the service account used to join hybrid domain controllers to your self-managed AD domain. This secret is used once and not stored.
+
+The secret must contain key-value pairs with keys matching `customerAdAdminDomainUsername` and `customerAdAdminDomainPassword`. For example: `{"customerAdAdminDomainUsername":"carlos_salazar","customerAdAdminDomainPassword":"ExamplePassword123!"}`.
+
+Type: String
+
+Pattern: `^arn:aws:secretsmanager:[a-z0-9-]+:\d{12}:secret:[a-zA-Z0-9/_+=.@-]+-[a-zA-Z0-9]{6}$`
+
+Required: Yes
+
+**Tags **
+    
+
+The tags to be assigned to the directory. Each tag consists of a key and value pair. You can specify multiple tags as a list.
+
+Type: Array of [Tag](./API_Tag.html) objects
+
+Required: No
+
+## Response Syntax
+    
+    
+    {
+       "DirectoryId": "**_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.
+
+**DirectoryId **
+    
+
+The unique identifier of the newly created hybrid directory.
+
+Type: String
+
+Pattern: `^d-[0-9a-f]{10}$`
+
+## 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
+
+**DirectoryLimitExceededException**
+    
+
+The maximum number of directories in the region has been reached. You can use the [GetDirectoryLimits](./API_GetDirectoryLimits.html) operation to determine your directory limits in the region.
+
+HTTP Status Code: 400
+
+**EntityDoesNotExistException**
+    
+
+The specified entity could not be found.
+
+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 Request
+
+This example illustrates one usage of CreateHybridAD.
+    
+    
+    POST / HTTP/1.1
+    Host: ds.us-west-2.amazonaws.com
+    Accept-Encoding: identity
+    Content-Length: 298
+    X-Amz-Target: DirectoryService_20150416.CreateHybridAD
+    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=AKIAIOSFODNN7EXAMPLE/20231212/us-west-2/ds/aws4_request,
+     SignedHeaders=content-type;host;x-amz-date;x-amz-target,
+     Signature=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+    
+    {
+        "SecretArn": "arn:aws:secretsmanager:eu-west-1:111122223333:secret:CredExample-DZESji",
+        "AssessmentId": "da-1234567890example1",
+        "Tags": [{
+            "Key": "Environment",
+            "Value": "Production"
+        }]
+    }
+
+### Example Response
+
+This example illustrates one usage of CreateHybridAD.
+    
+    
+    HTTP/1.1 200 OK
+    x-amzn-RequestId: cfc1cbc8-c0b0-11e6-aa44-41d91ee57463
+    Content-Type: application/x-amz-json-1.1
+    Content-Length: 30
+    Date: Mon, 12 Dec 2023 21:20:31 GMT
+    
+    {
+        "DirectoryId": "d-926example"
+    }}
+
+## See Also
+
+For more information about using this API in one of the language-specific AWS SDKs, see the following:
+
+  * [AWS Command Line Interface](https://docs.aws.amazon.com/goto/aws-cli/ds-2015-04-16/CreateHybridAD)