Microsoft Active Directory

​

Overview

​

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

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

​

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