directories

Creates, updates, deletes, gets or lists a directories resource.

Overview

Name	directories
Type	Resource
Id	aws.ds.directories

Fields

The following fields are returned by SELECT queries:

describe_directories

Name	Datatype	Description
access_url	string	The access URL for the directory, such as http:​//<alias>.awsapps.com. If no alias exists, <alias> is the directory identifier, such as d-XXXXXXXXXX.
alias	string	The alias for the directory. If no alias exists, the alias is the directory identifier, such as d-XXXXXXXXXX. (pattern: <code>^(?!D-|d-)([\da-zA-Z]+)([-][\da-zA-Z])</code>)
connect_settings	object	DirectoryConnectSettingsDescription object that contains additional information about an AD Connector directory. Present only for AD Connector directories.
description	string	The description for the directory. (pattern: <code>^([a-zA-Z0-9_])[\a-zA-Z0-9_@#%+=:?./!\s-]$</code>)
desired_number_of_domain_controllers	integer	The desired number of domain controllers in the directory if the directory is Microsoft AD.
directory_id	string	The directory identifier. (pattern: <code>^d-[0-9a-f]{10}$</code>)
dns_ip_addrs	array	The IP addresses of the DNS servers for the directory. For a Simple AD or Microsoft AD directory, these are the IP addresses of the Simple AD or Microsoft AD directory servers. For an AD Connector directory, these are the IP addresses of self-managed directory to which the AD Connector is connected.
dns_ipv_6_addrs	array	The IPv6 addresses of the DNS servers for the directory. For a Simple AD or Microsoft AD directory, these are the IPv6 addresses of the Simple AD or Microsoft AD directory servers. For an AD Connector directory, these are the IPv6 addresses of the DNS servers or domain controllers in your self-managed directory to which the AD Connector is connected.
edition	string	The edition associated with this directory. (Enterprise, Standard, Hybrid)
hybrid_settings	object	Contains information about the hybrid directory configuration for the directory, including Amazon Web Services System Manager managed node identifiers and DNS IPs.
launch_time	string (date-time)	The date and time when the directory was created.
name	string	The fully qualified name of the directory. (pattern: <code>^([a-zA-Z0-9]+[\.-])+([a-zA-Z0-9])+$</code>)
network_type	string	The network type of the directory. (Dual-stack, IPv4, IPv6)
os_version	string	The operating system (OS) version of the directory. (SERVER_2012, SERVER_2019)
owner_directory_description	object	Describes the Managed Microsoft AD directory in the directory owner account.
radius_settings	object	Information about the RadiusSettings object configured for this directory.
radius_status	string	The status of the RADIUS MFA server connection. (Creating, Completed, Failed)
regions_info	object	Lists the Regions where the directory has replicated.
share_method	string	The method used when sharing a directory to determine whether the directory should be shared within your Amazon Web Services organization (ORGANIZATIONS) or with any Amazon Web Services account by sending a shared directory request (HANDSHAKE). (ORGANIZATIONS, HANDSHAKE)
share_notes	string	A directory share request that is sent by the directory owner to the directory consumer. The request includes a typed message to help the directory consumer administrator determine whether to approve or reject the share invitation.
share_status	string	Current directory status of the shared Managed Microsoft AD directory. (Shared, PendingAcceptance, Rejected, Rejecting, RejectFailed, Sharing, ShareFailed, Deleted, Deleting)
short_name	string	The short name of the directory. (pattern: <code>^[^\/:?"<>|.]+[^\/:?"<>|]*$</code>)
size	string	The directory size. (Small, Large)
sso_enabled	boolean	Indicates whether single sign-on is enabled for the directory. For more information, see EnableSso and DisableSso.
stage	string	The current stage of the directory. (Requested, Creating, Created, Active, Inoperable, Impaired, Restoring, RestoreFailed, Deleting, Deleted, Failed, Updating)
stage_last_updated_date_time	string (date-time)	The date and time when the stage was last updated.
stage_reason	string	Additional information about the directory stage.
type	string	The directory type. (SimpleAD, ADConnector, MicrosoftAD, SharedMicrosoftAD)
vpc_settings	object	A DirectoryVpcSettingsDescription object that contains additional information about a directory. Present only for Simple AD and Managed Microsoft AD directories.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_directories	select	region		Obtains information about the directories that belong to this account. You can retrieve information about specific directories by passing the directory identifiers in the DirectoryIds parameter. Otherwise, all directories that belong to the current account are returned. This operation supports pagination with the use of the NextToken request and response parameters. If more results are available, the DescribeDirectoriesResult.NextToken member contains a token that you pass in the next call to DescribeDirectories to retrieve the next set of items. You can also specify a maximum number of return results with the Limit parameter.
create_computer	insert	region, DirectoryId, ComputerName, Password		Creates an Active Directory computer object in the specified directory.
create_alias	insert	region, DirectoryId		Creates an alias for a directory and assigns the alias to the directory. The alias is used to construct the access URL for the directory, such as http:​//<alias>.awsapps.com. After an alias has been created, it cannot be deleted or reused, so this operation should only be used when absolutely necessary.
create_directory	insert	region, Password		Creates a Simple AD directory. For more information, see Simple Active Directory in the Directory Service Admin Guide. Before you call CreateDirectory, ensure that all of the required permissions have been explicitly granted through a policy. For details about what permissions are required to run the CreateDirectory operation, see Directory Service API Permissions: Actions, Resources, and Conditions Reference.
update_directory_setup	update	region, DirectoryId, UpdateType		Updates directory configuration for the specified update type.
update_radius	update	region, DirectoryId, RadiusSettings		Updates the Remote Authentication Dial In User Service (RADIUS) server information for an AD Connector or Microsoft AD directory.
delete_directory	delete	region		Deletes an Directory Service directory. Before you call DeleteDirectory, ensure that all of the required permissions have been explicitly granted through a policy. For details about what permissions are required to run the DeleteDirectory operation, see Directory Service API Permissions: Actions, Resources, and Conditions Reference.
cancel_schema_extension	exec	region, DirectoryId, SchemaExtensionId		Cancels an in-progress schema extension to a Microsoft AD directory. Once a schema extension has started replicating to all domain controllers, the task can no longer be canceled. A schema extension can be canceled during any of the following states; Initializing, CreatingSnapshot, and UpdatingSchema.
disable_ca_enrollment_policy	exec	region, DirectoryId		Disables the certificate authority (CA) enrollment policy for the specified directory. This stops automatic certificate enrollment and management for domain-joined clients, but does not affect existing certificates. Disabling the CA enrollment policy prevents new certificates from being automatically enrolled, but existing certificates remain valid and functional until they expire.
disable_client_authentication	exec	region, DirectoryId		Disables alternative client authentication methods for the specified directory.
disable_ldaps	exec	region, DirectoryId		Deactivates LDAP secure calls for the specified directory.
disable_radius	exec	region, DirectoryId		Disables multi-factor authentication (MFA) with the Remote Authentication Dial In User Service (RADIUS) server for an AD Connector or Microsoft AD directory.
disable_sso	exec	region, DirectoryId		Disables single-sign on for a directory.
enable_ca_enrollment_policy	exec	region, DirectoryId, PcaConnectorArn		Enables certificate authority (CA) enrollment policy for the specified directory. This allows domain-joined clients to automatically request and receive certificates from the specified Amazon Web Services Private Certificate Authority. Before enabling CA enrollment, ensure that the PCA connector is properly configured and accessible from the directory. The connector must be in an active state and have the necessary permissions.
enable_client_authentication	exec	region, DirectoryId		Enables alternative client authentication methods for the specified directory.
enable_ldaps	exec	region, DirectoryId		Activates the switch for the specific directory to always use LDAP secure calls.
enable_radius	exec	region, DirectoryId, RadiusSettings		Enables multi-factor authentication (MFA) with the Remote Authentication Dial In User Service (RADIUS) server for an AD Connector or Microsoft AD directory.
enable_sso	exec	region, DirectoryId		Enables single sign-on for a directory. Single sign-on allows users in your directory to access certain Amazon Web Services services from a computer joined to the directory without having to enter their credentials separately.
reset_user_password	exec	region, DirectoryId, UserName, NewPassword		Resets the password for any user in your Managed Microsoft AD or Simple AD directory. Disabled users will become enabled and can be authenticated following the API call. You can reset the password for any user in your directory with the following exceptions: For Simple AD, you cannot reset the password for any user that is a member of either the Domain Admins or Enterprise Admins group except for the administrator user. For Managed Microsoft AD, you can only reset the password for a user that is in an OU based off of the NetBIOS name that you typed when you created your directory. For example, you cannot reset the password for a user in the Amazon Web Services Reserved OU. For more information about the OU structure for an Managed Microsoft AD directory, see What Gets Created in the Directory Service Administration Guide.
share_directory	exec	region, DirectoryId, ShareTarget, ShareMethod		Shares a specified directory (DirectoryId) in your Amazon Web Services account (directory owner) with another Amazon Web Services account (directory consumer). With this operation you can use your directory from any Amazon Web Services account and from any Amazon VPC within an Amazon Web Services Region. When you share your Managed Microsoft AD directory, Directory Service creates a shared directory in the directory consumer account. This shared directory contains the metadata to provide access to the directory within the directory owner account. The shared directory is visible in all VPCs in the directory consumer account. The ShareMethod parameter determines whether the specified directory can be shared between Amazon Web Services accounts inside the same Amazon Web Services organization (ORGANIZATIONS). It also determines whether you can share the directory with any other Amazon Web Services account either inside or outside of the organization (HANDSHAKE). The ShareNotes parameter is only used when HANDSHAKE is called, which sends a directory sharing request to the directory consumer.
start_schema_extension	exec	region, DirectoryId, CreateSnapshotBeforeSchemaExtension, LdifContent		Applies a schema extension to a Microsoft AD directory.
unshare_directory	exec	region, DirectoryId, UnshareTarget		Stops the directory sharing between the directory owner and consumer accounts.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_directories

Obtains information about the directories that belong to this account. You can retrieve information about specific directories by passing the directory identifiers in the DirectoryIds parameter. Otherwise, all directories that belong to the current account are returned. This operation supports pagination with the use of the NextToken request and response parameters. If more results are available, the DescribeDirectoriesResult.NextToken member contains a token that you pass in the next call to DescribeDirectories to retrieve the next set of items. You can also specify a maximum number of return results with the Limit parameter.

SELECT
access_url,
alias,
connect_settings,
description,
desired_number_of_domain_controllers,
directory_id,
dns_ip_addrs,
dns_ipv_6_addrs,
edition,
hybrid_settings,
launch_time,
name,
network_type,
os_version,
owner_directory_description,
radius_settings,
radius_status,
regions_info,
share_method,
share_notes,
share_status,
short_name,
size,
sso_enabled,
stage,
stage_last_updated_date_time,
stage_reason,
type,
vpc_settings
FROM aws.ds.directories
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_computer

Creates an Active Directory computer object in the specified directory.

INSERT INTO aws.ds.directories (
DirectoryId,
ComputerName,
Password,
OrganizationalUnitDistinguishedName,
ComputerAttributes,
region
)
SELECT 
'{{ DirectoryId }}' /* required */,
'{{ ComputerName }}' /* required */,
'{{ Password }}' /* required */,
'{{ OrganizationalUnitDistinguishedName }}',
'{{ ComputerAttributes }}',
'{{ region }}'
RETURNING
computer
;

create_alias

Creates an alias for a directory and assigns the alias to the directory. The alias is used to construct the access URL for the directory, such as http:​//<alias>.awsapps.com. After an alias has been created, it cannot be deleted or reused, so this operation should only be used when absolutely necessary.

INSERT INTO aws.ds.directories (
DirectoryId,
Alias,
region
)
SELECT 
'{{ DirectoryId }}' /* required */,
'{{ Alias }}',
'{{ region }}'
RETURNING
alias,
directory_id
;

create_directory

Creates a Simple AD directory. For more information, see Simple Active Directory in the Directory Service Admin Guide. Before you call CreateDirectory, ensure that all of the required permissions have been explicitly granted through a policy. For details about what permissions are required to run the CreateDirectory operation, see Directory Service API Permissions: Actions, Resources, and Conditions Reference.

INSERT INTO aws.ds.directories (
Name,
ShortName,
Password,
Description,
Size,
VpcSettings,
Tags,
NetworkType,
region
)
SELECT 
'{{ Name }}',
'{{ ShortName }}',
'{{ Password }}' /* required */,
'{{ Description }}',
'{{ Size }}',
'{{ VpcSettings }}',
'{{ Tags }}',
'{{ NetworkType }}',
'{{ region }}'
RETURNING
directory_id
;

Manifest

# Description fields are for documentation purposes
- name: directories
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the directories resource.
  - name: DirectoryId
    value: "{{ DirectoryId }}"
    description: |
      The identifier of the directory for which to create the alias.
  - name: ComputerName
    value: "{{ ComputerName }}"
    description: |
      The name of the computer account.
  - name: Password
    value: "{{ Password }}"
    description: |
      The password for the directory administrator. The directory creation process creates a directory administrator account with the user name Administrator and this password. If you need to change the password for the administrator account, you can use the ResetUserPassword API call. The regex pattern for this string is made up of the following conditions: Length (?=^.{8,64}$) – Must be between 8 and 64 characters AND any 3 of the following password complexity rules required by Active Directory: Numbers and upper case and lowercase (?=.*d)(?=.*[A-Z])(?=.*[a-z]) Numbers and special characters and lower case (?=.*d)(?=.*[^A-Za-z0-9s])(?=.*[a-z]) Special characters and upper case and lower case (?=.*[^A-Za-z0-9s])(?=.*[A-Z])(?=.*[a-z]) Numbers and upper case and special characters (?=.*d)(?=.*[A-Z])(?=.*[^A-Za-z0-9s]) For additional information about how Active Directory passwords are enforced, see Password must meet complexity requirements on the Microsoft website.
  - name: OrganizationalUnitDistinguishedName
    value: "{{ OrganizationalUnitDistinguishedName }}"
    description: |
      The fully-qualified distinguished name of the organizational unit to place the computer account in.
  - name: ComputerAttributes
    description: |
      An array of Attribute objects that contain any LDAP attributes to apply to the computer account.
    value:
      - Name: "{{ Name }}"
        Value: "{{ Value }}"
  - name: Alias
    value: "{{ Alias }}"
    description: |
      The requested alias. The alias must be unique amongst all aliases in Amazon Web Services. This operation throws an EntityAlreadyExistsException error if the alias already exists.
  - name: Name
    value: "{{ Name }}"
    description: |
      The fully qualified name for the directory, such as corp.example.com.
  - name: ShortName
    value: "{{ ShortName }}"
    description: |
      The NetBIOS name of the directory, such as CORP.
  - name: Description
    value: "{{ Description }}"
    description: |
      A description for the directory.
  - name: Size
    value: "{{ Size }}"
    description: |
      The size of the directory.
    valid_values: ['Small', 'Large']
  - name: VpcSettings
    description: |
      Contains VPC information for the CreateDirectory, CreateMicrosoftAD, or CreateHybridAD operation.
    value:
      VpcId: "{{ VpcId }}"
      SubnetIds:
        - "{{ SubnetIds }}"
  - name: Tags
    description: |
      The tags to be assigned to the Simple AD directory.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: NetworkType
    value: "{{ NetworkType }}"
    description: |
      The network type for your directory. Simple AD supports IPv4 and Dual-stack only.
    valid_values: ['Dual-stack', 'IPv4', 'IPv6']

UPDATE examples

update_directory_setup

Updates directory configuration for the specified update type.

UPDATE aws.ds.directories
SET 
DirectoryId = '{{ DirectoryId }}',
UpdateType = '{{ UpdateType }}',
OSUpdateSettings = '{{ OSUpdateSettings }}',
DirectorySizeUpdateSettings = '{{ DirectorySizeUpdateSettings }}',
NetworkUpdateSettings = '{{ NetworkUpdateSettings }}',
CreateSnapshotBeforeUpdate = {{ CreateSnapshotBeforeUpdate }}
WHERE 
region = '{{ region }}' --required
AND DirectoryId = '{{ DirectoryId }}' --required
AND UpdateType = '{{ UpdateType }}' --required;

update_radius

Updates the Remote Authentication Dial In User Service (RADIUS) server information for an AD Connector or Microsoft AD directory.

UPDATE aws.ds.directories
SET 
DirectoryId = '{{ DirectoryId }}',
RadiusSettings = '{{ RadiusSettings }}'
WHERE 
region = '{{ region }}' --required
AND DirectoryId = '{{ DirectoryId }}' --required
AND RadiusSettings = '{{ RadiusSettings }}' --required;

DELETE examples

delete_directory

Deletes an Directory Service directory. Before you call DeleteDirectory, ensure that all of the required permissions have been explicitly granted through a policy. For details about what permissions are required to run the DeleteDirectory operation, see Directory Service API Permissions: Actions, Resources, and Conditions Reference.

DELETE FROM aws.ds.directories
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

cancel_schema_extension

Cancels an in-progress schema extension to a Microsoft AD directory. Once a schema extension has started replicating to all domain controllers, the task can no longer be canceled. A schema extension can be canceled during any of the following states; Initializing, CreatingSnapshot, and UpdatingSchema.

EXEC aws.ds.directories.cancel_schema_extension 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"SchemaExtensionId": "{{ SchemaExtensionId }}"
}'
;

disable_ca_enrollment_policy

Disables the certificate authority (CA) enrollment policy for the specified directory. This stops automatic certificate enrollment and management for domain-joined clients, but does not affect existing certificates. Disabling the CA enrollment policy prevents new certificates from being automatically enrolled, but existing certificates remain valid and functional until they expire.

EXEC aws.ds.directories.disable_ca_enrollment_policy 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}"
}'
;

