Document LDAP group common-name requirements for Negotiate role claims
- Dominant language
- C#
- Stars
- 38.4k
- Forks
- 10.9k
- Avg merge
- 2d 10h
- Merged PRs (30d)
- 281
Description
## Summary
The Negotiate LDAP claim resolver maps direct and nested LDAP group memberships to role claims using each group's common name (CN). The public configuration API doesn't document that organizational-unit scope and the remaining distinguished-name components aren't represented in the resulting role value.
## What is wrong
* The role-claim projection isn't injective when separate directory groups have the same CN in different organizational units.
* `LdapAdapter` extracts the first CN from each group distinguished name and later emits that value as a role claim.
* The `EnableLdap` overloads don't document this mapping or state that role-based authorization with duplicate group CNs across organizational units isn't supported.
## Why it matters (defense in depth)
* Directory administrators and application authors may incorrectly assume that organizational-unit boundaries remain part of the role identity.
* Documenting the required group-name uniqueness makes the authorization boundary explicit and helps deployments avoid relying on directory structure that the role claims don't preserve.
## Affected code
* `src/Security/Authentication/Negotiate/src/Internal/LdapAdapter.cs:88-109` - maps direct group distinguished names to CN role claims.
* `src/Security/Authentication/Negotiate/src/Internal/LdapAdapter.cs:126-166` - applies the same CN projection while traversing nested groups.
* `src/Security/Authentication/Negotiate/src/NegotiateOptions.cs:43-63` - public `EnableLdap` entry points don't describe the role-claim mapping limitation.
## Recommended fix
Add `` to both `NegotiateOptions.EnableLdap` overloads stating that LDAP memberships are represented as role claims using the group CN, that organizational-unit and other distinguished-name components aren't included, and that role-based authorization with duplicate group CNs across organizational units isn't supported. Add a concise implementation comment near the `retrievedClaims` collection or CN projection so future maintenance preserves the documented contract.
Keep this change documentation-only. Don't change existing claim values, cache contents, or runtime behavior. Emitting full distinguished names would be a breaking semantic change for existing role policies. Runtime duplicate detection isn't selected because reliable directory-wide uniqueness checks would add query cost, require broader directory permissions, and introduce new failure behavior. A conceptual-documentation-only change was also considered, but API XML documentation is needed so the limitation is visible from IntelliSense and generated API reference pages.
This change has no public API signature impact and requires no migration. Existing applications retain their current CN-based role values.
## Acceptance criteria
* [ ] Both `EnableLdap` overloads document that LDAP group CNs become role claim values.
* [ ] The documentation states that organizational-unit and other distinguished-name components aren't preserved.
* [ ] The documentation states that role authorization with duplicate group CNs across organizational units isn't supported.
* [ ] The implementation includes a concise maintainer comment at the CN-to-role projection point.
* [ ] No runtime behavior, role claim values, cache format, or public API signatures change.
* [ ] The Negotiate project builds with XML documentation generation and existing LDAP adapter tests pass.
Contributor guide
Assessment
This issue has not been assessed yet.