From: Arran Cudbard-Bell Date: Sun, 20 Oct 2019 23:14:36 +0000 (-0400) Subject: Create a concepts doc module and move concepts pages there X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f4de2d57056b82525f996ef877b123a3db70ee02;p=thirdparty%2Ffreeradius-server.git Create a concepts doc module and move concepts pages there Reorganise LDAP howto files --- diff --git a/doc/antora/antora.yml b/doc/antora/antora.yml index bdd746affcb..c3a8cd9e018 100644 --- a/doc/antora/antora.yml +++ b/doc/antora/antora.yml @@ -10,6 +10,7 @@ start_page: ROOT:index.adoc 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 diff --git a/doc/antora/modules/ROOT/nav.adoc b/doc/antora/modules/ROOT/nav.adoc index d8bba0ebd6e..3d924122c18 100644 --- a/doc/antora/modules/ROOT/nav.adoc +++ b/doc/antora/modules/ROOT/nav.adoc @@ -1,2 +1 @@ * xref:index.adoc[Introduction] -** xref:aaa.adoc[AAA] diff --git a/doc/antora/modules/ROOT/pages/concepts.adoc b/doc/antora/modules/ROOT/pages/concepts.adoc deleted file mode 100644 index 55856e30b9e..00000000000 --- a/doc/antora/modules/ROOT/pages/concepts.adoc +++ /dev/null @@ -1,7 +0,0 @@ -= Concepts - -List with some articles related to RADIUS. - -## Topics - -* xref:aaa.adoc[AAA] diff --git a/doc/antora/modules/ROOT/pages/index.adoc b/doc/antora/modules/ROOT/pages/index.adoc index 235593f90ff..fc5f60fe671 100644 --- a/doc/antora/modules/ROOT/pages/index.adoc +++ b/doc/antora/modules/ROOT/pages/index.adoc @@ -29,7 +29,7 @@ Everything in the server is fully documented, and there are many 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/` @@ -95,7 +95,7 @@ http://packages.networkradius.com[Network RADIUS, window="_blank"] packages wher 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. diff --git a/doc/antora/modules/concepts/nav.adoc b/doc/antora/modules/concepts/nav.adoc new file mode 100644 index 00000000000..493b9566417 --- /dev/null +++ b/doc/antora/modules/concepts/nav.adoc @@ -0,0 +1,6 @@ +* xref:index.adoc[Concepts] +** General +*** xref:aaa.adoc[AAA] +** Modules +*** LDAP +**** xref:modules/ldap/authentication.adoc[Authentication] diff --git a/doc/antora/modules/ROOT/pages/aaa.adoc b/doc/antora/modules/concepts/pages/aaa.adoc similarity index 100% rename from doc/antora/modules/ROOT/pages/aaa.adoc rename to doc/antora/modules/concepts/pages/aaa.adoc diff --git a/doc/antora/modules/concepts/pages/index.adoc b/doc/antora/modules/concepts/pages/index.adoc new file mode 100644 index 00000000000..f2bc25f36fa --- /dev/null +++ b/doc/antora/modules/concepts/pages/index.adoc @@ -0,0 +1,8 @@ += 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. diff --git a/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc b/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc new file mode 100644 index 00000000000..bc35ac6eee6 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc @@ -0,0 +1,203 @@ +== 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/ diff --git a/doc/antora/modules/howto/nav.adoc b/doc/antora/modules/howto/nav.adoc index 2eda16a80a4..473b19d528d 100644 --- a/doc/antora/modules/howto/nav.adoc +++ b/doc/antora/modules/howto/nav.adoc @@ -6,12 +6,13 @@ *** 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] diff --git a/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc b/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc index d8cf4dd67ad..d5ab8823e48 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/accounting.adoc @@ -1 +1 @@ -= rlm_ldap - Accounting += Configuring Accouting diff --git a/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc b/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc index bdd7f464d29..71ab360c9c2 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authentication.adoc @@ -1,212 +1,7 @@ -== 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: diff --git a/doc/antora/modules/howto/pages/modules/ldap/authorization.adoc b/doc/antora/modules/howto/pages/modules/ldap/authorization.adoc index 4d3bcb4cada..010b3a211c8 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/authorization.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/authorization.adoc @@ -1,4 +1,4 @@ -= rlm_ldap - Authorization += Configuring Authorization === Group Membership Depending on the LDAP vendor you use, LDAP group membership is either handled diff --git a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap.adoc b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap.adoc index 9aaa3b68246..54830265b5e 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/bootstrap_openldap.adoc @@ -1,15 +1,15 @@ -= Bootstrapping OpenLDAP += Installing and Configuring OpenLDAP -This page describes two methods ( -<> and via <>) of creating an -OpenLDAP instance for testing purposes. +This page describes two methods (using <> and via +<>) 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. @@ -20,6 +20,7 @@ using the OpenLDAP LTB packages available under the [#bootstrap_with_docker] == Using OpenLDAP in a docker container + === Bootstrap https://github.com/osixia[Osixia!] provides a @@ -107,6 +108,7 @@ setup correctly>>. == Installing OpenLDAP from packages === Bootstrap ==== Switch to privileged user + [source,shell] ---- sudo -s @@ -120,6 +122,14 @@ For convenience we will configure the OLC database to be modifiable only by the 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. @@ -143,7 +153,7 @@ LDAP_ADMIN_PASSWORD="secret" 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). @@ -214,7 +224,7 @@ olcAccess: to dn.base="" by * read EOF ---- -.Decoding OpenLDAP ACLs +.Interpreting OpenLDAP ACLs **** The OpenLDAP ACL syntax can be difficult to understand for new users. To help diff --git a/doc/antora/modules/howto/pages/modules/ldap/configuration.adoc b/doc/antora/modules/howto/pages/modules/ldap/configuration.adoc index c7ea773395b..20eda3c8397 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/configuration.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/configuration.adoc @@ -1,14 +1,11 @@ -= 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[] @@ -19,62 +16,150 @@ possible in the default configuration. The defaults are usually close 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 diff --git a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch.adoc b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch.adoc index b9d8b80a800..5192a7946bc 100644 --- a/doc/antora/modules/howto/pages/modules/ldap/ldapsearch.adoc +++ b/doc/antora/modules/howto/pages/modules/ldap/ldapsearch.adoc @@ -1,4 +1,4 @@ -= 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. @@ -296,7 +296,24 @@ efficient). - 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 @@ -339,23 +356,6 @@ ldapsearch ... -E 'pr=100' "(|(ObjectClass=...))" "dn" | ... ``` **** -==== 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 @@ -399,7 +399,7 @@ result: 0 Success ``` ==== -.Finding groups in older directories +.Finding groups in "mature" directories **** As with users, groups may be located in multiple areas of the directory.