> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Microsoft Active Directory

The Active Directory connector integrates the Maverics Orchestrator with on-premises Microsoft Active Directory environments -- providing LDAP-based authentication and attribute lookup for SSO with AD-connected applications.

<Note>
  **Console terminology:** In the Maverics Console, this section is called
  **Identity Fabric**. The YAML configuration uses the `connectors` key to define
  identity provider integrations.
</Note>

## Overview

The Active Directory connector uses the LDAP protocol internally to communicate with AD domain controllers. It shares the same configuration field set as the [LDAP connector](/reference/orchestrator/identity-fabric/ldap) with defaults and conventions optimized for Active Directory environments. The key difference is the connector type, which determines internal handling specific to Active Directory.

## Use Cases

* **Unify SSO for AD-dependent applications** -- Extend single sign-on to applications that rely on AD domain credentials, Kerberos, or NTLM without rewriting the application or migrating users out of Active Directory
* **Consolidate AD with cloud IdPs** -- Route AD-bound applications through the Orchestrator alongside cloud IdP applications, reducing the number of standalone identity integrations and simplifying licensing
* **AD-to-cloud failover** -- Pair with the [Continuity connector](/reference/orchestrator/identity-fabric/continuity) to fail over between Active Directory and a cloud IdP, ensuring authentication continues during outages on either side
* **AD attribute enrichment** -- Retrieve AD user attributes (display name, group memberships, email, department) for header injection, claim enrichment, or policy evaluation in legacy and modern applications

## Setup

