dotnet / dotnet/runtime

[API Proposal]: System.DirectoryServices.Protocols: Add new directory search control for LDAP_SERVER_DIRSYNC_EX_OID

Open
#120,022 4 comments 0 reactions 0 assignees View on GitHub
api-suggestion area-System.DirectoryServices needs-further-triage
Dominant language
C#
Stars
18.3k
Forks
5.6k
PR merge metrics
PR metrics pending

Description

### Background and motivation

Active Directory implemented the LDAP_SERVER_DIRSYNC_EX_OID search control in 2012. The OID is 1.2.840.113556.1.4.2090. Its behavior mirrors the regular LDAP_SERVER_DIRSYNC_OID control except it provides a mechanism to return specified directory attributes even if they have not changed.

See ref: https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-adts/a568cbbe-5082-45ca-9427-0a6793646b89

Adding a directory control and response for this extended version of the DirSync control would be helpful for various DirSync change polling applications that use the DirectoryServices.Protocols API.

### API Proposal

The main, perhaps only, file that would need to be changed is:
https://github.com/dotnet/dotnet/blob/30000d883e06c122311a66894579bc12329a09d4/src/runtime/src/libraries/System.DirectoryServices.Protocols/src/System/DirectoryServices/Protocols/common/DirectoryControl.cs

One possible approach is to simply add new request and response classes.

```csharp
namespace System.DirectoryServices.Protocols;

public class DirSyncExtendedRequestControl : DirectoryControl
{
public DirSyncExtendedRequestControl() : base("1.2.840.113556.1.4.2090", null, true, true) { }
// Other ctor signatures and members to match existing DirSyncRequestControl
}

public class DirSyncExtendedResponseControl : DirectoryControl
{
internal DirSyncExtendedResponseControl(byte[] cookie, bool moreData,
int resultSize, bool criticality, byte[] controlValue)
: base("1.2.840.113556.1.4.2090", controlValue, criticality, true)
{
// set properties/fields as done in DirSyncResponseControl
}
}

internal static void TransformControls(DirectoryControl[] controls)
{
// Slight changes in this method to add a condition matching the new OID above
}

### API Usage

```csharp
byte[]? currCookie = null;
var dirSyncExt = new DirSyncExtendedControl()
{
Cookie = currCookie,
// etc
};
var searchReq = new SearchRequest()
{
Filter = "(objectCategory=group)",
// etc
};
searchReq.Controls.Add(dirSyncExt);
// Perform DirSync polling per usual
```

### Alternative Designs

_No response_

### Risks

The LDAP_SERVER_DIRSYNC_EX_OID is an Active Directory MS-ADTS extension, meaning any new request/response controls for it may not be usable on other LDAP platforms, though I believe that is already the case with some LDAP OIDs in DirectoryServices.Protocols. In any case, the new classes could be decorated with [SupportedOSPlatform("windows")].

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.