disable_client_authentication

Disables alternative client authentication methods for the specified directory.

EXEC aws.ds.directories.disable_client_authentication 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"Type": "{{ Type }}"
}'
;

disable_ldaps

Deactivates LDAP secure calls for the specified directory.

EXEC aws.ds.directories.disable_ldaps 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"Type": "{{ Type }}"
}'
;

disable_radius

Disables multi-factor authentication (MFA) with the Remote Authentication Dial In User Service (RADIUS) server for an AD Connector or Microsoft AD directory.

EXEC aws.ds.directories.disable_radius 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}"
}'
;

disable_sso

Disables single-sign on for a directory.

EXEC aws.ds.directories.disable_sso 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"UserName": "{{ UserName }}", 
"Password": "{{ Password }}"
}'
;

enable_ca_enrollment_policy

Enables certificate authority (CA) enrollment policy for the specified directory. This allows domain-joined clients to automatically request and receive certificates from the specified Amazon Web Services Private Certificate Authority. Before enabling CA enrollment, ensure that the PCA connector is properly configured and accessible from the directory. The connector must be in an active state and have the necessary permissions.

EXEC aws.ds.directories.enable_ca_enrollment_policy 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"PcaConnectorArn": "{{ PcaConnectorArn }}"
}'
;

enable_client_authentication

