Connector Configuration

Prerequisites

• Active Directory domain controller accessible from Identity Mesh (or from the relay agent that runs the connector)
• Service account with read permissions (or read/write for bi-directional sync), supplied through the connector's authentication settings as a secret reference, never in the config JSON
• LDAP port 389 (or LDAPS port 636) open in firewall. LDAPS (port 636) is required for password provisioning via EnableAfterCreate
• Base DN for the domain (or one per domain when the connector spans a forest)

Configuration Example

{
  "type": "active-directory",
  "name": "Corporate AD",
  "config": {
    "LdapServer": "dc01.corp.contoso.com",
    "LdapPort": 636,
    "UseSsl": true,
    "BaseDn": "DC=corp,DC=contoso,DC=com",
    "PageSize": 500,
    "ExternalIdAttribute": "objectGUID",
    "DeltaAttribute": "uSNChanged",
    "EnableAfterCreate": true,
    "DeleteMode": "disable",
    "ObjectTypes": [
      {
        "Name": "user",
        "Attributes": [
          "sAMAccountName", "userPrincipalName", "mail", "givenName", "sn",
          "displayName", "employeeNumber", "manager", "objectSid"
        ],
        "Filter": null,
        "Export": {
          "CreateEnabled": true,
          "DefaultContainer": "OU=Staff,DC=corp,DC=contoso,DC=com",
          "DeleteMode": "disable"
        }
      },
      {
        "Name": "group",
        "Attributes": ["cn", "member", "managedBy", "groupType"],
        "Filter": "(&(objectClass=group)(groupType:1.2.840.113556.1.4.803:=2147483648))",
        "Export": {
          "CreateEnabled": true,
          "DefaultContainer": "OU=Groups,DC=corp,DC=contoso,DC=com",
          "DeleteMode": "delete"
        }
      }
    ]
  }
}

Connection Fields

Object Types

Each entry in ObjectTypes names one structural class the connector handles. In the Admin Portal this is the What to import and export step of the AD connector form: type chips, a class search backed by the forest schema, a per-type attribute picker scoped to that class, and the export defaults with an OU browser. The connector always keeps at least one type; the last remaining type cannot be removed.

How the Import Is Built

• • The connector runs one LDAP search per domain. The filter is the OR of every type's clause, and the requested attributes are the union of every type's list plus objectGUID, uSNChanged and objectClass.
• • Each returned entry is typed from its objectClass, so a single search feeds every configured type.
• • A domain's own Filter (on a Partitions entry) replaces the whole derived filter for that domain, not just one type's clause.
• • When you save a connector, the API warns if an attribute flow rule maps an attribute that no type will load. Add the attribute to the right type, or the flow will never see a value.

Delete Modes

A Delete export reaches the connector when a projection rule with DeleteIfUnlinked stops matching an object that exists in AD, or when a self-service group is removed. The mode decides what the connector does with it. Values are matched case-insensitively.

Export Behaviour Notes

• • Single-valued DN references such as manager, managedBy and secretary are resolved to the referenced object's DN on updates as well as creates.
• • An attribute sent with an explicit empty value is cleared in AD. An attribute absent from the change is left untouched.
• • distinguishedName is never written; the object's DN comes from its container and RDN.
• • Group membership is written as a replace, so emptying an already-empty group succeeds.

Schema Discovery

The class search in the portal is backed by an endpoint that reads the forest schema and returns every structural class with its required and optional attributes. You can call it directly with the connector's config JSON; credentials are resolved the same way the connector resolves them at run time, so a secret reference works. Requires connectors.write.

POST /api/connectors/discover-classes
Content-Type: application/json
Authorization: Bearer {{api_token}}

{
  "configJson": "{ \"LdapServer\": \"dc01.corp.contoso.com\", \"BaseDn\": \"DC=corp,DC=contoso,DC=com\", \"UseSsl\": true }",
  "partitionId": null
}

Prerequisites

• Azure AD tenant with appropriate licensing
• App registration in Azure AD with required API permissions
• Client ID and client secret from app registration
• Tenant ID (directory ID)

Configuration Example

{
  "type": "entra-id",
  "name": "Contoso Entra ID",
  "config": {
    "TenantId": "12345678-1234-1234-1234-123456789abc",
    "GroupSelectionFilter": "startswith(displayName,'IM-')",
    "PageSize": 999,
    "ImportUsers": true,
    "ImportGroups": true,
    "ImportMemberships": true,
    "ExternalIdAttribute": "id",
    "ObjectTypes": [
      { "name": "User",  "attributes": ["id", "userPrincipalName", "displayName", "mail", "department", "jobTitle", "accountEnabled"] },
      { "name": "Group", "attributes": ["id", "displayName", "mailNickname", "groupTypes", "securityEnabled"] }
    ]
  },
  "auth": {
    "Mode": "ClientSecret",
    "ClientId": "87654321-4321-4321-4321-cba987654321",
    "ClientSecret": "secret://entra/contoso/clientsecret"
  }
}

Required API Permissions

Configuration Example

{
  "type": "okta",
  "name": "Okta Production",
  "config": {
    "OrgDomain": "contoso.okta.com",
    "UserSearchFilter": "status eq \"ACTIVE\"",
    "PageSize": 200,
    "ImportUsers": true,
    "ImportGroups": true,
    "ImportMemberships": true,
    "ExternalIdAttribute": "id"
  },
  "auth": {
    "Mode": "ApiKey",
    "ApiKey": "secret://okta/contoso/apitoken"
  }
}

Prerequisites

• SQL Server instance accessible from Identity Mesh
• Database account with read permissions on the source table or view
• A datetime2 column for delta tracking (not date which lacks time granularity)
• A unique identifier column for each row (e.g., primary key)

Configuration Example

{
  "type": "sql",
  "name": "HR Database",
  "config": {
    "connectionString": "Server=hrdb.company.com;Database=HRSystem;",
    "importQuery": "dbo.Employees",
    "externalIdColumn": "EmployeeId",
    "objectType": "User",
    "deltaColumn": "ModifiedDateUtc",
    "deltaColumnType": "datetime",
    "softDeleteColumn": "IsActive",
    "softDeleteValue": "false",
    "columnsToLoad": ["EmployeeId", "Email", "DisplayName", "Department", "Title", "ManagerEmail"]
  }
}

Configuration Fields

Dynamic Target Container

Projection rules support {{attribute}} templates in the Target Container field. At projection time, tokens are resolved against the mesh object's attributes, placing objects into different OUs automatically.

OU={{department}},OU=Users,DC=corp,DC=com

If a user's department attribute is Engineering, the resolved container becomes OU=Engineering,OU=Users,DC=corp,DC=com. Unresolved tokens (missing or null attributes) are left as-is.

Authentication Modes