# Extend your AWS Managed Microsoft AD schema
Extend your directory schema

AWS Managed Microsoft AD uses schemas to organize and enforce how directory data is stored. The process of adding definitions to the schema is referred to as "extending the schema." Schema extensions make it possible for you to modify the schema of your AWS Managed Microsoft AD directory using a valid LDAP Data Interchange Format (LDIF) file. For more information about AD schemas and how to extend your schema, see the topics listed below.

## When to extend your AWS Managed Microsoft AD schema


You can extend your AWS Managed Microsoft AD schema by adding new object classes and attributes. For example, you might do this if you have an application that requires changes to your schema in order to support single sign-on capabilities. 

You can also use schema extensions to enable support for applications that rely on specific Active Directory object classes and attributes. This can be especially useful in the case where you need to migrate corporate applications that are dependent on AWS Managed Microsoft AD, to the AWS cloud.

Each attribute or class that is added to an existing Active Directory schema must be defined with a unique ID. That way when companies add extensions to the schema, they can be guaranteed to be unique and not to conflict with each other. These IDs are referred to as AD Object Identifiers (OIDs) and are stored in AWS Managed Microsoft AD.

To get started, see [Tutorial: Extending your AWS Managed Microsoft AD schema](ms_ad_tutorial_extend_schema.md).

### Related topics