Enables alternative client authentication methods for the specified directory.

EXEC aws.ds.directories.enable_client_authentication 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"Type": "{{ Type }}"
}'
;

enable_ldaps

Activates the switch for the specific directory to always use LDAP secure calls.

EXEC aws.ds.directories.enable_ldaps 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"Type": "{{ Type }}"
}'
;

enable_radius

Enables multi-factor authentication (MFA) with the Remote Authentication Dial In User Service (RADIUS) server for an AD Connector or Microsoft AD directory.

EXEC aws.ds.directories.enable_radius 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"RadiusSettings": "{{ RadiusSettings }}"
}'
;

enable_sso

Enables single sign-on for a directory. Single sign-on allows users in your directory to access certain Amazon Web Services services from a computer joined to the directory without having to enter their credentials separately.

EXEC aws.ds.directories.enable_sso 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"UserName": "{{ UserName }}", 
"Password": "{{ Password }}"
}'
;

reset_user_password

Resets the password for any user in your Managed Microsoft AD or Simple AD directory. Disabled users will become enabled and can be authenticated following the API call. You can reset the password for any user in your directory with the following exceptions: For Simple AD, you cannot reset the password for any user that is a member of either the Domain Admins or Enterprise Admins group except for the administrator user. For Managed Microsoft AD, you can only reset the password for a user that is in an OU based off of the NetBIOS name that you typed when you created your directory. For example, you cannot reset the password for a user in the Amazon Web Services Reserved OU. For more information about the OU structure for an Managed Microsoft AD directory, see What Gets Created in the Directory Service Administration Guide.

