> ## 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.

## 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

**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.

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**.

**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.

## 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

> **[LDAP](/reference/orchestrator/identity-fabric/ldap)**
>
> Generic LDAP connector for non-AD directories

> **[Identity Fabric](/reference/orchestrator/identity-fabric)**
>
> Overview of all identity providers

> **[Identity Fabric](/reference/orchestrator/identity-fabric#configuration-reference)**
>
> Complete field reference for all connector types

> **[Continuity](/reference/orchestrator/identity-fabric/continuity)**
>
> IdP failover connector for hybrid AD/cloud scenarios