+++ /dev/null
-= Mapping and testing with ldapsearch
-
-Prior to configuring the `ldap` module, the connectivity and connection
-parameters should be verified using the `ldapsearch` utility.
-
-`ldapsearch` is provided as part of the OpenLDAP suite of tools. These tools
-should be installed on the machine used for testing the LDAP server.
-
-We _strongly_ recommend running these checks on the same machine that will be
-used to host the RADIUS server. A common cause of connectivity issues is that a
-firewall is preventing network access from the RADIUS server to the LDAP server.
-Running `ldapsearch` on a third machine may not reveal these firewall issues.
-
-== Before starting
-
-Try to determine answers to the following questions:
-
-* What's the IP address of the LDAP server being tested?
-** If using an FQDN does the FQDN resolve to this IP address?
-* Does the LDAP server requires encrypted connections?
-** If yes:
-*** Does the LDAP server use the StartTLS extension to transition to
-encrypted communication, or is communication encrypted from the start (LDAPS)?
-*** What are the necessary root certificates and intermediary certificates
-needed to validate the identity of the LDAP server?
-* What port is used to connect to the LDAP server? Usually this will be `389`
-(unencrypted or StartTLS) or `636` (LDAPS).
-* Do connections need to be bound to perform searches on the LDAP directory?
-** If yes:
-*** Determine what credentials are needed for binding, and whether a client
-certificate is required.
-* Determine the Base DN, the object deepest in the tree that contains the object
-representing users, groups, clients etc...
-
-== Determining the correct ldap search arguments
-
-`ldapsearch` accepts a large number of different arguments, and allow relatively
-complex commands to be sent to the LDAP server.
-
-It will likely take a number of attempts to find the correct `ldapsearch` invocation.
-If you have no prior information about the LDAP server follow the examples below,
-adding progressively more connection parameters until `ldapsearch` returns a positive
-result (`$? == 0` and one or more entries written to stdout).
-
-[source,ldif]
-----
-dn: uid=john,ou=people,dc=example,dc=com
-objectClass: inetOrgPerson
-uid: john
-userPassword: password
-----
-
-If the `ldapsearch` program fails to return anything useful, then additional
-arguments should be added until the search succeeds. Unfortunately, every piece
-of advice in this section is site-specific, and is independent of RADIUS.
-
----
-
-=== Search without bind (anonymous)
-At a minimum, unless you have defaults set in your local `ldap.conf` file,
-you will need to provide the following arguments:
-
-- `-z 1` - Limit the number of results to 1.
-- `-x` - Use simple authentication instead of SASL (correct for the majority of servers).
-- `-H <ldap uri>` - The LDAP server to connect to.
-- `-b <dn>` - A point in the LDAP tree to start the search from.
-
-.Performing an anonymous search
-====
-```
-ldapsearch -z 1 -x -H ldap://ldap.example.com:389 -b "cn=freeradius,dc=example,dc=com"
-```
-====
----
-.Bad FQDN/IP or attempt blocked by firewall
-```
-ldap_sasl_bind(SIMPLE): Can't contact LDAP server (-1)
-```
-
-* Verify (using `dig` or similar) that the FQDN of the LDAP
-server can be resolved.
-* Verify that there is no firewall blocking access. Some techniques to check this
-which _may_ work.
-** `sudo traceroute -Tn -p 636 ldap.example.com` will be successful (and not
-continue indefinitely) when there is _no_ firewall blocking.
-** `netcat -vz -w3 ldap.example.com 636` will return `succeeded` when there is no
-firewall blocking access.
-
----
-.Bind required
-```
-ldap_bind: Server is unwilling to perform (53)
- additional info: unauthenticated bind (DN with no password) disallowed
-```
-
-The majority of LDAP servers will also require the LDAP client to identify itself,
-this is done with a bind operation.
-
-If a message similar to the one above is returned, it means a bind operation
-must be performed before attempting any operations on the LDAP server.
-
-The following arguments should be added to identify the LDAP client to the LDAP
-server:
-
-- `-D <dn>` - The bind DN. A unique identifier for the user being bound.
-- `-w <password>` - The bind password.
-
-.Performing a search with a bound user
-====
-```
-ldapsearch -z 1 -x -H ldap://ldap.example.com:389 -D "cn=freeradius,dc=example,dc=com" -w mypassword -b "dc=example,dc=com"
-```
-====
----
-
-=== Encrypting connections with TLS
-
-If a message similar to the one below is returned by `ldapsearch`. TLS must
-be enabled on the connection.
-
-```
-ldap_bind: Confidentiality required (13)
- additional info: TLS confidentiality required
-```
-
-==== Common arguments
-
-- `LDAPTLS_CACERT=<ca_cert_and_intermediaries.pem>` - An environmental variable
-specifying a PEM file containing CA and chain of trusted certificates, that
-joins with the chain presented by the LDAP server. These certificates must be
-provided in order to validate the LDAP server's certificate.
-
-- `LDAPTLS_REQCERT=hard` - An environmental variable requiring the LDAP server
-provide a certificate.
-
-
-.Retrieving certificate chains from the server
-****
-If using LDAP over TLS `openssl s_client` can display information about the
-certificates presented by the LDAP server. The information returned
-(particularly the certificate issuer(s)) in useful to determine what
-certificates need to be available to the LDAP client.
-
-The `openssl` invocation is different depending on whether StartTLS or LDAPS
-is used.
-
-.LDAPS - Retrieving the certificate chain of the fictitious ldap.example.com server
-====
-```
-echo -n | openssl s_client -host ldap.example.com -port 636 -prexit -showcerts
-CONNECTED(00000003)
-depth=1 C = OT, ST = Tentacle Cove, O = FreeRADIUS, OU = Services, CN = example.com, emailAddress = support@example.com
-verify return:0
----
-Certificate chain
- 0 s:/C=OT/ST=Tentacle Cove/L=Grenoble/O=FreeRADIUS/OU=Services/CN=ldap.example.com/emailAddress=support@example.com
- i:/C=OT/ST=Tentacle Cove/O=FreeRADIUS/OU=Services/CN=example.com/emailAddress=support@example.com
------BEGIN CERTIFICATE-----
-MIIHDjCCBPagAwIBAgIJANAO5znieeLNMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYD
-...
-```
-====
-
-.StartTLS - Retrieving the certificate chain of the fictitious ldap.example.com server
-====
-```
-echo -n | openssl s_client -host ldap.example.com -port 389 -prexit -showcerts -starttls ldap
-CONNECTED(00000003)
-depth=1 C = OT, ST = Tentacle Cove, O = FreeRADIUS, OU = Services, CN = example.com, emailAddress = support@example.com
-verify return:0
----
-Certificate chain
- 0 s:/C=OT/ST=Tentacle Cove/L=Grenoble/O=FreeRADIUS/OU=Services/CN=ldap.example.com/emailAddress=support@example.com
- i:/C=OT/ST=Tentacle Cove/O=FreeRADIUS/OU=Services/CN=example.com/emailAddress=support@example.com
------BEGIN CERTIFICATE-----
-MIIHDjCCBPagAwIBAgIJANAO5znieeLNMA0GCSqGSIb3DQEBCwUAMIGSMQswCQYD
-...
-```
-[NOTE]
-.Availability of `-starttls ldap`
-Not all builds of `openssl s_client` support `-starttls ldap`. As of OpenSSL
-1.1.1 this feature is still only available in the OpenSSL master branch. See
-this GitHub Pull Request for details:
-https://github.com/openssl/openssl/pull/2293.
-====
-****
-
-==== LDAPS
-
-LDAPS is configured by changing the URI scheme passed as the value to `-H`.
-
-Where an unencrypted or StartTLS connection uses `ldap://`, LDAPS requires
-`ldaps://`.
-
-The port for LDAPS is different than for unencrypted communication. Where an
-unencrypted or StartTLS connection normally uses `TCP/389`, LDAPS normally uses
-`TCP/636`.
-
-For LDAPS an unencrypted or StartTLS URI is changed from:
-```
--H ldap://<fqdn>:389
-```
-
-to
-
-```
--H ldaps://<fqdn>:636
-```
-
-.Performing a search with a bound user with LDAPS
-====
-```
-LDAPTLS_CACERT=cert_bundle.pem LDAPTLS_REQCERT=hard ldapsearch -z 1 -x -H ldaps://ldap.example.com:636 -D "cn=freeradius,dc=example,dc=com" -w mypassword -b "dc=example,dc=com"
-```
-====
-
-==== StartTLS
-
-StartTLS connections runs on the same port as unencrypted LDAP. StartTLS
-is an LDAP
-
-- `-ZZ` - Transition to encrypted communication using the StartTLS extension,
-and fail if we can't.
-
-.Performing a search with a bound user with StartTLS
-====
-```
-LDAPTLS_CACERT=cert_bundle.pem LDAPTLS_REQCERT=hard ldapsearch -z 1 -x -H ldap://ldap.example.com:389 -D "cn=freeradius,dc=example,dc=com" -w mypassword -b "dc=example,dc=com" -ZZ
-```
-====
-
-== Locating Objects within LDAP
-
-In additional to the arguments specifying how to connect to the LDAP server and
-where to search, `ldapsearch` accepts two positional arguments. Both positional
-arguments are optional.
-
-The first argument specifies the filter to apply to the search, the second is a
-comma delimited list of attributes to retrieve.
-
-=== Users
-Users are represented by a fairly limited subset of ObjectClasses. The
-following filters are usually sufficient to identify users in different
-directory types.
-
-- OpenLDAP - `(|(ObjectClass=organizationalPerson)(ObjectClass=posixAccount)(ObjectClass=Person))`
-- ActiveDirectory - `(|(ObjectClass=User)(ObjectClass=posixAccount))`
-- Novell eDir - `(ObjectClass=User)`
-
-.Performing a search with a user object filter
-====
-```
-ldapsearch -z 10 -x -H ldap://ldap.example.com:389 -b "dc=example,dc=com" "(|(ObjectClass=organizationalPerson)(ObjectClass=PosixAccount)(ObjectClass=Person))"
-
-# extended LDIF
-#
-# LDAPv3
-# base <dc=example,dc=com> with scope subtree
-# filter: (|(ObjectClass=organizationalPerson)(ObjectClass=PosixAccount)(ObjectClass=Person))
-# requesting: ALL
-#
-
-...
-
-# doctopus, octopuses, example.com
-dn: uid=doctopus,ou=octopuses,dc=example,dc=com
-objectClass: person
-objectClass: organizationalPerson
-objectClass: inetOrgPerson
-cn: Doctopus McTentacles
-sn: McTentacles
-uid: dpus
-givenName: Doctopus
-userPassword:: MGN0MHB1NTNzUnVsMw==
-
-# search result
-search: 3
-result: 0 Success
-
-# numResponses: 18
-# numEntries: 17
-```
-====
-
-There's a lot of useful information in this result:
-
-- We know where the user objects are likely to be located, as it's fairly
-obvious from the DN (`...,ou=octopuses,dc=example,dc=com`). _Note: In the
-majority of non-FreeRADIUS themed LDAP directories the user object container
-will be `ou=people`_.
-- The result shows a `uid` attribute. This will almost always be the correct
-attribute for identifying a user.
-- The result shows a base64 encoded `userPassword` attribute. This
-means users can be authenticated without rebinding the connection (more
-efficient).
-- There's no `memberOf` attributes. This means user to group mappings
-are likely stored in group objects instead of the user objects themselves.
-
-==== What to record
-
-- `user_object_base_dn` - The DN higher in the tree than relevant users
-objects.
-- `user_object_class_filter` - The filter which matches the objectClass(es) of
-user objects.
-- `uid_attribute` - The attribute used to identify the user
-(usually `uid`, but can vary considerably between instances).
-- `user_password_attribute` - The attribute used to hold password data (if
-present).
-- `account_disabled_attribute` - Any attributes used to indicate whether an
-account is disabled. To determine if this attribute exists, repeat the user
-search (above) with a filter for a user account known to be disabled e.g.
-`(uid=a-disabled-user)`.
-- `account_enabled_attribute` - Any attributes used to indicate whether an
-account is enabled. Should be present in the search results already obtained.
-
-.Finding users in "mature" LDAP directories
-****
-The above result represents an ideal scenario. In reality, LDAP directories
-often accumulate a lot of cruft. Users objects may be located in
-multiple container objects, and at multiple levels within a directory.
-
-If you believe this to be the case with your directory, remove the `-z` argument
-limiting the number of result, and pipe the output of `ldapsearch` through a
-command chain _such as_: `grep dn: | sed -e 's/dn: [^,]*,//' | sort | uniq -c`.
-
-This operation will return a list of objects which _contain_ user objects,
-and how many user objects they contain.
-
-.Determining which objects contain users
-====
-```
-ldapsearch -x -H ldap://ldap.example.com:389 -b "dc=example,dc=com" "(|(ObjectClass=organizationalPerson)(ObjectClass=PosixAccount)(ObjectClass=Person))" | grep dn: | sed -e 's/dn: [^,]*,//' | sort | uniq -c`
-2 ou=octopuses,dc=example,dc=com
-10 ou=people,dc=example,dc=com
-1 ou=people,dc=created-by-someone-who-didnt-know-what-dc-meant,dc=example,dc=com
-2 ou=people,ou=remnant-of-an-ancient-edir-instance,dc=example,dc=com
-2 ou=giraffes,dc=example,dc=com
-```
-====
-
-The user object base DN selected for your rlm_ldap configuration must be higher
-in the object tree than the objects containing users. In the above example the
-user object base DN would be `dc=example,dc=com`.
-
-If an error message is returned similar to `Size limit exceeded (4)`, it means
-that the LDAP server is refusing to provide the complete set of results. If the
-LDAP directory supports result paging, adding a paging request such as `-E
-'pr=100'` may negate the per-search result limit.
-
-For large result sets you should also specify a list of attributes to retrieve
-after the search filter. Limiting the attributes returned reduces load on the
-LDAP server, and generally results in a quicker response.
-
-```
-ldapsearch ... -E 'pr=100' "(|(ObjectClass=...))" "dn" | ...
-```
-****
-
-=== Groups
-
-Groups are represented by a fairly limited subset of ObjectClasses. The
-following filters are usually sufficient to identify groups in different
-directory types.
-
-- OpenLDAP - `(objectClass=groupOfNames)`
-- ActiveDirectory - `(objectClass=group)`
-- Novell eDir - `(objectClass=group)`
-
-.Performing a search with a group object filter
-====
-```
-ldapsearch -z 10 -x -H ldap://ldap.example.com:389 -b "dc=example,dc=com" "(objectClass=posixGroup)"
-
-# extended LDIF
-#
-# LDAPv3
-# base <ou=people,dc=example,dc=com> with scope subtree
-# filter: (ObjectClass=posixGroup)
-# requesting: ALL
-#
-
-...
-
-dn: cn=mariner-alert,ou=groups,dc=example,dc=com
-cn: mariner-alert
-description: Heads up to all delicious denizens of the directory
-member: uid=doctopus,ou=octopuses,dc=example,dc=com
-member: uid=rocktopus,ou=octopuses,dc=example,dc=com
-objectClass: groupOfNames
-objectClass: fdGroupMail
-mail: mariner-alert@example.com
-
-# search result
-search: 3
-result: 0 Success
-
-# numResponses: 10
-# numEntries: 9
-```
-====
-
-.Finding groups in "mature" directories
-****
-As with users, groups may be located in multiple areas of the directory.
-
-.Determining which objects contain groups
-====
-```
-ldapsearch -x -H ldap://ldap.example.com:389 -b "dc=example,dc=com" -E 'pr=100' "(ObjectClass=posixGroup)" dn | grep dn: | sed -e 's/dn: [^,]*,//' | sort | uniq -c`
-3 ou=groups,dc=example,dc=com
-1 ou=groups,o=long-defunct-org-that-was-merged-with-example-com,dc=example,dc=com
-3 ou=groups,ou=interns-summer-project,dc=example,dc=com
-2 ou=groups,ou=backup-restored-in-the-wrong-place,dc=example,dc=com
-```
-====
-****
-
-==== Group membership scheme variants
-Groups memberships can be represented in multiple ways. There are four main
-variants:
-
-1. User objects which reference groups by DN, _usually_ with multiple
-instances of the `memberOf` attribute.
-2. User objects which reference groups by name, again, _usually_
-with multiple instances of the `memberOf` attribute.
-3. Group objects which reference their members by DN, _usually_ with multiple
-instances of the `member` attribute.
-4. Group objects which reference their members by name, _usually_ with
-multiple instances of the `memberUid` attribute.
-
-In order to perform efficient group lookups which group membership scheme the
-LDAP server uses must be determined.
-
-Repeat the search for user objects using a filter that matches a user known
-to be members of one or more groups e.g.
-`(&(objectClass=posixUser)(uid=doctopus))`.
-
-- If the result shows a attribute containing the DN of known group, the LDAP
-server implements _variant 1_.
-
-- If the result shows a attribute containing the name of known group, the LDAP
-server implements _variant 2_.
-
-Repeat the the search for group objects using a filter that matches a group
-the user is known to be a member of e.g. `(&(objectClass=groupOfNames)(cn=mariner-alert))`.
-
-- If the result shows an attribute containing the DN of a user, the ldap server
-implements _variant 3_.
-
-- If the result shows an attribute containing the name of a user, the ldap server
-implements _variant 4_.
-
-==== If the variant can't be determined
-
-- There's a typographical error in the search filter or `ldapsearch` arguments.
-- The bound user doesn't have sufficient permission to view user or group
-objects. Contact your LDAP administrator.
-- The LDAP directory uses a special scheme to represent groups which requires
-querying a special OID, or providing additional search controls (outside of the
-scope of this howto).
-- Group memberships are represented with 'operational' attributes. Repeat the
-user object search with '+' set as the second positional argument.
-
-.Searching for a user object and returning operational attributes
-```
-ldapsearch -z 10 -x -H ldap://ldap.example.com:389 -b "dc=example,dc=com" "(ObjectClass=posixUser)" +
-```
-
-==== What to record
-
-* `group_object_base_dn` - The DN higher in the tree than all
-relevant group objects.
-* `group_name_attribute` - The attribute used to identify the group
-(usually `cn`).
-* _variant 1_
-** `membership_attribute` - User object attribute containing group
-membership information.
-* _variant 2_
-** `membership_attribute` - User object attribute containing group
-membership information.
-* _variant 3_
-** `membership_user_dn_filter` - A filter matching users by DN.
-* _vairant 4_
-** `membership_user_name_filter` - A filter matching users by user name.
-
-== Translating ldapsearch arguments to rlm_ldap configuration items
-
-[width="100%",cols="30%,20%,50%",options="header",]
-|===
-| Purpose | ldapsearch argument | `ldap { ... }` config item
-| Limit number of search results | ```-z``` | Not supported.
-| Use basic authentication | ```-x``` | Set by default.
-| LDAP Host URI | ```-H <uri>``` | ```server = '<uri>'``` +
- ```port = (389\|<custom port>)```
-| Base DN | ```-b <dn>``` | ```base_dn = '<dn>'```
-| Bind DN | ```-D <dn>``` | ```identity = '<dn>'```
-| Bind Password | ```-w <password>``` | ```password = '<password>'```
-| Enable LDAPS | ```-H ldaps://<uri>``` | ```server = 'ldaps://<uri>'``` +
- ```port = (636\|<custom port>)```
-| Enable StartTLS | ```-ZZ``` | ```tls { start_tls = yes }```
-| Specify RootCA and intermediaries | ```LDAPTLS_CACERT=<ca_cert_and_intermediaries.pem>``` | ```tls { ca_file = '<ca_cert_and_intermediaries.pem>' }```
-| Require cert validation to succeed | ```LDAPTLS_REQCERT=hard``` | ```tls { require_cert = 'demand' }```
-|===
-
-== Translating ldapsearch results to rlm_ldap configuration items
-
-=== Users
-[width="100%",cols="30%,70%",options="header",]
-|===
-| Purpose | `ldap { user { ... } }` config item
-| Specify where to search for users | ```base_dn = '<user_object_base_dn>'```
-| Specify how to find a user | ```filter = "(&(<user_object_class_filter>)(<uid_attribute>=%{%{Stripped-User-Name}:-%{User-Name}})"```
-| Retrieve a "known good" password | ```update { &control:Password-With-Header = <user_password_attribute>```
-| Allow accounts to be explicitly disabled | ```access_attribute = '<account_disabled_attribute>'``` +
- ```access_positive = 'no'```
-| Require accounts to be explicitly enabled | ```access_attribute = '<account_enabled_attribute>'``` +
- ```access_positive = 'yes'```
-|===
-
-=== Groups - Common
-
-[width="100%",cols="30%,70%",options="header",]
-|===
-| Purpose | `ldap { group { ... } }` config item
-| Specify where to search for group | ```base_dn = '<group_object_base_dn>'```
-| Specify which objects are groups | ```filter = '<group_object_class_filter>'```
-| Specify which attribute in a group object
- identifies the group | ```name_attribute = '<group_name_attribute>'```
-|===
-
-=== Groups - variant 1
-
-User objects reference groups using DNs.
-
-[width="100%",cols="30%,70%",options="header",]
-|===
-| Purpose | `ldap { group { ... } }` config item
-| Specify how to find group objects by DN, when referenced by a user object. | ```membership_attribute = '<group_object_base_dn>'```
-|===
-
-=== Groups - variant 2
-
-User objects reference groups using group names.
-
-[width="100%",cols="30%,70%",options="header",]
-|===
-| Purpose | `ldap { group { ... } }` config item
-| Specify how to find group objects by name, when referenced by a user object. | ```membership_attribute = '<group_object_base_dn>'```
-|===
-
-=== Groups - variant 3
-
-Group objects reference users using DNs.
-
-[width="100%",cols="30%,70%",options="header",]
-|===
-| Purpose | `ldap { group { ... } }` config item
-| Specify how to find group objects referencing a user by DN. | ```membership_filter = "(<membership_user_dn_filter>=%{control:Ldap-UserDn})"```
-|===
-
-=== Groups - variant 4
-
-Group objects reference users using user names.
-
-[width="100%",cols="30%,70%",options="header",]
-|===
-| Purpose | `ldap { group { ... } }` config item
-| Specify how to find group objects referencing a user by name. | ```membership_filter = "(<membership_user_name_filter>=%{%{Stripped-User-Name}:-%{User-Name}})"```
-|===
-
-.Mixing and matching group membership schemes
-****
-Although rare, it is possible to have all four group membership scheme variants
-in a single directory. FreeRADIUS supports this configuration.
-
-For _variant 1_ and _variant 2_ FreeRADIUS will automatically determine if the
-user object attribute contained a DN or group name.
-
-For _variant 3_ and _variant 4_ it's possible to construct a filter which matches
-both on user DN and user name e.g.
-
-[source,config]
-----
-membership_filter = "(|(<membership_user_dn_filter>=%{control:Ldap-UserDn})(<membership_user_name_filter>=%{%{Stripped-User-Name}:-%{User-Name}}))"
-----
-****
-
-== Closing comments
-
-It is always simpler to debug LDAP issues using an LDAP-specific tool such as
-`ldapsearch`. Adding a RADIUS server to the mix will just make it more
-difficult to debug LDAP issues. Therefore you should not configure FreeRADIUS to
-use LDAP until such time as `ldapsearch` returns a positive result.
-
-Similarly, it is not productive to ask questions about `ldapsearch` and LDAP on
-the FreeRADIUS mailing list. The list members can help with configuring
-FreeRADIUS to talk to LDAP, but they are unable to help with debugging
-`ldapsearch`. Where possible, the local LDAP administrator should be contacted
-for assistance.
-
-We have not yet discovered an LDAP implementation that is truly incompatible
-with FreeRADIUS. With sufficient diligence and perseverance you will be able to
-successfully integrate FreeRADIUS and an LDAP server. You may find it
-heartening to know that the maintainers of FreeRADIUS also consider `rlm_ldap`
-one of the more complex modules bundled with FreeRADIUS.
projects / thirdparty / freeradius-server.git / commitdiff