<Tabs>
  <Tab title="Console UI">
    To create a Microsoft Active Directory connector in the Maverics Console:

    1. Navigate to **Identity Fabric** in the Console sidebar.
    2. Click **Create** and select **Microsoft Active Directory**.
    3. Enter a **Name** for the connector.
    4. Enter one or more **URLs** for the Active Directory server (e.g., `ldaps://dc1.corp.example.com:636`). Multiple URLs enable domain controller failover.
    5. Enter the **Service Account Username** (bind DN used to connect to the server).
    6. Enter the **Service Account Password**.
    7. Enter the **Base DN** for LDAP searches (e.g., `dc=corp,dc=example,dc=com`).
    8. Enter the **OUD Search Key** -- the attribute used to filter on during query and bind operations. For Active Directory, use `sAMAccountName`.

    <Note>
      The Console labels this field **OUD Search Key**. It maps to the `usernameSearchKey` field in the YAML configuration.
    </Note>

    9. Optionally select an **Authentication Search Scope** from the dropdown.
    10. Optionally set a **Login URL** for a custom endpoint for posting user credentials.
    11. Optionally set **Custom Login HTML** to present a custom page for authentication.
    12. Optionally set a **CA Path** for the certificate authority when using self-signed certificates.
    13. Click **Save**.
  </Tab>

  <Tab title="Configuration">
    ```yaml maverics.yaml theme={null}
    connectors:
      - name: ad
        type: activedirectory
        url:
          - "ldaps://dc1.corp.example.com:636"
          - "ldaps://dc2.corp.example.com:636"
        serviceAccountUsername: "cn=svc-maverics,ou=Service Accounts,dc=corp,dc=example,dc=com"
        serviceAccountPassword: <vault.ad_password>
        baseDN: "dc=corp,dc=example,dc=com"
        usernameSearchKey: sAMAccountName
        enableAuthentication: true
        userAttributes:
          - sAMAccountName
          - mail
          - displayName
          - memberOf
        attributeMapping:
          email: mail
          name: displayName
          username: sAMAccountName
        tls: ad-tls
    ```

    ## Configuration Reference

    The Active Directory connector uses the same field set as the LDAP connector. All fields documented on the [LDAP connector page](/reference/orchestrator/identity-fabric/ldap) apply to `type: activedirectory`.

    | Key                         | Type      | Required | Description                                                                                                                                            |
    | --------------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `name`                      | string    | Yes      | Unique connector identifier referenced by app policies and attribute providers                                                                         |
    | `type`                      | string    | Yes      | Must be `activedirectory`                                                                                                                              |
    | `url`                       | string\[] | Yes      | AD domain controller URLs -- supports `ldap://` (port 389) and `ldaps://` (port 636); multiple URLs enable domain controller failover                  |
    | `serviceAccountUsername`    | string    | Yes      | Bind DN for the service account (e.g., `cn=svc-maverics,ou=Service Accounts,dc=corp,dc=example,dc=com`)                                                |
    | `serviceAccountPassword`    | string    | Yes      | Service account password -- use secret reference syntax `<namespace.key>`                                                                              |
    | `baseDN`                    | string    | Yes      | Base DN for LDAP searches (e.g., `dc=corp,dc=example,dc=com`)                                                                                          |
    | `usernameSearchKey`         | string    | No       | LDAP attribute used for username lookup -- use `sAMAccountName` for AD environments                                                                    |
    | `userRDNKey`                | string    | No       | Relative Distinguished Name key for user entries                                                                                                       |
    | `enableAuthentication`      | boolean   | No       | Enable LDAP bind authentication for end users                                                                                                          |
    | `loginUrl`                  | string    | No       | URL for the LDAP login form                                                                                                                            |
    | `authenticationSearchScope` | string    | No       | LDAP search scope for authentication queries                                                                                                           |
    | `userAttributes`            | string\[] | No       | AD attributes to retrieve during searches (e.g., `["sAMAccountName", "mail", "displayName", "memberOf"]`)                                              |
    | `objectClasses`             | string\[] | No       | Object classes for the LDAP search filter                                                                                                              |
    | `attributeMapping`          | map       | No       | Map Orchestrator attribute names to AD attribute names (e.g., `email: "mail"`)                                                                         |
    | `attributeDelimiter`        | string    | No       | Delimiter for multi-valued attributes (default: `","`)                                                                                                 |
    | `customLogin.templateFile`  | string    | No       | Path to a custom HTML login form template                                                                                                              |
    | `tls`                       | string    | No       | Named TLS profile for AD connection                                                                                                                    |
    | `healthCheck`               | object    | No       | Health check monitoring configuration (see [Identity Fabric Configuration Reference](/reference/orchestrator/identity-fabric#configuration-reference)) |

    For the complete connector field reference including health check details, see [Identity Fabric Configuration Reference](/reference/orchestrator/identity-fabric#configuration-reference).

    <Note>
      The `activedirectory` connector type uses the LDAP protocol internally. It shares the same configuration fields as the [LDAP connector](/reference/orchestrator/identity-fabric/ldap). The key difference is the `type` value, which determines internal handling specific to Active Directory environments.
    </Note>
  </Tab>
</Tabs>

## AD-Specific Notes

* **Use `sAMAccountName` as the `usernameSearchKey`** -- In Active Directory environments, users typically log in with their `sAMAccountName` (e.g., `jsmith`), not the `uid` attribute used by generic LDAP directories.
* **Multiple `url` entries support domain controller failover** -- List multiple domain controller URLs to ensure authentication continues if a DC becomes unavailable. The Orchestrator will try each URL in order.
* **For LDAPS, ensure the TLS profile includes AD's root CA** -- Active Directory Certificate Services (AD CS) often uses an internal CA. The TLS profile referenced by the `tls` field must include this CA certificate via `caFile`.
* **Common AD attributes** -- `sAMAccountName` (login name), `mail` (email), `displayName` (full name), `memberOf` (group memberships), `department`, `title`, `manager`.

## Troubleshooting

* **Service account permissions** -- The service account must have read access to the `baseDN` subtree. In AD, this typically means the account needs "Read all properties" permission on user objects in the target OU.
* **LDAPS certificate trust** -- AD domain controllers use certificates issued by AD CS. Export the root CA certificate and include it in the TLS profile. Without it, LDAPS connections will fail with certificate verification errors.
* **Distinguished Name format** -- AD uses a specific DN format with OUs (e.g., `cn=svc-maverics,ou=Service Accounts,dc=corp,dc=example,dc=com`). Verify the exact DN using `dsquery` or Active Directory Users and Computers.
* **Group membership depth** -- The `memberOf` attribute only shows direct group memberships, not nested groups. For nested group resolution, consider using a group search filter or a Service Extension.

## Related Pages

<CardGroup cols={2}>
  <Card title="LDAP" icon="database" href="/reference/orchestrator/identity-fabric/ldap">
    Generic LDAP connector for non-AD directories
  </Card>

  <Card title="Identity Fabric" icon="id-badge" href="/reference/orchestrator/identity-fabric">
    Overview of all identity providers
  </Card>

  <Card title="Identity Fabric" icon="code" href="/reference/orchestrator/identity-fabric#configuration-reference">
    Complete field reference for all connector types
  </Card>

  <Card title="Continuity" icon="arrows-rotate" href="/reference/orchestrator/identity-fabric/continuity">
    IdP failover connector for hybrid AD/cloud scenarios
  </Card>
</CardGroup>