EXEC aws.ds.directories.reset_user_password 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"UserName": "{{ UserName }}", 
"NewPassword": "{{ NewPassword }}"
}'
;

share_directory

Shares a specified directory (DirectoryId) in your Amazon Web Services account (directory owner) with another Amazon Web Services account (directory consumer). With this operation you can use your directory from any Amazon Web Services account and from any Amazon VPC within an Amazon Web Services Region. When you share your Managed Microsoft AD directory, Directory Service creates a shared directory in the directory consumer account. This shared directory contains the metadata to provide access to the directory within the directory owner account. The shared directory is visible in all VPCs in the directory consumer account. The ShareMethod parameter determines whether the specified directory can be shared between Amazon Web Services accounts inside the same Amazon Web Services organization (ORGANIZATIONS). It also determines whether you can share the directory with any other Amazon Web Services account either inside or outside of the organization (HANDSHAKE). The ShareNotes parameter is only used when HANDSHAKE is called, which sends a directory sharing request to the directory consumer.

EXEC aws.ds.directories.share_directory 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"ShareNotes": "{{ ShareNotes }}", 
"ShareTarget": "{{ ShareTarget }}", 
"ShareMethod": "{{ ShareMethod }}"
}'
;

start_schema_extension

Applies a schema extension to a Microsoft AD directory.

EXEC aws.ds.directories.start_schema_extension 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"CreateSnapshotBeforeSchemaExtension": {{ CreateSnapshotBeforeSchemaExtension }}, 
"LdifContent": "{{ LdifContent }}", 
"Description": "{{ Description }}"
}'
;

unshare_directory

Stops the directory sharing between the directory owner and consumer accounts.

EXEC aws.ds.directories.unshare_directory 
@region='{{ region }}' --required 
@@json=
'{
"DirectoryId": "{{ DirectoryId }}", 
"UnshareTarget": "{{ UnshareTarget }}"
}'
;