About schema extension

This page describes how schema extension works in Managed Service for Microsoft Active Directory.

Overview

Active Directory relies on schema to organize and store the directory data. The AD schema defines the object classes and its attributes that are used to store the directory data.

You can use schema extensions to perform schema changes and enable support for applications which are dependent on specific classes or attributes in Active Directory.

You can extend the default AD schema by defining new classes and attributes or modifying the definitions or properties of existing classes and attributes. Managed Microsoft AD lets you extend the schema using an LDAP Data Interchange Format (LDIF) file that contains commands for schema changes. For more information, see Extending the Schema.

For more information about LDIF, see LDAP Data Interchange Format.

How to prepare your LDIF file

An LDIF file is a standard plain text data interchange format for representing Lightweight Directory Access Protocol (LDAP) directory content and update requests. An LDIF file consists of a series of records that represents a collection of update requests, such as add, modify, rename. Blank lines separate the set of records in the LDIF file representing each entry of update request. We recommend you to understand the format of LDIF files before creating your file with schema changes. For more information, see LDIF Scripts.

Before preparing your LDIF file, read the following guidelines.

Schema elements

Schema elements, such as classes, attributes, objects, are the building blocks of an AD schema. We recommend you to learn the key concepts related to schema elements such as attributes, object classes, object identifiers, and linked attributes. For more information, see Active Directory Schema (AD DS).

LDIF file structure

You need to arrange the entries in an LDIF file by using the Directory Information Tree (DIT) structure. The structure of a valid LDIF file must adhere to the following guidelines:

  • List the parent entries before the child entries.
  • Separate the entries in an LDIF file with a blank line.
  • Any class or attribute that you use in an entry must exist in the schema. Before using a class or attribute, make sure you verify if it is available in the schema. If not, you need to add the class or attribute to the schema. For example, you need to create an attribute before attaching the attribute with a class.

Distinguished name format

All entries in an LDIF file begin with a distinguished name (DN). It specifies the AD object upon which the records operate on. In case the records update schema cache, DN must be empty. For schema changes, DN must be in the following format:

dn: cn=CLASS_OR_ATTRIBUTE,cn=Schema,cn=Configuration,dc=ROOT_DOMAIN,dc=TOP_LEVEL_DOMAIN

Replace the following:

  • CLASS_OR_ATTRIBUTE: The name of a class or attribute. For example, example-attribute.
  • ROOT_DOMAIN: The root domain of your domain name. For example, if your domain name is example.com, enter example.
  • TOP_LEVEL_DOMAIN: The top-level domain of your domain name. For example, if your domain name is example.com, enter com.

For example, the DN of an attribute example-attribute for domain name example.com must be in the following format:

dn: cn=example-attribute,cn=Schema,cn=Configuration,dc=example,dc=com

Supported LDIF changetypes

Managed Microsoft AD supports the following LDIF changetypes for schema extension:

LDIF changetype Schema extension action
add Creates a new class or attribute in the schema.
modify Updates the properties of a class or attribute in the schema. The following list describes some of the possible property updates:
  • Attaching an attribute to a class.
  • Updating the ldapDisplayName property of a class or attribute.
  • Disabling a class or attribute.
    		•
    modrdn or moddn Renames the relative distinguished name (RDN) for a class or attribute.

    Considerations

    Before you extend the schema, make sure you refer to the following considerations.

    • Microsoft provides detailed advisories describing the impact of schema extensions on your Active Directory environment. Make sure you review them carefully before extending the schema. For more information, see What You Must Know Before Extending the Schema.
    • Adding a class or attribute to the schema is permanent. However, you can disable a class or attribute that you no longer require after adding it. For more information, see Disabling Existing Classes and Attributes.

    How schema extension works

    When you initiate schema extension for a domain, Managed Microsoft AD validates the LDIF file for structure, format of schema elements, and supported changetypes or actions.

    If the LDIF file is valid, Managed Microsoft AD takes a backup of the domain before applying the schema changes. If you encounter any problems with your application after updating the schema, you can use this backup to restore the domain. Then, Managed Microsoft AD isolates one of your domain controllers from the domain and applies the schema changes using the Ldifde tool. While schema changes are in progress, other domain controllers in your domain serve the client traffic.

    If the schema changes succeed, then the isolated domain controller connects back to the domain and replicates these schema changes to other domain controllers in the domain.

    If the schema changes fail, Managed Microsoft AD reverts the domain controller to the backed up state.

    Managed Microsoft AD doesn't support partial schema extension on a domain. In other words, if any of the commands in the LDIF file fails to apply on the domain, the schema extension request fails. Managed Microsoft AD also reverts your domain back to the state it was prior to applying the schema changes.

    What's next