PSMDB-1573 Update documentation to add guidance on LDAP parameters en… #969

radoslawszulgo · 2025-01-22T21:43:25Z

Add documentation based on @igorsol guidance below:

LDAP documentation refinements

for Set up LDAP authentication and authorization using NativeLDAP - Percona Server for MongoDB 8.0

Creating correct LDAP query may require escaping of special characters. Different parts of such query may have different escaping requirements. There are several RFC documents describing escaping for LDAP:

RFC 4514 | LDAP: Distinguished Names - escaping in Distinguished Names
RFC 4515 | LDAP: String Representation of Search Filters - LDAP search filters utilize its own escaping mechanism
RFC 4516 | LDAP: Uniform Resource Locator - based on general URL escaping. Most obvious example is the need to escape question mark character if it used for something which is not a separator for various parts of LDAP query

There are several parameters in LDAP configuration which require escaping of special characters:

security.ldap.authz.queryTemplate and ldapQuery parameter inside security.ldap.userToDNMapping
both these parameters are LDAP queries which can contain LDAP search filter and distinguished names. So the correct way to escape special characters is to do it step by step:

escape special characters if there are full or partial distinguished names in the query according to RFC 4514
after that escape special characters inside LDAP search filter part of the query according to RFC 4515
after that escape special characters in the whole query according to RFC 4516. Do not escape question marks if that character is used to separate parts of the query
after that if you are going to use result in the YAML config file it might be necessary to do escaping according to YAML specification

substitution parameter inside security.ldap.userToDNMapping
The result of this substitution becomes the value of the {USER} placeholder which is user in the security.ldap.authz.queryTemplate parameter. Generally speaking escaping requirements depends on in which part of the query template it will be substituted. For example the most frequent case result of substitution will be full or part of distinguished name. In that case you will need to escape special characters in the substitution parameters according to RFC 4514.
It is not necessary to use other escaping mechanisms in this parameter because Percona Server for MongoDB will apply RFC 4515 and RFC 4516 escaping as necessary while making substitutions in the security.ldap.authz.queryTemplate parameter.

One more place where you will need to care about special characters is the user name used while connecting using LDAP authorization. In some cases such user name might be full distinguished name and can be substituted directly into the security.ldap.authz.queryTemplate parameter without using any transformation via security.ldap.userToDNMapping. In other case such user name might represent some user ID such as email or user's real name but after transformation via security.ldap.userToDNMapping some parts of it may become part of distinguished name substituted into the security.ldap.authz.queryTemplate parameter. In any case general rule is: if user name or any part of it will end up substituted as distinguished name it must be escaped according to RFC 4514.

MongoDB documentation has following note in several places:

An explanation of RFC4514, RFC4515, RFC4516, or LDAP queries is out of scope for the MongoDB Documentation. Please review the RFC directly or use your preferred LDAP resource.

Reference:
Self-Managed Configuration File Options - security.ldap.userToDNMapping

…cryption

radoslawszulgo · 2025-01-22T21:44:56Z

See screenshots from the preview:

docs/ldap-setup.md

igorsol · 2025-01-23T10:21:21Z

docs/ldap-setup.md

-If you don’t know what the substitution or LDAP query string should be, please consult with the LDAP administrators to figure this out.
+If you don’t know what the Substitution or LDAP query string should be, please consult with the LDAP administrators to figure this out.
+
+Not, you can use only the `LDAP query` or the `Substitution` stage, the combination of two is not allowed.


typo: Not -> Note

docs/ldap-setup.md

Co-authored-by: Anastasia Alexandrova <anastasia.alexandrova@percona.com> Co-authored-by: Igor Solodovnikov <igor.solodovnikov@percona.com>

nastena1606 · 2025-01-23T14:18:36Z

docs/ldap-setup.md

