nav:
- modules/ROOT/nav.adoc
- modules/installation/nav.adoc
+- modules/concepts/nav.adoc
- modules/howto/nav.adoc
- modules/tutorials/nav.adoc
- modules/unlang/nav.adoc
* xref:index.adoc[Introduction]
-** xref:aaa.adoc[AAA]
+++ /dev/null
-= Concepts
-
-List with some articles related to RADIUS.
-
-## Topics
-
-* xref:aaa.adoc[AAA]
The documentation is split into sections by subject area, oganized by
desired outcome. At a high level, the subject areas describe:
-* xref:concepts.adoc[Concepts] and introduction for newcomers.
+* xref:concepts:index.adoc[Concepts] and introduction for newcomers.
* xref:installation:index.adoc[Installing] and xref:installation:upgrade.adoc[upgrading] FreeRADIUS.
* The syntax of the xref:unlang:index.adoc[unlang] processing language.
* The xref:raddb:index.adoc[configuration files] located in `/etc/raddb/`, or `/etc/freeradius/`
possible.
Administrators who are new to FreeRADIUS should read the
-xref:concepts.adoc[concepts section] as it describes the concepts behind
+xref:concepts:index.adoc[concepts section] as it describes the concepts behind
FreeRADIUS. It is vital for newcomers to understand these concepts, as the rest
of the documentation assumes familiarity with them.
--- /dev/null
+* xref:index.adoc[Concepts]
+** General
+*** xref:aaa.adoc[AAA]
+** Modules
+*** LDAP
+**** xref:modules/ldap/authentication.adoc[Authentication]
--- /dev/null
+= Concepts
+
+This section documents concerning the protocols and modules used by the
+FreeRADIUS server.
+
+It intended to provide more theoretical information about particular subjects
+than would be appropriate to include inline in module configurations or as
+sidebars in howto guides.
--- /dev/null
+== Authenticating Users with LDAP
+
+Please be aware the FreeRADIUS is an AAA server, and LDAP
+is a _database_. This separation of roles means that FreeRADIUS
+supports multiple kinds of authentication protocols such as `PAP`,
+`CHAP`, `MS-CHAP`, etc. An LDAP database supports only one
+authentication method: "bind as user". This authentication method is
+compatible only with PAP.
+
+Our recommendation is to use LDAP as a database. FreeRADIUS should
+read the "known good" password from LDAP, and then use that
+information to authenticate the user. It is almost always wrong to
+use the LDAP "bind as user" method for authenticating users.
+
+The only caveat to the above recommendation is Active Directory. For
+"security" reasons, Active Directory will not return the "known good"
+password to FreeRADIUS over a standard LDAP query. Therefore when
+Active Directory is used, the choices are:
+
+PAP::
+Use "bind as user"
+
+MS-CHAP::
+Use xref:raddb:mods-available/ntlm_auth.adoc[`ntlm`] or xref:raddb:mods-available/winbind.adoc[`winbind`].
+
+Due to the limitations of Active Directory, There are unfortunately no
+other possible choices.
+
+== LDAP Security Recommendations
+
+The credentials (username *and* password) for FreeRADIUS to use to
+connect to your LDAP server(s) should be secure. We make the
+following recommendations for LDAP "best practices" security.
+
+* Create a dedicated account for use by FreeRADIUS
+
+* Ensure that this account does not have administrator access
+
+* Ensure that this account is read-only, and has no write permissions
+
+* Start by using 'simple authentication' instead of
+ https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer[SASL].
+ The SASL protocol should be attempted only after 'simple
+ authentication' has been verified to work.
+
+* Use TLS for connecting between FreeRADIUS and the LDAP server. See
+ the `tls` sub-section of the default `ldap` module for instructions
+
+* When storing RADIUS user profiles (quotas, `Simultaneous-Use` flags,
+ access time restrictions, etc) in LDAP, the LDAP schema
+ `doc/schemas/ldap/openldap/freeradius.schema` must first be imported
+ into the LDAP server.
+
+== Authentication method compatibility
+
+The LDAP module is compatible a few different kinds of authentication
+methods. Note that we say _compatible_, and not _supports_. LDAP
+servers are databases, and do not support authentication protocols
+such as CHAP, MS-CHAP, or EAP.
+
+PAP::
+The user supplies a `User-Password` (plaintext or EAP-TTLS/PAP)
++
+FreeRADIUS reads the "known good" password from LDAP, and compares
+that to what the user entered.
+
+Bind as user::
+The user supplies a `User-Password` (plaintext or EAP-TTLS/PAP)
++
+FreeRADIUS uses that password to "bind as the user" to LDAP, using the
+supplied `User-Name` and `User-Password. If the bind is successfull,
+the user is authenticated. Otherwise, authentication fails.
+
+CHAP::
+The user supplies a `CHAP` password attribute.
++
+FreeRADIUS reads the "known good" password from LDAP in cleartext, and
+compares that to what the user entered.
+
+MS-CHAP::
+The user supplies a `MS-CHAP` password attribute. Either as
+MS-CHAPv2, or as PEAP/MSCHAPv2, or as EAP-TTLS/MS-CHAPv2.
++
+FreeRADIUS reads the "known good" password from LDAP in cleartext, or
+as an NT hash, and compares that to what the user entered.
+
+All of above authentication methods other than "bind as user" require
+that FreeRADIUS obtain the `userPassword` field from LDAP. If that
+field is not returned to FreeRADIUS, then normal authentication is
+impossible. Either FreeRADIUS has to be configured to use "bind as
+user" for authentication, or the LDAP database has to be updated to
+return the `userPassword` field to FreeRADIUS. This change usually
+involves giving the FreeRADIUS "read-only" user permission to read the
+`userPassword` field.
+
+Again, the best method is to test authentication is with the
+xref:howto:modules/ldap/ldapsearch.adoc[ldapsearch] tool.
+These tests *must* be run prior to configuring FreeRADIUS. We strongly
+recommend having the LDAP database return the `userPassword` field to
+FreeRADIUS, so that FreeRADIUS can authenticate the user.
+
+We also strongly recommend that the passwords be stored in LDAP as
+cleartext. Otherwise, the only authentication methods that will work
+are PAP and EAP-TTLS/PAP. The next section explains these issues in
+more detail.
+
+== Password Storage Methods
+
+If the `userPassword` field is returned from LDAP to FreeRADIUS, that
+information can be stored in a number of different formats:
+
+* the value can be cleartext
+* the value can be prepended with a string enclosed by braces, such as with `{crypt}` or `{ssha3}`.
+* the value can be have a suffix of `::`, in which case the password is generally a https://en.wikipedia.org/wiki/Base64[base64] encoded version of the real password
+
+TIP: Base64 values can be decoded via the command: `printf "%s"
+"VALUE" | base64 -d`
+
+FreeRADIUS is capable of understanding and parsing all of the above
+formats. There is sufficient information in the password values to
+determine what format it is in (base64, binary, or text), and what
+password "encryption" mechanism has been used (crypt, MD5, SHA, SSHA2,
+SHA3, etc). All that is necessary is that the
+xref:raddb:mods-available/ldap.adoc[ldap module] be configured to map
+the `userPassword` LDAP field to the `&control:Password-With-Header`
+attribute in FreeRADIUS. FreeRADIUS will then "do the right thing" to
+authenticate the user.
+
+This mapping is done in the default module configuration. There are
+no additional changes required for FreeRADIUS to correctly read and
+decode the `userPassword` field from LDAP. Please see the
+xref:raddb:mods-available/pap.adoc[pap module] for a full list of
+supported password "encryption" formats.
+
+== Additional Considerations
+
+There are some major caveats with the above authentication methods.
+The first is that we *strongly recommend* against using "bind as
+user". This process is slow, and causes unnecessary churn in the
+connections used to contact the LDAP server. Further, the "bind as
+user" process works _only_ when a `User-Password attribute exists in
+the request. If any other authentication type is used in the request,
+then the "bind as user" _will not work_. There is no amount of
+"fixing" things or configuration changes which will make it work.
+
+The second caveat is that the `CHAP` authentication type works _only_
+when a "clear text" password is stored in the LDAP database. The
+`CHAP` calclulations are designed around having access to the "clear
+text" password. It is impossible to use any "encrypted" or "hashed"
+passwords with `CHAP`.
+
+The third caveat is that the `MS-CHAP` authentication type works
+_only_ when a "clear text" password or "NT hashed" passwords which are
+stored in the LDAP database. The `MS-CHAP` calculations are designed
+around having access to "known good" passwords in those formats. It
+is impossible to use any other kind of "encrypted" or "hashed"
+passwords with `MS-CHAP`.
+
+The final caveat is that when the LDAP database contains "encrypted"
+or "hashed" passwords, the _only_ authentication type which is
+compatible with those passwords is PAP. i.e. when the `User-Password`
+is supplied to FreeRADIUS.
+
+For recommendations on password storage methods in LDAP, please see
+the LDAP
+https://openldap.org/doc/admin24/security.html#Password%20Storage[password
+storage] page. Please note that the recommendations there are made
+for LDAP security, and pay no attention to the caveats described
+above. When both RADIUS and LDAP are used together, then the
+requirements of _both_ systems must be met in order for them to work
+together. In many cases, a naive approach to LDAP security will
+prevent RADIUS from working.
+
+The issue of a database storing passwords in clear-text has to be
+balanced against the users sending clear-text passwords in
+authentication protocols. While those passwords are protected by TLS
+(EAP-TTLS) or by RADIUS (in it's own "encryption" mechanism), it is
+generally better to use a stronger authentication method than just
+PAP.
+
+In the end, there is no perfect solution to security requirements.
+The choice may be either to give up on using a particular
+authentication method, or to relax the security requirements on LDAP
+and on password storage. The final decision as to which choice is
+best can only be made by a local administrator.
+
+== Integrating Novell eDirectory with FreeRADIUS
+
+You can integrate Novell eDirectoryTM 8.7.1 or later with FreeRADIUS
+1.0.2 onwards to allow wireless authentication for eDirectory users. By
+integrating eDirectory with FreeRADIUS, you can do the following:
+
+* Use universal password for RADIUS authentication. Universal password
+provides single login and authentication for eDirectory users.
+Therefore, the users need not have a separate password for RADIUS and
+eDirectory authentication.
+* Enforce eDirectory account policies for users. The existing eDirectory
+policies on the user accounts can still be applied even after
+integrating with RADIUS. Also, you can make use of the intruder lockout
+facility of eDirectory by logging the failed logins into eDirectory.
+
+For configuration information please refer to the Novell documentation
+https://www.netiq.com/documentation/edir_radius/
*** xref:modules/expiration/index.adoc[Expiration]
*** xref:modules/krb5/index.adoc[Krb5]
*** xref:modules/ldap/index.adoc[LDAP]
-**** xref:modules/ldap/bootstrap_openldap.adoc[Bootstrap OpenLDAP]
-**** xref:modules/ldap/ldapsearch.adoc[Directory mapping and testing with ldapsearch]
-**** xref:modules/ldap/configuration.adoc[Configuration]
-**** xref:modules/ldap/authorization.adoc[Authorization]
-**** xref:modules/ldap/authentication.adoc[Authentication]
-**** xref:modules/ldap/accounting.adoc[Accounting]
+**** xref:modules/ldap/bootstrap_openldap.adoc[Installing and Configuring OpenLDAP]
+**** xref:modules/ldap/ldapsearch.adoc[Mapping and testing with ldapsearch]
+
+**** xref:modules/ldap/configuration.adoc[Enabling the LDAP module]
+**** xref:modules/ldap/authorization.adoc[Configuring authorization]
+**** xref:modules/ldap/authentication.adoc[Configuring authentication]
+**** xref:modules/ldap/accounting.adoc[Configuring accounting]
*** xref:modules/mschap/index.adoc[MS-CHAP]
*** xref:modules/pam/index.adoc[PAM]
*** xref:modules/passwd/index.adoc[Passwd]
-= rlm_ldap - Accounting
+= Configuring Accouting
-== Authenticating Users with LDAP
-
-Please be aware the FreeRADIUS is an AAA server, and LDAP
-is a _database_. This separation of roles means that FreeRADIUS
-supports multiple kinds of authentication protocols such as `PAP`,
-`CHAP`, `MS-CHAP`, etc. An LDAP database supports only one
-authentication method: "bind as user". This authentication method is
-compatible only with PAP.
-
-Our recommendation is to use LDAP as a database. FreeRADIUS should
-read the "known good" password from LDAP, and then use that
-information to authenticate the user. It is almost always wrong to
-use the LDAP "bind as user" method for authenticating users.
-
-The only caveat to the above recommendation is Active Directory. For
-"security" reasons, Active Directory will not return the "known good"
-password to FreeRADIUS over a standard LDAP query. Therefore when
-Active Directory is used, the choices are:
-
-PAP::
-Use "bind as user"
-
-MS-CHAP::
-Use xref:raddb:mods-available/ntlm_auth.adoc[`ntlm`] or xref:raddb:mods-available/winbind.adoc[`winbind`].
-
-Due to the limitations of Active Directory, There are unfortunately no
-other possible choices.
-
-Please see the xref:modules/ldap_authentication.adoc[LDAP
-authentication] concepts page for more information on the limitations
-related to authenticating users with LDAP.
-
-== LDAP Security Recommendations
-
-The credentials (username *and* password) for FreeRADIUS to use to
-connect to your LDAP server(s) should be secure. We make the
-following recommendations for LDAP "best practices" security.
-
-* Create a dedicated account for use by FreeRADIUS
-
-* Ensure that this account does not have administrator access
-
-* Ensure that this account is read-only, and has no write permissions
-
-* Start by using 'simple authentication' instead of
- https://en.wikipedia.org/wiki/Simple_Authentication_and_Security_Layer[SASL].
- The SASL protocol should be attempted only after 'simple
- authentication' has been verified to work.
-
-* Use TLS for connecting between FreeRADIUS and the LDAP server. See
- the `tls` sub-section of the default `ldap` module for instructions
-
-* When storing RADIUS user profiles (quotas, `Simultaneous-Use` flags,
- access time restrictions, etc) in LDAP, the LDAP schema
- `doc/schemas/ldap/openldap/freeradius.schema` must first be imported
- into the LDAP server.
-
-== Authentication method compatibility
-
-The LDAP module is compatible a few different kinds of authentication
-methods. Note that we say _compatible_, and not _supports_. LDAP
-servers are databases, and do not support authentication protocols
-such as CHAP, MS-CHAP, or EAP.
-
-PAP::
-The user supplies a `User-Password` (plaintext or EAP-TTLS/PAP)
-+
-FreeRADIUS reads the "known good" password from LDAP, and compares
-that to what the user entered.
-
-Bind as user::
-The user supplies a `User-Password` (plaintext or EAP-TTLS/PAP)
-+
-FreeRADIUS uses that password to "bind as the user" to LDAP, using the
-supplied `User-Name` and `User-Password. If the bind is successfull,
-the user is authenticated. Otherwise, authentication fails.
-
-CHAP::
-The user supplies a `CHAP` password attribute.
-+
-FreeRADIUS reads the "known good" password from LDAP in cleartext, and
-compares that to what the user entered.
-
-MS-CHAP::
-The user supplies a `MS-CHAP` password attribute. Either as
-MS-CHAPv2, or as PEAP/MSCHAPv2, or as EAP-TTLS/MS-CHAPv2.
-+
-FreeRADIUS reads the "known good" password from LDAP in cleartext, or
-as an NT hash, and compares that to what the user entered.
-
-All of above authentication methods other than "bind as user" require
-that FreeRADIUS obtain the `userPassword` field from LDAP. If that
-field is not returned to FreeRADIUS, then normal authentication is
-impossible. Either FreeRADIUS has to be configured to use "bind as
-user" for authentication, or the LDAP database has to be updated to
-return the `userPassword` field to FreeRADIUS. This change usually
-involves giving the FreeRADIUS "read-only" user permission to read the
-`userPassword` field.
-
-Again, the best method is to test authentication is with the
-xref:modules/ldap/search[ldapsearch] tool. These tests *must* be
-run prior to configuring FreeRADIUS. We strongly recommend having the
-LDAP database return the `userPassword` field to FreeRADIUS, so that
-FreeRADIUS can authenticate the user.
-
-We also strongly recommend that the passwords be stored in LDAP as
-cleartext. Otherwise, the only authentication methods that will work
-are PAP and EAP-TTLS/PAP. The next section explains these issues in
-more detail.
-
-== Password Storage Methods
-
-If the `userPassword` field is returned from LDAP to FreeRADIUS, that
-information can be stored in a number of different formats:
-
-* the value can be cleartext
-* the value can be prepended with a string enclosed by braces, such as with `{crypt}` or `{ssha3}`.
-* the value can be have a suffix of `::`, in which case the password is generally a https://en.wikipedia.org/wiki/Base64[base64] encoded version of the real password
-
-TIP: Base64 values can be decoded via the command: `printf "%s"
-"VALUE" | base64 -d`
-
-FreeRADIUS is capable of understanding and parsing all of the above
-formats. There is sufficient information in the password values to
-determine what format it is in (base64, binary, or text), and what
-password "encryption" mechanism has been used (crypt, MD5, SHA, SSHA2,
-SHA3, etc). All that is necessary is that the
-xref:raddb:mods-available/ldap.adoc[ldap module] be configured to map
-the `userPassword` LDAP field to the `&control:Password-With-Header`
-attribute in FreeRADIUS. FreeRADIUS will then "do the right thing" to
-authenticate the user.
-
-This mapping is done in the default module configuration. There are
-no additional changes required for FreeRADIUS to correctly read and
-decode the `userPassword` field from LDAP. Please see the
-xref:raddb:mods-available/pap.adoc[pap module] for a full list of
-supported password "encryption" formats.
-
-== Additional Considerations
-
-There are some major caveats with the above authentication methods.
-The first is that we *strongly recommend* against using "bind as
-user". This process is slow, and causes unnecessary churn in the
-connections used to contact the LDAP server. Further, the "bind as
-user" process works _only_ when a `User-Password attribute exists in
-the request. If any other authentication type is used in the request,
-then the "bind as user" _will not work_. There is no amount of
-"fixing" things or configuration changes which will make it work.
-
-The second caveat is that the `CHAP` authentication type works _only_
-when a "clear text" password is stored in the LDAP database. The
-`CHAP` calclulations are designed around having access to the "clear
-text" password. It is impossible to use any "encrypted" or "hashed"
-passwords with `CHAP`.
-
-The third caveat is that the `MS-CHAP` authentication type works
-_only_ when a "clear text" password or "NT hashed" passwords which are
-stored in the LDAP database. The `MS-CHAP` calculations are designed
-around having access to "known good" passwords in those formats. It
-is impossible to use any other kind of "encrypted" or "hashed"
-passwords with `MS-CHAP`.
-
-The final caveat is that when the LDAP database contains "encrypted"
-or "hashed" passwords, the _only_ authentication type which is
-compatible with those passwords is PAP. i.e. when the `User-Password`
-is supplied to FreeRADIUS.
-
-For recommendations on password storage methods in LDAP, please see
-the LDAP
-https://openldap.org/doc/admin24/security.html#Password%20Storage[password
-storage] page. Please note that the recommendations there are made
-for LDAP security, and pay no attention to the caveats described
-above. When both RADIUS and LDAP are used together, then the
-requirements of _both_ systems must be met in order for them to work
-together. In many cases, a naive approach to LDAP security will
-prevent RADIUS from working.
-
-The issue of a database storing passwords in clear-text has to be
-balanced against the users sending clear-text passwords in
-authentication protocols. While those passwords are protected by TLS
-(EAP-TTLS) or by RADIUS (in it's own "encryption" mechanism), it is
-generally better to use a stronger authentication method than just
-PAP.
-
-In the end, there is no perfect solution to security requirements.
-The choice may be either to give up on using a particular
-authentication method, or to relax the security requirements on LDAP
-and on password storage. The final decision as to which choice is
-best can only be made by a local administrator.
-
-== Integrating Novell eDirectory with FreeRADIUS
-
-You can integrate Novell eDirectoryTM 8.7.1 or later with FreeRADIUS
-1.0.2 onwards to allow wireless authentication for eDirectory users. By
-integrating eDirectory with FreeRADIUS, you can do the following:
-
-* Use universal password for RADIUS authentication. Universal password
-provides single login and authentication for eDirectory users.
-Therefore, the users need not have a separate password for RADIUS and
-eDirectory authentication.
-* Enforce eDirectory account policies for users. The existing eDirectory
-policies on the user accounts can still be applied even after
-integrating with RADIUS. Also, you can make use of the intruder lockout
-facility of eDirectory by logging the failed logins into eDirectory.
-
-For configuration information please refer to the Novell documentation
-https://www.netiq.com/documentation/edir_radius/
+= Configuring Authentication
== Testing
+
=== Authentication
Now in another terminal window run on the FreeRADIUS server to test authentication:
-= rlm_ldap - Authorization
+= Configuring Authorization
=== Group Membership
Depending on the LDAP vendor you use, LDAP group membership is either handled
-= Bootstrapping OpenLDAP
+= Installing and Configuring OpenLDAP
-This page describes two methods (
-<<bootstrap_with_docker,Docker>> and via <<bootstrap_with_packages,Packages>>) of creating an
-OpenLDAP instance for testing purposes.
+This page describes two methods (using <<bootstrap_with_docker,Docker>> and via
+<<bootstrap_with_packages,Packages>>) of creating an OpenLDAP instance for
+testing purposes.
-If you're looking to create a temporary instance of OpenLDAP and spin
-it up as quickly as possible, you should consider using the
+If you're looking to create a temporary instance of OpenLDAP and spin it up as
+quickly as possible, you should consider using the
https://docs.docker.com/install/[Docker containerisation service].
-This will allow you to create a self-contained, and pre-configured
-OpenLDAP instance with a minimum amount of effort.
+A pre-configured docker container allow you to create a self-contained OpenLDAP
+instance with a minimum amount of effort.
If you're looking to create a more permanent installation of OpenLDAP or
are not comfortable using docker, then you may wish to install OpenLDAP from packages.
[#bootstrap_with_docker]
== Using OpenLDAP in a docker container
+
=== Bootstrap
https://github.com/osixia[Osixia!] provides a
== Installing OpenLDAP from packages
=== Bootstrap
==== Switch to privileged user
+
[source,shell]
----
sudo -s
root user (`UID=0`, `GID=0`). When configuring OpenLDAP via OLC the `ldapadd`
utility will be run as root so our changes are authorised.
+==== Install packages
+
+OpenLDAP LTB packages available under the
+"Packaging and OpenLDAP extensions" heading https://ltb-project.org/documentation[here].
+
+You should add the appropriate repository definitions and install the `openldap`
+package (`yum install openldap` or `apt-get install openldap`).
+
==== Define site specific variables
Change the values here to match local paths and your site specific
configuration.
LDAP_READONLY_PASSWORD="readonly"
----
-==== Switch OpenLDAP from using state configuration files to OLC
+==== Switch OpenLDAP from using static configuration files to OLC
After installing OpenLDAP, `slapd` (the main OpenLDAP daemon) needs to be
switched to using OLC (on-line configuration).
EOF
----
-.Decoding OpenLDAP ACLs
+.Interpreting OpenLDAP ACLs
****
The OpenLDAP ACL syntax can be difficult to understand for new users. To help
-= Basic configuration for rlm_ldap
-The configuration step should be little more than copying the parameters used by
-xref:modules/ldap/ldapsearch.adoc[ldapsearch] to the
-xref:raddb:mods-available/ldap.adoc[ldap module] configuration file.
+= Enabling the LDAP module
+
+The configuration step should be little more than
+xref:modules/ldap/ldapsearch.adoc#_translating_ldapsearch_arguments_to_rlm_ldap_configuration_items[copying the parameters used by ldapsearch]
+to the xref:raddb:mods-available/ldap.adoc[ldap module] configuration file.
The xref:raddb:mods-available/ldap.adoc[ldap module] configuration file
describes the configuration parameters accepted by the module, and what they do.
- This document explains how to perform testing with the LDAP module.
-
-Before configuring the LDAP module, the LDAP parameters should first be
-validated via the xref:modules/ldap/search[`ldapsearch`] command-line tool.
include::howto:partial$pre_test.adoc[]
to being correct. All that is necessary is to make minor changes, and
_test_ them. FreeRADIUS should look for data.
-If the xref:modules/ldap/search[`ldapsearch`] tests above pass,
+If the xref:modules/ldap/search[ldapsearch] tests above pass,
then the LDAP module configuration can be copied directly from the
-command-line options to that tool:
+command-line options to that tool using the
+xref:modules/ldap/ldapsearch.adoc#_translating_ldapsearch_arguments_to_rlm_ldap_configuration_items[translation table] on that page.
+
+At a minimum you will need to set the following configuration items
+in in xref:raddb:mods-available/ldap.adoc[mods-available/ldap] using
+the values you discovered
+running the xref:modules/ldap/search[ldapsearch] tests.
+
+[source,config]
+----
+ldap {
+ identity = 'cn=readonly,dc=example,dc=com' <1>
+ password = 'readonly' <2>
+ server = 'ldap://localhost' <3>
+ base_dn = 'dc=example,dc=com' <4>
+
+ user {
+ base_dn = "ou=people,${..base_dn}" <5>
+ filter = '(objectClass=posixUser)' <6>
+ }
+}
+----
+
+<1> A read only user that can bind to the directory to perform searches.
+ This user should not have permission to modify the directory unless
+ you're also using LDAP for accounting
+ xref:modules/ldap/accounting.adoc[accounting].
+<2> The password for the read only user.
+<3> An LDAP URI pointing to the server. If the LDAP server is on the same
+ host as the RADIUS server, consider using a Unix Socket (`ldapi://`)
+ to reduce network overhead.
+<4> The object containing all other objects we're interested in.
+<5> The object containing all the users we need to perform AAA functions for.
+<6> Filter to select only valid user objects.
+
+We do _not_ recommend immediately configuring TLS unless you are testing against
+a production server. The best approach is to test one piece in isolation,
+before proceeding on to the next piece.
+
+== Enabling mods-available/ldap
+
+The `ldap` module is enabled by creating a soft link from the
+`mods-enabled/` directory to the `mods-available/` directory.
[source,shell]
----
-ldapsearch -D ${identity} -w ${password} -h ${server} -b 'CN=user,${base_dn}' '${filter}' '*'
+cd raddb/mods-enabled && ln -s ../mods-available/ldap
----
-Where we have the following configuration paramters:
+== Calling the LDAP module
-`${identity}`::
-The information going into the `identity` configuration item of the LDAP module.
-+
-This identity should be a read-only, non-administrator account.
+The LDAP module needs to be listed in different section depending on the
+function(s) it's performing.
-`${password}`::
-The information going into the `password` configuration item of the LDAP module.
+=== User authorization and group checks
-`${server}`::
-The information going into the `server` configuration item of the LDAP module.
-+
-This information could also be taken from the URI in the `-H`
-command-line option. We generally recommend using the URI form
-instead of a bare hostname.
+For simple authentication types like `PAP` and `CHAP` the LDAP module
+should be listed in the `recv Access-Request { ... }` (≥ v4.0.x)
+or `authorize { ... }` (≤ v3.0.x) section of the virtual server
+listening on the network (usually found in `sites-available/default`).
-`${base_dn}`::
-The information going into the `base_dn` configuration item of the LDAP module.
-+
-This is ususally something like `dc=example,dc=com`
+For EAP authentication the LDAP module should be listed in
+`sites-available/inner-tunnel` instead.
-`${filter}`::
-The information going into the `filter` configuration item of the LDAP module.
-+
-The `filter` configuration item is located inside of the `user { ... }` section/
+The LDAP module's `authorize` method will discover the authenticating user's DN
+and (optionally) cache that user's group memberships.
-We do _not_ recommend immediately configuring TLS. The best approach
-is to test one piece in isolation, before proceeding on to the next
-piece.
+It will also (optionally) check whether a user is authorized to use a particular
+service.
+[source,config]
+----
+server default {
+ ...
+ recv Access-Request {
+ ldap
+ ...
+ }
+ ...
+}
+----
-== Enabling mods-available/ldap
+Group checks may be performed _after_ the LDAP's authorize
+method has run, using the pair comparison attribute `LDAP-Group`.
-The `ldap` module is enabled by creating a soft link from the
-`mods-enabled/` directory to the `mods-available/` directory.
+[source,unlang]
+----
+server default {
+ ...
+ recv Access-Request {
+ ldap
+ if (&LDAP-Group != 'cn=authorized_users,ou=groups,dc=example,dc=com') {
+ reject
+ }
+ ...
+ }
+}
+----
-[source,shell]
+See xref:modules/ldap/authorization.adoc[LDAP authorization] for more detailed
+information on configuring LDAP/Group authorization. Including how to perform
+authorization _after_ authentication.
+
+=== User authentication with LDAP binds
+
+Before deciding which authentication to use, you should read
+xref:concepts:modules/ldap/authentication.adoc[LDAP authentication concepts] as it will
+explain which authentication methods are appropriate for different deployments
+and authentication protocols.
+
+LDAP binds for simple authentication types like `PAP` the LDAP module should be
+listed in the `recv Access-Request { ... }` and `authenticate ldap { ... }` (≥
+v4.0.x) or `authorize { ... }` and `authenticate { ... }` (≤ v3.0.x) sections of
+the virtual server listening on the network (usually found in
+`sites-available/default`).
+
+For EAP authentication the LDAP module should be listed in
+`sites-available/inner-tunnel` instead. Be aware that LDAP binds will only work
+for EAP methods which provide the user's password in the clear.
+
+[source,unlang]
----
-cd raddb/mods-enabled && ln -s ../mods-available/ldap
+server default {
+ ...
+ recv Access-Request {
+ ldap
+ if (ok || updated) {
+ update control {
+ &Auth-Type := ldap
+ }
+ }
+ }
+
+ authenticate ldap {
+ ldap
+ }
+ ...
+}
----
-It is also possible to copy the `mods-available/ldap` default
-configuration file to `mods-enabled/ldap`, and then edit that file.
-This process leaves the original `mods-available/ldap` configuration
-file in place, if there is a need to refer to it in the future. The
-choice of which method to use is up to the local administrator.
+See xref:modules/ldap/authentication.adoc[LDAP authentication] for more detailed
+information on configuring LDAP authentication.
== Testing the Server
-= Directory mapping and testing with ldapsearch
+= Mapping and testing with ldapsearch
Prior to configuring the `ldap` module, the connectivity and connection
parameters should be verified using the `ldapsearch` utility.
- There's no `memberOf` attributes. This means user to group mappings
are likely stored in group objects instead of the user objects themselves.
-.Finding users in older LDAP directories
+==== 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
```
****
-==== 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.
-
=== Groups
Groups are represented by a fairly limited subset of ObjectClasses. The
```
====
-.Finding groups in older directories
+.Finding groups in "mature" directories
****
As with users, groups may be located in multiple areas of the directory.
projects / thirdparty / freeradius-server.git / commitdiff
