== 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.

include::ROOT:partial$externaldoc.adoc[]

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"

https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/raddb/mods-available/mschap[MS-CHAP::]
Use https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/raddb/mods-available/ntlm_auth[`ntlm`] and https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/raddb/mods-available/mschap[`winbind`] configuration.

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-radius.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.

https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/raddb/mods-available/pap[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.

https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/raddb/mods-available/chap[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.

https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/raddb/mods-available/mschap[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
https://www.freeradius.org/documentation/freeradius-server/4.0.0/howto/modules/ldap/ldapsearch/index.html[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
https://github.com/FreeRADIUS/freeradius-server/tree/v3.2.x/raddb/mods-available/ldap[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
https://github.com/FreeRADIUS/freeradius-server/blob/v3.2.x/raddb/mods-available/pap[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 https://www.netiq.com/documentation/edir_radius/[Novell documentation].
