Skip to content

Commit

Permalink
PSMDB-1573 Update documentation to add guidance on LDAP parameters en…
Browse files Browse the repository at this point in the history 
…cryption (#974)

modified:   docs/authorization.md
	modified:   docs/ldap-setup.md
  • Loading branch information
@nastena1606
nastena1606 authored Feb 19, 2025
1 parent e2279ec commit dba3b5d
Show file tree
Hide file tree
Showing 2 changed files with 69 additions and 27 deletions.
27 changes: 27 additions & 0 deletions docs/authorization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,33 @@ 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. A special character is any character which is not alphanumeric and not an ASCII character.

These characters must be escaped to formulate the correct LDAP query on the following stages:

* To transform a username to the LDAP DN, and the matched pattern of a username must be first queried in the LDAP server to become the DN.
* To retrieve the groups a user is the member of.

Additionally, the username pattern to match for the transformation can have special characters that must be escaped too.

What exactly characters require escaping depends on the Percona Server for MongoDB configuration. Namely, on the configuration of the LDAP query template and the regular expressions inside the `--ldapUserToDNMapping` parameter.

The escaping rules are described in the following documents:

* [RFC 4514 | LDAP: Distinguished Names](https://datatracker.ietf.org/doc/html/rfc4514) - Escaping in Distinguished Names
* [RFC 4515 | LDAP: String Representation of Search Filters](https://datatracker.ietf.org/doc/html/rfc4515) - LDAP search filters utilize its own escaping mechanism
* [RFC 4516 | LDAP: Uniform Resource Locator](https://datatracker.ietf.org/doc/html/rfc4516) - General URL escaping rules.

Their explanation is out of the scope of the Percona Server For MongoDB documentation. Please review the RFC directly or use your preferred LDAP resource.

To summarize, username escaping happens in the following cases:

* When a username is defined as the LDAP DN and has special characters in any of its parts.
* When a username must be transformed to the LDAP DN and the username pattern for the transformation has special characters
* When the transformed LDAP DN value contains special characters in any of its parts.

### LDAP referrals

As of version 6.0.2-1, Percona Server for MongoDB supports LDAP referrals as defined in [RFC 4511 4.1.10](https://www.rfc-editor.org/rfc/rfc4511.txt). For security reasons, referrals are disabled by default. Double-check that using referrals is safe before enabling them.
Expand Down
69 changes: 42 additions & 27 deletions docs/ldap-setup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,32 +4,33 @@ 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). The usage of particular escaping rules depends on the part of the LDAP query which will contain the 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.
* You have the LDAP server up and running and it's accessible to the servers with Percona Server for MongoDB installed.
* This document primarily focuses on OpenLDAP used as the LDAP server and the examples are given based on the OpenLDAP format. If you are using Active Directory, refer to the [Active Directory configuration](#active-directory-configuration) section.
* In examples below, we use anonymous binds to the LDAP server and the following OpenLDAP groups:

2. You have the LDAP server up and running and it is accessible to the servers with Percona Server for MongoDB installed.
```text
dn: cn=testusers,dc=percona,dc=com
objectClass: groupOfNames
cn: testusers
member: cn=alice,dc=percona,dc=com
3. This document primarily focuses on OpenLDAP used as the LDAP server and the examples are given based on the OpenLDAP format. If you are using Active Directory, refer to the [Active Directory configuration](#active-directory-configuration) section.
dn: cn=otherusers,dc=percona,dc=com
objectClass: groupOfNames
cn: otherusers
member: cn=bob,dc=percona,dc=com
```

4. You have the `sudo` privilege to the server with the Percona Server for MongoDB installed.
## Prerequisites

## Prerequisites
- To configure LDAP, you must have the `sudo` privilege to the server with the Percona Server for MongoDB installed.

* In this setup we use anonymous binds to the LDAP server. 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. Define this user’s credentials for the `security.ldap.bind.queryUser` and `security.ldap.bind.queryPassword` parameters in the `mongod.conf` configuration file.
- 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 the `security.ldap.bind.queryUser` and `security.ldap.bind.queryPassword` parameters in the `mongod.conf` configuration file. If the username or any part of it ends 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 LDAP query without using any transformation. The LDAP query is defined within the `security.ldap.authz.queryTemplate` configuration parameter.
- A username represents an email address or a full name and requires transformation to LDAP DN. The transformation rules are defined via the `security.ldap.userToDNMapping` configuration parameter. After the transformation, some parts of the username may become part of distinguished name substituted into the `security.ldap.authz.queryTemplate` parameter.

* In this setup, we use the following OpenLDAP groups:

```text
dn: cn=testusers,dc=percona,dc=com
objectClass: groupOfNames
cn: testusers
member: cn=alice,dc=percona,dc=com
dn: cn=otherusers,dc=percona,dc=com
objectClass: groupOfNames
cn: otherusers
member: cn=bob,dc=percona,dc=com
```

## Setup procedure

Expand All @@ -39,9 +40,9 @@ By default, Percona Server for MongoDB establishes the TLS connection when bindi

1. Place the certificate in the `certs` directory. The path to the `certs` directory is:

* On Debian / Ubuntu: `/etc/ssl/certs/`
* On RHEL / derivatives: `/etc/openldap/certs/`

* On RHEL / CentOS: `/etc/openldap/certs/`
* On Debian / Ubuntu: `/etc/ssl/certs/`

2. Specify the path to the certificates in the `ldap.conf` file:

Expand Down Expand Up @@ -92,8 +93,7 @@ db.createRole(

#### Access without username transformation

This section assumes that users connect to Percona Server for MongoDB by providing their LDAP DN as the username.

This section assumes that users connect to Percona Server for MongoDB by providing their LDAP DN as the username and the LDAP DNs don't contain special characters. Otherwise, you must escape them according to [RFC 4514 | LDAP: Distinguished Names](https://datatracker.ietf.org/doc/html/rfc4514).

1. Edit the Percona Server for MongoDB configuration file (by default, `/etc/mongod.conf`) and specify the following configuration:

Expand Down Expand Up @@ -130,13 +130,13 @@ This section assumes that users connect to Percona Server for MongoDB by providi

#### Access with username transformation

If users connect to Percona Server for MongoDB with usernames that are not LDAP , you need to transform these usernames to be accepted by the LDAP server.
If users connect to Percona Server for MongoDB with usernames that are not LDAP, you need to transform these usernames to be accepted by the LDAP server. If usernames contain special characters, these [characters must be escaped](#escaping-special-characters).

Using the `--ldapUserToDNMapping` configuration parameter allows you to do this. You specify the match pattern as a regexp to capture a username. Next, specify how to transform it - either to use a substitution value or to query the LDAP server for a username.

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.

Note that you can use only the `query` or the `substitution` stage, the combination of two is not allowed.
Note that you can use only the `LDAPquery` or the `Substitution` stage, and you cannot combine the two.

=== "Substitution"

Expand Down Expand Up @@ -217,6 +217,21 @@ Note that you can use only the `query` or the `substitution` stage, the combinat
mongosh -u "alice" -p "secretpwd" --authenticationDatabase '$external' --authenticationMechanism 'PLAIN'
```

#### Escaping special characters

The **`substitution` parameter**

The result of the substitution becomes the value of the `{USER}` placeholder, which is a `{USER}` value in the `security.ldap.authz.queryTemplate` parameter. Escaping requirements depend on the part of the query template that will be substituted. For example, the result of the substitution can be a full distinguished name or a part of it. In this case, according to [RFC4514](https://www.ietf.org/rfc/rfc4514.txt), you must escape special characters in the `substitution` parameter. Using other escaping mechanisms in this parameter is unnecessary because {{ product.psmdb_full_name }} applies the necessary escaping as outlined in [RFC4515](https://tools.ietf.org/html/rfc4515) and [RFC4516](https://tools.ietf.org/html/rfc4516) while substituting the `security.ldap.authz.queryTemplate` parameter.

The **`ldapQuery` and `queryTemplate` parameters**

To properly escape special characters, follow these steps:

1. Escape special characters in full or partially distinguished names in the query according to [RFC 4514](https://www.ietf.org/rfc/rfc4514.txt).
2. Next, escape special characters within the LDAP search filter portion of the query, as outlined in [RFC 4515](https://www.ietf.org/rfc/rfc4515.txt).
3. Then, escape special characters in the query according to [RFC 4516](https://www.ietf.org/rfc/rfc4516.txt). Note that you do not need to escape question marks if they are being used to separate parts of the query.<br />
4. Finally, if you plan to use the result in a YAML configuration file, you may need to escape characters according to the [YAML specification](https://yaml.org/spec/)

### Active Directory configuration

Microsoft Active Directory uses a different schema for user and group definition. To illustrate Percona Server for MongoDB configuration, we will use the following AD users:
Expand All @@ -241,7 +256,7 @@ dn:CN=otherusers,CN=Users,DC=percona,DC=com
member:CN=bob,CN=Users,DC=otherusers,DC=example,DC=com
```

Use one of the given Percona Server for MongoDB configurations for user authentication and authorization in Active Directory:
Use one of the given Percona Server for MongoDB configurations for user authentication and authorization in Active Directory. Read about [escaping special characters in usernames](#escaping-special-characters) to modify the configuration accordingly.

=== "No username transformation"

Expand Down

0 comments on commit dba3b5d

Please sign in to comment.