-
-* In this setup, we use the following OpenLDAP groups:
+* The setup of an LDAP server is out of scope of this document. We assume that you are familiar with the LDAP server schema.
+* An explanation of [RFC4514](https://www.ietf.org/rfc/rfc4514.txt), [RFC4515](https://tools.ietf.org/html/rfc4515), [RFC4516](https://tools.ietf.org/html/rfc4516), or LDAP queries is out of scope of this setup. Please review the RFC directly or use your preferred LDAP resource.


I would trade places by mentioning LDAP queries first and then RCFs that describe special character escaping in those queries

nastena1606 · 2025-01-23T14:21:45Z

docs/ldap-setup.md

@@ -31,6 +22,12 @@ cn: otherusers
 member: cn=bob,dc=percona,dc=com
 ```

+## Prerequisites 
+- To configure LDAP, you must have the `sudo` privilege to the server with the {{ product.psmdb_full_name }} installed.
+- If your LDAP server disallows anonymous binds, create the user that Percona Server for MongoDB will use to connect to and query the LDAP server. Afterwards, set that username and password using`security.ldap.bind.queryUser` and `security.ldap.bind.queryPassword` parameters in the `mongod.conf` configuration file. If username or any part of it will end up substituted as distinguished name it must be escaped according to [RFC 4514](https://tools.ietf.org/html/rfc4514). It may happen when: 


As I understand the requirement to escape special characters applies to all usernames, not just for the one PSMDB uses to connect to LDAP. Maybe it's worth mentioning this?

nastena1606 · 2025-01-23T14:22:54Z

docs/ldap-setup.md

+- To configure LDAP, you must have the `sudo` privilege to the server with the {{ product.psmdb_full_name }} installed.
+- If your LDAP server disallows anonymous binds, create the user that Percona Server for MongoDB will use to connect to and query the LDAP server. Afterwards, set that username and password using`security.ldap.bind.queryUser` and `security.ldap.bind.queryPassword` parameters in the `mongod.conf` configuration file. If username or any part of it will end up substituted as distinguished name it must be escaped according to [RFC 4514](https://tools.ietf.org/html/rfc4514). It may happen when: 
+    - A username is a fully distinguished name and can be substituted directly into the `security.ldap.authz.queryTemplate` parameter without using any transformation via `security.ldap.userToDNMapping`.
+    - A username represents an email address or fullname and after transformation via `security.ldap.userToDNMapping` some parts of it may become part of distinguished name substituted into the  `security.ldap.authz.queryTemplate` parameter.


Suggested change

- A username represents an email address or fullname and after transformation via `security.ldap.userToDNMapping` some parts of it may become part of distinguished name substituted into the `security.ldap.authz.queryTemplate` parameter.

- A username represents an email address or full name and after transformation via `security.ldap.userToDNMapping`, some parts of it may become part of a distinguished name substituted into the `security.ldap.authz.queryTemplate` parameter.

Moved the tip to a separate subsection since it also applies to AD setup

docs/authorization.md

igorsol · 2025-01-27T16:11:49Z

docs/authorization.md

@@ -59,6 +59,34 @@ Both `substitution` and `ldapQuery` should contain placeholders to insert parts

 So having an array of documents, Percona Server for MongoDB tries to match each document against the provided name and if it matches, the name is replaced either with the substitution string or with the result of the LDAP query.

+### Escaping special characters in usernames
+
+A username can contain special characters in any of its parts. An example of a special character is the `@` sign in an email. 


The @ character in the mail is probably not the best example because not always it should be escaped. For example on userToDNMapping stage regular expression might match everything before the @ character - in this case there is no reason to esscape it.

Probably it would be better to say that any character which is not alphanumeric or is not an ASCII character may require escaping but which exact characters require escaping depends on all parts of configuration and especially on our LDAP query templates and on our regular expressions inside userToDNMapping.

docs/authorization.md

igorsol · 2025-01-27T16:17:50Z

docs/ldap-setup.md

@@ -4,32 +4,32 @@ This document describes an example configuration of LDAP authentication and auth

 ## Assumptions

-1. The setup of an LDAP server is out of scope of this document. We assume that you are familiar with the LDAP server schema.
+* The setup of an LDAP server is out of scope of this document. We assume that you are familiar with the LDAP server schema.
+* If usernames contain special characters, they must be escaped as described in [RFC4514](https://www.ietf.org/rfc/rfc4514.txt), [RFC4515](https://tools.ietf.org/html/rfc4515), [RFC4516](https://tools.ietf.org/html/rfc4516). An explanation of escaping rules or LDAP queries is out of scope of this setup. Please review the RFC directly or use your preferred LDAP resource.


Suggested change

* If usernames contain special characters, they must be escaped as described in [RFC4514](https://www.ietf.org/rfc/rfc4514.txt), [RFC4515](https://tools.ietf.org/html/rfc4515), [RFC4516](https://tools.ietf.org/html/rfc4516). An explanation of escaping rules or LDAP queries is out of scope of this setup. Please review the RFC directly or use your preferred LDAP resource.

* If usernames contain special characters, they must be escaped as described in [RFC4514](https://www.ietf.org/rfc/rfc4514.txt), [RFC4515](https://tools.ietf.org/html/rfc4515), [RFC4516](https://tools.ietf.org/html/rfc4516). Usage of particular escaping methods depends on the part of the LDAP query which will contain substituted value. An explanation of escaping rules or LDAP queries is out of scope of this setup. Please review the RFC directly or use your preferred LDAP resource.

igorsol · 2025-01-27T16:23:08Z

docs/release_notes/8.0.4-1.md

+version: 8.0.4-1
+---
+
+# {{ product.psmdb_full_name }} {{ page.meta.version }} ({{date.8_0_4}}) 


Not sure if this change is part of this PR or the "8.0.4 release notes" PR.

that's a fix "by chance" :)

radoslawszulgo · 2025-01-28T09:10:54Z

Thanks for changes Nastya. That also works for me.

nastena1606 · 2025-01-28T15:35:44Z

Thanks for changes Nastya. That also works for me.

Can I consider this answer as approval?:)

radoslawszulgo · 2025-01-28T15:52:52Z

Yes!

…

On Tue, 28 Jan 2025 at 16:36, Anastasia Alexandrova < ***@***.***> wrote: Thanks for changes Nastya. That also works for me. Can I consider this answer as approval?:) — Reply to this email directly, view it on GitHub <#969 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/BJXQMX5S2F5N5SNTQDIYCJL2M6PWNAVCNFSM6AAAAABVV5K73KVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDMMJZGM2DQMJZGU> . You are receiving this because you authored the thread.Message ID: ***@***.***>

docs/ldap-setup.md

docs/authorization.md

Co-authored-by: Igor Solodovnikov <igor.solodovnikov@percona.com>

igorsol

Thanks!

PSMDB-1573 Update documentation to add guidance on LDAP parameters en…

9013036

…cryption

nastena1606 deployed to PSMDB-1573-escaping-ldap-parameters - psmdb-docs-8.0 PR #969 January 22, 2025 21:43 — with Render View deployment

radoslawszulgo requested review from nastena1606 and igorsol January 22, 2025 21:45

nastena1606 reviewed Jan 23, 2025

View reviewed changes

docs/ldap-setup.md Outdated Show resolved Hide resolved

igorsol requested changes Jan 23, 2025

View reviewed changes

radoslawszulgo commented Jan 23, 2025

View reviewed changes

docs/ldap-setup.md Outdated Show resolved Hide resolved

Apply suggestions from code review

4ca76c9

Co-authored-by: Anastasia Alexandrova <anastasia.alexandrova@percona.com> Co-authored-by: Igor Solodovnikov <igor.solodovnikov@percona.com>

nastena1606 deployed to PSMDB-1573-escaping-ldap-parameters - psmdb-docs-8.0 PR #969 January 23, 2025 10:42 — with Render View deployment

nastena1606 reviewed Jan 23, 2025

View reviewed changes

Added a high-level explanation for escaping rules

4adb5d6

Moved the tip to a separate subsection since it also applies to AD setup

nastena1606 deployed to PSMDB-1573-escaping-ldap-parameters - psmdb-docs-8.0 PR #969 January 27, 2025 10:56 — with Render View deployment

nastena1606 requested a review from igorsol January 27, 2025 10:56

igorsol requested changes Jan 27, 2025

View reviewed changes

Updated after the review

531452c

nastena1606 deployed to PSMDB-1573-escaping-ldap-parameters - psmdb-docs-8.0 PR #969 January 28, 2025 07:32 — with Render View deployment

nastena1606 requested a review from igorsol January 28, 2025 16:44

nastena1606 reviewed Jan 28, 2025

View reviewed changes

docs/ldap-setup.md Outdated Show resolved Hide resolved

Update docs/ldap-setup.md

727e6c3

nastena1606 deployed to PSMDB-1573-escaping-ldap-parameters - psmdb-docs-8.0 PR #969 January 28, 2025 17:13 — with Render View deployment

igorsol requested changes Jan 28, 2025

View reviewed changes

docs/authorization.md Outdated Show resolved Hide resolved

Apply suggestions from code review

eb1f64f

Co-authored-by: Igor Solodovnikov <igor.solodovnikov@percona.com>

nastena1606 deployed to PSMDB-1573-escaping-ldap-parameters - psmdb-docs-8.0 PR #969 January 29, 2025 11:57 — with Render View deployment

igorsol approved these changes Jan 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PSMDB-1573 Update documentation to add guidance on LDAP parameters en… #969

PSMDB-1573 Update documentation to add guidance on LDAP parameters en… #969

radoslawszulgo commented Jan 22, 2025

radoslawszulgo commented Jan 22, 2025

igorsol Jan 23, 2025

nastena1606 Jan 23, 2025

nastena1606 Jan 23, 2025

nastena1606 Jan 23, 2025 •

edited

Loading

igorsol Jan 27, 2025

nastena1606 Jan 28, 2025

igorsol Jan 27, 2025

igorsol Jan 27, 2025

radoslawszulgo Jan 29, 2025

radoslawszulgo commented Jan 28, 2025

nastena1606 commented Jan 28, 2025

radoslawszulgo commented Jan 28, 2025 via email

igorsol left a comment

	- A username represents an email address or fullname and after transformation via `security.ldap.userToDNMapping` some parts of it may become part of distinguished name substituted into the `security.ldap.authz.queryTemplate` parameter.
	- A username represents an email address or full name and after transformation via `security.ldap.userToDNMapping`, some parts of it may become part of a distinguished name substituted into the `security.ldap.authz.queryTemplate` parameter.

PSMDB-1573 Update documentation to add guidance on LDAP parameters en… #969

Are you sure you want to change the base?

PSMDB-1573 Update documentation to add guidance on LDAP parameters en… #969

Conversation

radoslawszulgo commented Jan 22, 2025

LDAP documentation refinements

radoslawszulgo commented Jan 22, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nastena1606 Jan 23, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

radoslawszulgo commented Jan 28, 2025

nastena1606 commented Jan 28, 2025

radoslawszulgo commented Jan 28, 2025 via email

igorsol left a comment

Choose a reason for hiding this comment

nastena1606 Jan 23, 2025 •

edited

Loading