dotnet / dotnet/aspnetcore

Document LDAP group common-name requirements for Negotiate role claims

Open
#69,023 1 comment 1 reaction 2 assignees Claimed by @rokonec View on GitHub
area-auth Docs
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

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.