+ [Extend your AWS Managed Microsoft AD schema](#ms_ad_schema_extensions)
+ [Schema elements](ms_ad_key_concepts.md#ms_ad_schema_elements)

**Topics**
+ [

## When to extend your AWS Managed Microsoft AD schema
](#ms_ad_schema_when_to_extend)
+ [

# Tutorial: Extending your AWS Managed Microsoft AD schema
](ms_ad_tutorial_extend_schema.md)

# Tutorial: Extending your AWS Managed Microsoft AD schema


In this tutorial, you will learn how to extend the schema for your AWS Directory Service for Microsoft Active Directory directory, also known as AWS Managed Microsoft AD, by adding unique *attributes* and *classes* that meet your specific requirements. AWS Managed Microsoft AD schema extensions can only be uploaded and applied using a valid LDIF (Lightweight Directory Interchange Format) script file.

Attributes (attributeSchema) define the fields in the database while classes (classSchema) define the tables in the database. For example, all of the user objects in Active Directory are defined by the schema class *User* while the individual properties of a user, such as email address or phone number, are each defined by an attribute. 

If you wanted to add a new property, such as Shoe-Size, you would define a new attribute, which would be of type *integer*. You could also define lower and upper limits like 1 to 20. Once the Shoe-Size attributeSchema object has been created, you would then alter the *User* classSchema object to contain that attribute. Attributes can be linked to multiple classes. Shoe-Size could also be added to the *Contact* class for example. For more information about Active Directory schemas, see [When to extend your AWS Managed Microsoft AD schema](ms_ad_schema_extensions.md#ms_ad_schema_when_to_extend).

This workflow has three basic steps. 

![\[Diagram showing the steps for the tutorial: 1 create a LDIF file, 2 import the LDIF file, and 3 verify schema changes.\]](http://docs.aws.amazon.com/directoryservice/latest/admin-guide/images/tutorialextendadschema.png)


**[Step 1: Create your LDIF file](create.md)**  
First, you create an LDIF file and define the new attributes and any classes that the attributes should be added to. You use this file for the next phase of the workflow.

**[Step 2: Import your LDIF file](import.md)**  
In this step, you use the AWS Directory Service console to import the LDIF file to your Microsoft Active Directory environment.

**[Step 3: Verify if the schema extension was successful](verify.md)**  
Finally, as an administrator, you use an EC2 instance to verify that the new extensions appear in the Active Directory Schema Snap-in.

# Step 1: Create your LDIF file


An LDIF file is a standard plain text data interchange format for representing [LDAP](https://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol) (Lightweight Directory Access Protocol) directory content and update requests. LDIF conveys directory content as a set of records, one record for each object (or entry). It also represents update requests, such as Add, Modify, Delete, and Rename, as a set of records, one record for each update request. 

The AWS Directory Service imports your LDIF file with the schema changes by running the `ldifde.exe` application on your AWS Managed Microsoft AD directory. Therefore, you will find it helpful to understand the LDIF script syntax. For more information, see [LDIF Scripts](https://msdn.microsoft.com/en-us/library/ms677268(v=vs.85).aspx). 

Several third-party LDIF tools can extract, clean-up, and update your schema updates. Regardless of which tool you use, it is important to understand that all identifiers used in your LDIF file must be unique. 

We highly recommend that you review the following concepts and tips prior to creating your LDIF file.
+ **Schema elements** – Learn about schema elements such as attributes, classes, object IDs, and linked attributes. For more information, see [Schema elements](ms_ad_key_concepts.md#ms_ad_schema_elements).
+ **Sequence of items** – Make sure that the order in which the items in your LDIF file are laid out follow the [Directory Information Tree (DIT)](https://en.wikipedia.org/wiki/Directory_information_tree) from the top down. The general rules for sequencing in an LDIF file include the following: 

   
  + Separate items with a blank line.
  + List child items after their parent items. 
  + Ensure that items such as attributes or object classes exist in the schema. If they are not present, you must add them to the schema before they can be used. For example, before you can assign an attribute to a class, the attribute must be created. 
+ **Format of the DN** – For each new instruction in the LDIF file, define the distinguished name (DN) as the first line of the instruction. The DN identifies an Active Directory object within the Active Directory object's tree and must contain the domain components for your directory. For example, the domain components for the directory in this tutorial are `DC=example,DC=com`.

  The DN must include the Active Directory object's common name (CN). The first CN entry represents the attribute or class name. To extend the Active Directory schema, use `CN=Schema,CN=Configuration`. Remember that you cannot modify Active Directory object content. The general DN format follows.

  ```
  dn: CN=[attribute or class name],CN=Schema,CN=Configuration,DC=[domain_name]
  ```

  For this tutorial, the DN for the new Shoe-Size attribute would look like:

  ```
  dn: CN=Shoe-Size,CN=Schema,CN=Configuration,DC=example,DC=com
  ```
+ **Warnings** – Review the warnings below before you extend your schema.
  + Before you extend your Active Directory schema, it is important to review Microsoft's warnings on the impact of this operation. For more information, see [What You Must Know Before Extending the Schema](https://msdn.microsoft.com/en-us/library/ms677995(v=vs.85).aspx).
  + You cannot delete a schema attribute or class. Therefore, if you make a mistake and don't want to restore from backup, you can only disable the object. For more information, see [Disabling Existing Classes and Attributes](https://msdn.microsoft.com/en-us/library/ms675903(v=vs.85).aspx).
  + Changes to defaultSecurityDescriptor are not supported.

To learn more about how LDIF files are constructed and see a sample LDIF file that can be used for testing AWS Managed Microsoft AD schema extensions, see the article [How to Extend your AWS Managed Microsoft AD Directory Schema](https://aws.amazon.com/blogs/security/how-to-add-more-application-support-to-your-microsoft-ad-directory-by-extending-the-schema/) on the AWS Security Blog.

**Next Step**

[Step 2: Import your LDIF file](import.md)

# Step 2: Import your LDIF file


You can extend your schema by importing an LDIF file from either the AWS Directory Service console or by using the API. For more information about how to do this with the schema extension APIs, see the [https://docs.aws.amazon.com/directoryservice/latest/devguide/](https://docs.aws.amazon.com/directoryservice/latest/devguide/). At this time, AWS does not support external applications, such as Microsoft Exchange, to perform schema updates directly. 

**Important**  
When you make an update to your AWS Managed Microsoft AD directory schema, the operation is not reversible. In other words, once you create a new class or attribute, Active Directory doesn't allow you to remove it. However, you can disable it.   
If you must delete the schema changes, one option is to restore the directory from a previous snapshot. Restoring a snapshot rolls both the schema and the directory data back to a previous point, not just the schema. Note, the maximum supported age of a snapshot is 180 days. For more information, see [Useful shelf life of a system-state backup of Active Directory](https://learn.microsoft.com/en-us/troubleshoot/windows-server/backup-and-storage/shelf-life-system-state-backup-ad) on the Microsoft website.

Before the update process begins, AWS Managed Microsoft AD takes a snapshot to preserve the current state of your directory.

**Note**  
Schema extensions is a global feature of AWS Managed Microsoft AD. If you are using [Configure Multi-Region replication for AWS Managed Microsoft AD](ms_ad_configure_multi_region_replication.md), the following procedures must be performed in the [Primary Region](multi-region-global-primary-additional.md#multi-region-primary). The changes will be applied across all replicated Regions automatically. For more information, see [Global vs Regional features](multi-region-global-region-features.md).

**To import your LDIF file**

1. In the [AWS Directory Service console](https://console.aws.amazon.com/directoryservicev2/) navigation pane, select **Directories**.

1. On the **Directories** page, choose your directory ID.

1. On the **Directory details** page, do one of the following:
   + If you have multiple Regions showing under **Multi-Region replication**, select the primary Region, and then choose the **Maintenance** tab. For more information, see [Primary vs additional Regions](multi-region-global-primary-additional.md).
   + If you do not have any Regions showing under **Multi-Region replication**, choose the **Maintenance** tab.

1. In the **Schema extensions** section, choose **Actions**, and then select **Upload and update schema**.

1. In the dialog box, click **Browse**, select a valid LDIF file, type a description, and then choose **Update Schema**.
**Important**  
Extending the schema is a critical operation. Don't apply any schema update in production environment without first testing it with your application in a development or test environment.

## How is the LDIF file applied


After your LDIF file has been uploaded, AWS Managed Microsoft AD takes steps to protect your directory against errors as it applies the changes in the following order. 

1. **Validates the LDIF file.** Since LDIF scripts can manipulate any object in the domain, AWS Managed Microsoft AD runs checks right after you upload to help ensure that the import operation will not fail. These include checks to ensure the following:
   + The objects to be updated are only held in the schema container
   + The DC (domain controllers) part matches the name of the domain where the LDIF script is running

1. **Takes a snapshot of your directory.** You can use the snapshot to restore your directory in case you encounter any problems with your application after updating the schema. 

1. **Applies the changes to a single DC.** AWS Managed Microsoft AD isolates one of your DCs and applies the updates in the LDIF file to the isolated DC. It then selects one of your DCs to be the primary schema, removes that DC from directory replication, and applies your LDIF file using `Ldifde.exe`.

1. **Replication occurs to all DCs.** AWS Managed Microsoft AD adds the isolated DC back in to replication to complete the update. While this is all happening, your directory continues to provide the Active Directory service to your applications without disruption.

**Next step**

[Step 3: Verify if the schema extension was successful](verify.md)

# Step 3: Verify if the schema extension was successful


After you have finished the import process, it is important to verify that schema updates were applied to your directory. This is especially critical before you migrate or update any application that relies on the schema update. You can do this using a variety of different LDAP tools or by writing a test tool that issues the appropriate LDAP commands. 

This procedure uses the Active Directory Schema Snap-in and/or PowerShell to verify that the schema updates were applied. You must run these tools from a computer that is domain joined to your AWS Managed Microsoft AD. This can be a Windows server running in your on-premises network with access to your virtual private cloud (VPC) or through a virtual private network (VPN) connection. You can also run these tools on an Amazon EC2 Windows instance (see [How to launch a new EC2 instance with seamless domain join](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/ec2-join-aws-domain.html#join-domain-console)).

**To verify using the Active Directory Schema Snap-in**

1. Install the Active Directory Schema Snap-In using the instructions on the [TechNet](https://technet.microsoft.com/en-us/library/cc732110.aspx) website. 

1. Open the Microsoft Management Console (MMC) and expand the **AD Schema** tree for your directory. 

1. Navigate through the **Classes** and **Attributes** folders until you find the schema changes that you made earlier.

**To verify using PowerShell**

1. Open a PowerShell window.

1. Use the `Get-ADObject` cmdlet as shown below to verify the schema change. For example:

   `get-adobject -Identity 'CN=Shoe-Size,CN=Schema,CN=Configuration,DC=example,DC=com' -Properties *`

**Optional step**

[Add a value to the new attribute - Optional](addvalue.md)

# Add a value to the new attribute - Optional


Use this optional step when you have created a new attribute and want to add a new value to the attribute in your AWS Managed Microsoft AD directory.

**To add a value to an attribute**

1. Open the PowerShell command line utility and set the new attribute with the following command. In this example, we will add a new EC2InstanceID value to the attribute for a specific computer.

   `PS C:\> set-adcomputer -Identity computer name -add @{example-EC2InstanceID = 'EC2 instance ID'}`

1. You can validate if the EC2InstanceID value was added to the computer object by running the following command:

   `PS C:\> get-adcomputer -Identity computer name –Property example-EC2InstanceID`

# Related resources


The following resource links are located on the Microsoft website and provide related information. 

 
+ [Extending the Schema (Windows)](https://msdn.microsoft.com/en-us/library/ms676900(v=vs.85).aspx)
+ [Active Directory Schema (Windows)](https://msdn.microsoft.com/en-us/library/ms674984(v=vs.85).aspx)
+ [Active Directory Schema](https://technet.microsoft.com/en-us/library/cc961581.aspx)
+ [Windows Administration: Extending the Active Directory Schema](https://technet.microsoft.com/en-us/magazine/a39543ba-e561-4933-b590-0878885f44f5)
+ [Restrictions on Schema Extension (Windows)](https://msdn.microsoft.com/en-us/library/ms677924(v=vs.85).aspx)
+ [Ldifde](https://technet.microsoft.com/en-us/library/cc731033(v=ws.11).aspx)