From 3e62369d3d0b095a450037efa3335fc58f9de4ca Mon Sep 17 00:00:00 2001 From: nolade Date: Tue, 27 May 2025 15:02:25 -0400 Subject: [PATCH] docs: Update Concept section as top-level section, intro/landing page, xrefs. Added components section to include server, nas, datastore infoi and radius session/message/processing sections.docs: update concepts and radius components section --- doc/antora/modules/ROOT/pages/faq.adoc | 4 +- .../concepts/images/request_flow_4.0.svg | 276 ++++++++++++++++++ doc/antora/modules/concepts/nav.adoc | 27 +- doc/antora/modules/concepts/pages/aaa.adoc | 93 ------ .../modules/concepts/pages/architecture.adoc | 42 --- .../modules/concepts/pages/database.adoc | 12 - doc/antora/modules/concepts/pages/index.adoc | 29 +- .../concepts/pages/modules/aaa/aaa.adoc | 33 +++ .../concepts/pages/modules/aaa/acct.adoc | 13 + .../concepts/pages/modules/aaa/authn.adoc | 21 ++ .../concepts/pages/modules/aaa/authz.adoc | 41 +++ .../modules/components/architecture.adoc | 24 ++ .../pages/modules/components/datastore.adoc | 24 ++ .../pages/{ => modules/components}/nac.adoc | 0 .../pages/{ => modules/components}/nas.adoc | 12 +- .../pages/modules/components/policy.adoc | 18 ++ .../{ => modules/components}/radius.adoc | 2 +- .../modules/components/radius_servers.adoc | 37 +++ .../concepts/pages/modules/freeradius.adoc | 43 +++ .../pages/modules/ldap/authentication.adoc | 147 ++-------- .../{ => ldap}/ldap_authentication.adoc | 8 +- .../concepts/pages/modules/ldap/novell.adoc | 15 + .../pages/modules/ldap/password_storage.adoc | 82 ++++++ .../{ => modules/protocol}/authproto.adoc | 190 ++++++------ .../{ => pages/modules/protocol}/peap.adoc | 0 .../pages/{ => modules/protocol}/wep.adoc | 0 .../pages/{ => modules/protocol}/wpa.adoc | 2 +- .../pages/modules/session/processing.adoc | 126 ++++++++ .../pages/modules/session/radius_session.adoc | 39 +++ .../modules/session/radius_session_msg.adoc | 127 ++++++++ .../modules/concepts/pages/overview.adoc | 110 +++---- .../modules/concepts/pages/processing.adoc | 89 ------ .../concepts/pages/virtual_servers.adoc | 10 +- 33 files changed, 1139 insertions(+), 557 deletions(-) create mode 100644 doc/antora/modules/concepts/images/request_flow_4.0.svg delete mode 100644 doc/antora/modules/concepts/pages/aaa.adoc delete mode 100644 doc/antora/modules/concepts/pages/architecture.adoc delete mode 100644 doc/antora/modules/concepts/pages/database.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/aaa/aaa.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/aaa/acct.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/aaa/authn.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/aaa/authz.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/components/architecture.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/components/datastore.adoc rename doc/antora/modules/concepts/pages/{ => modules/components}/nac.adoc (100%) rename doc/antora/modules/concepts/pages/{ => modules/components}/nas.adoc (87%) create mode 100644 doc/antora/modules/concepts/pages/modules/components/policy.adoc rename doc/antora/modules/concepts/pages/{ => modules/components}/radius.adoc (96%) create mode 100644 doc/antora/modules/concepts/pages/modules/components/radius_servers.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/freeradius.adoc rename doc/antora/modules/concepts/pages/modules/{ => ldap}/ldap_authentication.adoc (91%) create mode 100644 doc/antora/modules/concepts/pages/modules/ldap/novell.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/ldap/password_storage.adoc rename doc/antora/modules/concepts/pages/{ => modules/protocol}/authproto.adoc (60%) rename doc/antora/modules/concepts/{ => pages/modules/protocol}/peap.adoc (100%) rename doc/antora/modules/concepts/pages/{ => modules/protocol}/wep.adoc (100%) rename doc/antora/modules/concepts/pages/{ => modules/protocol}/wpa.adoc (99%) create mode 100644 doc/antora/modules/concepts/pages/modules/session/processing.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/session/radius_session.adoc create mode 100644 doc/antora/modules/concepts/pages/modules/session/radius_session_msg.adoc delete mode 100644 doc/antora/modules/concepts/pages/processing.adoc diff --git a/doc/antora/modules/ROOT/pages/faq.adoc b/doc/antora/modules/ROOT/pages/faq.adoc index f35a8e4a43..76bc3a9a0a 100644 --- a/doc/antora/modules/ROOT/pages/faq.adoc +++ b/doc/antora/modules/ROOT/pages/faq.adoc @@ -10,14 +10,14 @@ Read this FAQ before posting questions to the mailing lists as your question may == FreeRADIUS Overview -FreeRADIUS is the worlds leading RADIUS server used by Internet Service Providers (ISPs), cellular providers, and corporate and educational networks. RADIUS, which stands for “Remote Authentication Dial In User Service”, is a network protocol used to manage network access using xref:concepts:authproto.adoc[Authentication, Authorization and Accounting] processes. +FreeRADIUS is the worlds leading RADIUS server used by Internet Service Providers (ISPs), cellular providers, and corporate and educational networks. RADIUS, which stands for “Remote Authentication Dial In User Service”, is a network protocol used to manage network access using xref:concepts:modules/protocol/authproto.adoc[Authentication, Authorization and Accounting] processes. FreeRADIUS is developed by a group of people who call themselves "The FreeRADIUS Project" and is sponsored by https://www.inkbridgenetworks.com/[InkBridge Networks]. === What is FreeRADIUS and what is it supposed to do? The FreeRADIUS Server is a daemon for unix and unix like operating systems which allows one to set up a radius protocol server. The RADIUS protocol manages the communication between network devices to facilitate remote user -authentication and accounting practices. See xref:concepts:architecture.adoc[Architecture] for more information on RADIUS components and interactions. The RADIUS protocol serves three primary functions: +authentication and accounting practices. See xref:concepts:modules/components/architecture.adoc[Architecture] for more information on RADIUS components and interactions. The RADIUS protocol serves three primary functions: * Authenticates users or devices before allowing them access to a network. * Authorizes those users or devices for specific network services. diff --git a/doc/antora/modules/concepts/images/request_flow_4.0.svg b/doc/antora/modules/concepts/images/request_flow_4.0.svg new file mode 100644 index 0000000000..e6a6a8d32b --- /dev/null +++ b/doc/antora/modules/concepts/images/request_flow_4.0.svg @@ -0,0 +1,276 @@ + + + + + + Canvas 1 + + + Layer 1 + + + + + + + + + + Text + + module x + + + + + + + + + + + + + Text + + module y + + + + + + + Text + + server {} + + + + + + + + + + + + + + + + + + + Text + + Authenticate {} + + + + + + + + + + Text + + module z + + + + + + + + + + Text + + Auth-Type z {} + + + + + + + + + + + + + + + + + + + Text + + Listener proto a + + + + + + + + + + + + + Text + + Author Arran Cudbard-Bell + Copyright 2025 The FreeRADIUS project + Creative commons license CC BY + + + + + + + + + + + + + + + + + + + + + + Text + + Auth-Type y {} + + + + + + + + + + Text + + Auth-Type x {} + + + + + + + + + + Text + + Listener proto a + + + + + + + + + + + + + + + + Text + + Post-Auth-Type Reject {} + + + + + + + + + + Text + + Post-Auth {} + + + + + + + + + + + + + Text + + Reject path is followed if the rcode set for a section when the request leaves, is not ok or fail + + + + + + + + + + Text + + Autz-Type a {} + + + + + + + + + + Text + + Autz-Type b {} + + + + + + + + + + Text + + Autz-Type c {} + + + + + + + + + + Text + + Authorize {} + + + + + + + diff --git a/doc/antora/modules/concepts/nav.adoc b/doc/antora/modules/concepts/nav.adoc index 979b38f1c8..7394269558 100644 --- a/doc/antora/modules/concepts/nav.adoc +++ b/doc/antora/modules/concepts/nav.adoc @@ -1,13 +1,22 @@ * xref:index.adoc[Concepts] -** xref:overview.adoc[General] -*** xref:architecture.adoc[Architecture] -*** xref:authproto.adoc[Protocols] -*** xref:database.adoc[Datastores] -** xref:aaa.adoc[AAA] -*** xref:processing.adoc[Processing] -** Modules -*** LDAP -**** xref:modules/ldap/authentication.adoc[Authentication] +** xref:overview.adoc[Overview] +*** xref:modules/freeradius.adoc[What is FreeRADIUS] +*** xref:modules/aaa/aaa.adoc[Authentication Authorisation Accounting (AAA)] +**** xref:modules/aaa/authz.adoc[Authorisation] +**** xref:modules/aaa/authn.adoc[Authentication] +**** xref:modules/aaa/acct.adoc[Accounting] +*** xref:modules/components/architecture.adoc[RADIUS System Components] +**** xref:modules/components/nas.adoc[Network Access Server (NAS)] +**** xref:modules/components/radius_servers.adoc[RADIUS Server] +***** xref:modules/components/radius_servers.adoc#policy[Server Policies] +**** xref:modules/components/datastore.adoc[Datastores] +*** xref:modules/session/radius_session.adoc[RADIUS Sessions] +**** xref:modules/session/radius_session_msg.adoc[Messages] +**** xref:modules/session/processing.adoc[Processing] +** xref:modules/protocol/authproto.adoc[Protocols] +** xref:modules/ldap/authentication.adoc[Authentication with LDAP] +*** xref:modules/ldap/password_storage.adoc[Password Storage] +*** xref:modules/ldap/novell.adoc[Integrate Novell] ** xref:resources.adoc[Resources] // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. diff --git a/doc/antora/modules/concepts/pages/aaa.adoc b/doc/antora/modules/concepts/pages/aaa.adoc deleted file mode 100644 index 97933d488a..0000000000 --- a/doc/antora/modules/concepts/pages/aaa.adoc +++ /dev/null @@ -1,93 +0,0 @@ -= AAA - -== Authorization, Authentication, and Accounting request handling - -There are a lot of questions about misconfigured FreeRADIUS servers -because of misunderstanding of FreeRADIUS operations. This document -explains how the server operates. - -Normally there are two steps in processing an authentication request -coming from a NAS in FreeRADIUS: authorization and authentication. -If we use FreeRADIUS as a proxy to re-send the request to another -RADIUS server there will be additional steps. - -=== Authorization - -Authorization is the process of finding and returning information -about what the user is allowed to do. For example, finding out what -kind of authentication methods they are allowed to run, and what VLAN -the user should be placed into. - -Authorization modules generally "get data" from somewhere, -e.g. `ldap`, `sql`, `files`, etc. - -The authentication method is usually determined when the server gets -the users credentials from a database. Once the credentials are -available, the server can authenticate the user. - -=== Authentication - -Authentication is simply a process of comparing user’s credentials in -request with the "known good" credentials retrieved from a -database. Authentication usually deals with password -encryption. The modules `pap`, `chap`, `mschap`, etc. do authentication. - -Some modules do both authentication and limited authorization. For -example, the `mschap` module authenticates MS-CHAP credentials, but it -may also be used as an authorization module, which verifies that -request contains `MS-CHAP` related attribute. If so, the module -instructs the server to use `mschap` for authentication, too - -These dual modules are usually related to protocol-specific -attributes, such as the `pap` module for the `User-Password` -attribute, `chap` for `CHAP-Password`, `mschap` for `MS-CHAP-*`, etc. - -=== Request Processing - -When the server processes requests, it manages four -xref:reference:unlang/list.adoc[attribute lists]. - -.Attribute Lists and Details - -[cols="1,2"] -|=== -|Attribute List|Description - -|`request` -|Attributes taken from the received packet. - -|`reply` -|Attributes which will be sent in the reply. - -|`control` -|Attributes used to control how the server operates. These are never sent in a packet. - -|`session-state` -|Attributes which are saved and restored across multiple request / reply exchanges. -|=== - -All of these lists are available to all modules. All of these lists are available in xref:reference:unlang/index.adoc[Unlang] - -=== Accounting - -Accounting refers to the recording of resources a user consumes during the time they are on the network. -The information gathered can include the amount of system time used, the amount of data sent, or the -quantity of data received by the user during a session. - -During a network session, the NAS periodically sends an accounting of user activity to the server. This -accounting is a summary, and the collected data is used for billing purposes. -ISPs are a large consumer of accounting data, because each user is billed for every minute of network -access. However, corporations have not, historically, relied on network accounting information gathered -by RADIUS because employees were not traditionally billed for network access. As their need for ongoing -network monitoring increases, though, so does the need to store and process accounting information. -The accounting summary sent by the NAS to the server does not include detailed information such as web -sites visited or even how many bytes were transferred using a particular protocol (SMTP, HTTP, and so -forth). That type of detailed information is only available to the NAS, and it does not send that data to the -server. - -If detailed information about user activity is required, network administrators can obtain it through other -protocols such as sFlow or NetFlow. Network administrators may find it difficult to tie the pieces together to get a more comprehensive -understanding of user activity. - -// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. -// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/architecture.adoc b/doc/antora/modules/concepts/pages/architecture.adoc deleted file mode 100644 index da77f4f6a6..0000000000 --- a/doc/antora/modules/concepts/pages/architecture.adoc +++ /dev/null @@ -1,42 +0,0 @@ -= Architecture - -RADIUS is a network protocol, a system that defines rules and conventions for communication between -network device. Like many protocols, RADIUS uses a client-server model. A RADIUS client (also called a -Network Access Server, or NAS) sends requests to a RADIUS server. The RADIUS server then processes the -request and sends back a response. - -Common NAS products include wireless access points such as the Linksys WRT54G and dial-up -equipment commonly available from large network manufacturers. Common RADIUS server products -include Cisco ACS, Microsoft IAS, Funk (now Juniper) Steel Belted RADIUS, Open Systems Radiator, and -FreeRADIUS. - -== RADIUS Components - -The RADIUS protocol shares the general concept of client-server communication with many other -protocols such as HTTP and SMTP, the specifics of RADIUS communications differ. This section describes -the RADIUS system in more detail, including the specific roles of the NAS, the server, and datastores such -as MySQL and Lightweight Directory Access Protocol (LDAP). - -=== User / Device - -Requests access to the network. A device may be a laptop, modem, or VOIP Phone - -=== Network Access Server (NAS) - -Provides access to the network for the user/device. The NAS can be a switch, Wireless Access Point, or VPN Terminator. - -=== Authentication Server - -Receives authentication requests from the NAS and returns authentication results to the NAS. -Optionally requests user and configuration information from the database or directory. The server may -return configuration parameters to the NAS. Receives accounting information from the NAS. Some exanples of a RADIUS server -are FreeRADIUS, Radiator, NPS, or IAS. - -=== Datastore - -Optional database or directory with user authentication and authorisation information. RADIUS server communicates with the -data store using DB API or LDAP. Types of data stores include SQL Database, Kerberos Service Server, or an -LDAP Directory. - -// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. -// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/database.adoc b/doc/antora/modules/concepts/pages/database.adoc deleted file mode 100644 index 557f531576..0000000000 --- a/doc/antora/modules/concepts/pages/database.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Databases - -== RADIUS Information - -https://www.freeradius.org/[FreeRADIUS] - -https://www.inkbridgenetworks.com/[Inkbridge Networks] - - - -// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. -// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/index.adoc b/doc/antora/modules/concepts/pages/index.adoc index b1bc067854..bb502634b8 100644 --- a/doc/antora/modules/concepts/pages/index.adoc +++ b/doc/antora/modules/concepts/pages/index.adoc @@ -1,14 +1,29 @@ = Concepts -This section introduces you to the main concepts behind RADIUS and it's related components. -It is intended for users with limited RADIUS knowledge or experience. The information provided will help us understand the basic concepts and how RADIUS works in a network environment. +The Concepts guide introduces the main concepts for readers who are new to RADIUS (Remote Authentication Dial-In User Service) and its associated components. This information explains the foundational ideas and principles behind RADIUS to help you understand what RADIUS is, what it does, and how it operates within a network environment. By covering these basics, the section aims to provide a solid starting point for further exploration or practical use of RADIUS in network authentication, authorization, and accounting. + +== Sections in this Guide + +* xref:concepts:overview.adoc[Overview] explains the RADIUS server, FreeRADIUS, and the core services provided. + ** xref:modules/freeradius.adoc[What is FreeRADIUS] explains the benefits of the open-source software version. + ** xref:modules/aaa/aaa.adoc[Authentication Authorisation Accounting (AAA)] explains the core services provided by FreeRADIUS. + *** xref:modules/aaa/authz.adoc[Authorisation] is the process of allowing an authenticated user to access services on the network. + *** xref:modules/aaa/authn.adoc[Authentication] if the process of verifying an end-user's credentials. + *** xref:modules/aaa/acct.adoc[Accounting] operations record the time spent on the network and services accessed for auditing or billing purposes. + ** xref:modules/components/architecture.adoc[RADIUS System Components] explains the RADIUS design and components. + *** xref:modules/components/nas.adoc[Network Access Server (NAS)] outlines the NAS operations and access management. + *** xref:modules/components/radius_servers.adoc[RADIUS Server] describes the role of the server and how server policies work. + *** xref:modules/components/datastore.adoc[Datastores] details how datastores work and what's supported. + ** xref:modules/session/radius_session.adoc[RADIUS Sessions] explains session transmission and management or these session on the network. + *** xref:modules/session/radius_session_msg.adoc[Session Messages] details the format and content of session messages. + *** xref:modules/session/processing.adoc[Processing] outlines the flow of messages and how aaa services are implemented. +* xref:modules/protocol/authproto.adoc[Protocols] defines the protocols used in the RADIUS environment. +* xref:modules/ldap/authentication.adoc[Authentication with LDAP] can be used by RADIUS servers to authenticate the network users. + ** xref:modules/ldap/password_storage.adoc[Password Storage] explains the methods of how the user's information can be stored. + ** xref:modules/ldap/novell.adoc[Integrate Novell] with RADIUS networks using LDAP. +* xref:resources.adoc[Resources] find more help, mailing lists, and related documentation to help learn about deploying FreeRADIUS. -The following sections are: -* xref:concepts:overview.adoc[Overview] outlines the RADIUS protocol, features, and benefits. -* xref:concepts:architecture.adoc[Architecture] explains the RADIUS design and components. -* xref:concepts:authproto.adoc[Protocols] defines the protocols used in the RADIUS environment. -* xref:concepts:database.adoc[Datastores] details how datastores work and what's supported. // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/modules/aaa/aaa.adoc b/doc/antora/modules/concepts/pages/modules/aaa/aaa.adoc new file mode 100644 index 0000000000..36af4fc6ad --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/aaa/aaa.adoc @@ -0,0 +1,33 @@ += Authorisation, Authentication, and Accounting (AAA) + +RADIUS is one of a number of Authentication, Authorisation, and Accounting (AAA) protocols. Other examples of AAA protocols include TACACS+ and Diameter. AAA defines an architecture that authenticates and grants authorisation to users and accounts for their activity. When AAA is not used, the network architecture is "open", where anyone can gain access and do anything, without any tracking. The open network architecture is commonly used in small businesses, where access to an office can be physically controlled. The open network architecture is poorly suited to ISPs, where access needs to be strictly controlled and accounted for. + +It is possible to incorporate only a portion of AAA in a system. For example, if a company is not concerned about billing users for their network usage, they may decide to both authenticate and authorise users, but ignore user activity and not deal with accounting. Similarly, a monitoring system will look for unusual user activity (accounting), but may delegate the authentication and authorisation decisions to another part of the network. + +Without AAA, a network administrator would have to statically configure a network. Even in the earliest days of dialup access, network administrators found a static model inadequate. AAA ensures the flexibility of network policies. AAA also gives network administrators the ability to move systems; without AAA, they would have to clearly define connectivity options. + +Today, the proliferation of mobile devices, diverse network consumers, and varied network access methods combine to create an environment that places greater demands on AAA. AAA has a part to play in almost all the ways we access a network: wireless hotspots use AAA for security; partitioned networks require AAA to enforce access; all forms of remote access use AAA to authorise remote users. + +The following sections describe each part of the AAA solution, and how each one works. + +== AAA request handling + +AAA request handling refers to the process by which a system manages xref:modules/aaa/authn.adoc[authentication], xref:modules/aaa/authz.adoc[authorisation], and xref:modules/aaa/acct.adoc[accounting] (AAA) services for users accessing computer resources or network services. This process involves verifying user identities, granting access based on permissions, and tracking their activities for auditing or billing purposes. + +Normally there are two steps in processing an authentication request +coming from a NAS in FreeRADIUS: authorisation and authentication. +If we use FreeRADIUS as a proxy to re-send the request to another +RADIUS server there will be additional steps. + +=== Authentication vs. Authorisation + +The following analogy illustrates the difference between Authentication and Authorisation: + +Imagine you are driving a car and you are stopped by a police officer. The officer asks you to provide a piece of identification to identify yourself. You could, for example, use your passport, driver’s license, or ID card to prove or *authenticate* who you are. In terms of the RADIUS protocol, the authentication process identifies the user as someone who is allowed to access the network. + +The police officer may also ask you to prove that you are authorized to drive. In this case, there is only one document - a driver’s license - that proves that you are permitted or *authorized* to drive a car. + +The authorisation process combines the policy on the RADIUS server and the information in the request from the NAS. The NAS may add additional information to the request, such as the user’s Media Access Control (MAC) address. The NAS sends the information to the server, where an authorisation decision is made. + +// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/modules/aaa/acct.adoc b/doc/antora/modules/concepts/pages/modules/aaa/acct.adoc new file mode 100644 index 0000000000..d12810274f --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/aaa/acct.adoc @@ -0,0 +1,13 @@ += Accounting + +Accounting refers to the recording of resources a user consumes during the time they are on the network. The information gathered can include the amount of system time used, the amount of data sent, or the quantity of data received by the user during a session. + +During a network session, the NAS periodically sends an accounting of user activity to the server. This accounting is a summary, and the collected data is used for billing purposes. + +ISPs are a large consumer of accounting data, because each user is billed for every minute of network access. However, corporations have not, historically, relied on network accounting information gathered by RADIUS because employees were not traditionally billed for network access. As their need for ongoing +network monitoring increases, though, so does the need to store and process accounting information. + +The accounting summary sent by the NAS to the server does not include detailed information such as web sites visited or even how many bytes were transferred using a particular protocol (SMTP, HTTP, and so forth). That type of detailed information is only available to the NAS, and it does not send that data to the +server. + +If detailed information about user activity is required, network administrators can obtain it through other protocols such as sFlow or NetFlow. Network administrators may find it difficult to tie the pieces together to get a more comprehensive understanding of user activity. diff --git a/doc/antora/modules/concepts/pages/modules/aaa/authn.adoc b/doc/antora/modules/concepts/pages/modules/aaa/authn.adoc new file mode 100644 index 0000000000..bf4c6626b7 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/aaa/authn.adoc @@ -0,0 +1,21 @@ += Authentication + +Authentication refers to the process of validating the identity of the user by matching the credentials supplied by the user (for example, name, password) to those configured on the AAA server (for example, name, password). If the credentials match, the user is authenticated and gains access to the network. If +the credentials do not match, authentication fails, and network access is denied. + +Authentication can also fail if user credentials are entered incorrectly. For example, site policy may allow a user network access from an on-site location using a cleartext password. However, if the same password is entered by the user from a remote location, access may be denied. + +An ISP can also choose to deny network access to authenticated users if the users’ account has been suspended. An administrator can choose to permit limited network access to unknown users, as well. For example, an administrator can provide access to an area where the user can purchase additional network +connectivity. This last example is most often seen in for-pay WiFi hotspots. + +Authentication is simply a process of comparing user’s credentials in request with the "known good" credentials retrieved from a database. Authentication usually deals with password encryption. The modules `pap`, `chap`, `mschap`, etc. do authentication. + +Some modules do both authentication and limited authorisation. For +example, the `mschap` module authenticates MS-CHAP credentials, but it +may also be used as an authorisation module, which verifies that +request contains `MS-CHAP` related attribute. If so, the module +instructs the server to use `mschap` for authentication, too + +These dual modules are usually related to protocol-specific +attributes, such as the `pap` module for the `User-Password` +attribute, `chap` for `CHAP-Password`, `mschap` for `MS-CHAP-*`, etc. diff --git a/doc/antora/modules/concepts/pages/modules/aaa/authz.adoc b/doc/antora/modules/concepts/pages/modules/aaa/authz.adoc new file mode 100644 index 0000000000..be5289e76f --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/aaa/authz.adoc @@ -0,0 +1,41 @@ += Authorisation + +Authorisation is the process of finding and returning information +about what the user is allowed to do. For example, finding out what +kind of authentication methods they are allowed to run, and what VLAN +the user should be placed into. + +Authorisation modules generally "get data" from somewhere, +e.g. `ldap`, `sql`, `files`, etc. + +The authentication method is usually determined when the server gets +the users credentials from a database. Once the credentials are +available, the server can authenticate the user. + +Authorisation refers to the process of determining what permissions are granted to the user. For example, the user may or may not be permitted certain kinds of network access or allowed to issue certain commands. + +The NAS sends a “request” - a packet of information about the user - and the RADIUS server either grants or denies authorisation based solely on information in the “request” sent by the NAS.In each case, the RADIUS server manages the authorisation policy and the NAS enforces the policy. + +The NAS “request” is really a set of statements. For example, the NAS may send the RADIUS server a “request” containing the following user information: + +``` +“user name is Bob” +“password is Hello” +“ip address is 192.02.34” +``` + +Once the server receives the request, it uses that information to figure out what properties the user should have (i.e. “Bob” is saying he/she has IP address 192.0.2.34, do the server records contradict this statement?). +The server then sends a reply to the NAS. The reply contains a series of statements about what properties the user should have: + +``` +"user name is Bob" +"ip address is 192.0.2.78" +``` + +[NOTE] +==== +The RADIUS server can’t request further information from the NAS. In contrast with SQL systems, RADIUS is limited in that it cannot make complicated queries. In SQL, queries such as "SELECT name from table where ipaddress = 192.02.34" are common. RADIUS does not have that capability. Instead, RADIUS +only makes statements about what is, and what should be. +==== + +Upon receipt of a reply from the server, the NAS tries to enforce those properties on the user. properties cannot be enforced, the NAS closes the connection. diff --git a/doc/antora/modules/concepts/pages/modules/components/architecture.adoc b/doc/antora/modules/concepts/pages/modules/components/architecture.adoc new file mode 100644 index 0000000000..e0592c1313 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/components/architecture.adoc @@ -0,0 +1,24 @@ += RADIUS System Components + +RADIUS is a network protocol, a system that defines rules and conventions for communication between network devices. Like many protocols, RADIUS uses a client-server model. A RADIUS client (also called a Network Access Server (NAS) ) sends requests to a RADIUS server. The RADIUS server then processes the +request and sends back a response. + +Common NAS products include wireless access points such as the Linksys WRT54G and dial-up equipment commonly available from large network manufacturers. Common RADIUS server products include Cisco ACS, Microsoft IAS, Juniper, Open Systems Radiator, and FreeRADIUS. + +The RADIUS protocol shares the general concept of client-server communication with many other protocols such as HTTP and SMTP, the specifics of RADIUS communications differ. This section describes the RADIUS system in more detail, including the specific roles of the NAS, the server, and datastores such as MySQL and Lightweight Directory Access Protocol (LDAP). + +This section describes the RADIUS system in more detail, including the specific roles of the NAS, the server, and datastores such as MySQL and Lightweight Directory Access Protocol (LDAP). + +.Examples of System Components +[opts="headers, autowidth"] +|=== +| *Component* | *Description* | *Examples* +| User or a device | Requests access to the network.| Laptop, tablet, modem, mobile, or VOIP phone. +| Network Access Server (NAS)| Provides access to the network for the user or device. | Switch, wireless access point (WAP), or VPN terminator. +| Authentication Server | Receives authentication requests from the NAS and returns authentication results to the NAS. Optionally requests user and configuration information from the datastore. The server may also +return configuration parameters to the NAS. Receives accounting information from the NAS. | FreeRADIUS, Radiator, Network Policy Server (NPS), or an Internet Authentication Service (IAS). +| Optional datastore such as a database or directory containing user authentication and authorisation information.| RADIUS server communicates with the datastore using a database API or LDAP. | SQL Database, Kerberos Service Server, or an LDAP Directory. +|=== + +// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/modules/components/datastore.adoc b/doc/antora/modules/concepts/pages/modules/components/datastore.adoc new file mode 100644 index 0000000000..ec4dadcbc1 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/components/datastore.adoc @@ -0,0 +1,24 @@ += Datastore + +Datastores (i.e., databases or directories) permit the storage and retrieval of data. They have limited decision-making capabilities. While stored procedures are possible in most databases, they are rarely +used when simple data storage is required. + +The key differences between RADIUS servers and datastores are the way they support policies and authentication. The role of a data store in the authentication process is to provide data to a RADIUS server. The server then uses an authentication method to authenticate the user. + +When a RADIUS server authenticates a user or stores accounting data for that user, it reads from or writes to a database or directory.User information (i.e., user name, password, credit amount) and session data (i.e., total session time and statistics for total traffic to and from the user) are stored on this database or directory. + +In many respects, the RADIUS protocol is similar to a remote database query language. Specifically, while an SQL or LDAP database stores user data, that database cannot be queried directly by the NAS. Instead, the NAS sends a request to the server, which in turn queries the database. This simplification of the normal database query language means that it is easy to add authentication and accounting to an NAS instead of implementing a full-featured SQL client, which would be very resource intensive and costly. + +.Comparison of Datastores and RADIUS Servers +[opts="headers, autowidth"] +|=== +| *Datastore* | *RADIUS Server* +| Stores authentication and authorisation data | Processes data retrieved from the datastore. +| Rarely implements policies. | Implements policies. +| Supports basic authentication queries, +such as LDAP “bind as user” | Support authentication protocols that include CHAP, MS-CHAP, MS-CHAPv2, and 802.1X (EAP, EAP-TLS, PEAP, EAP-TTLS, EAP-MD5). +|=== + + +// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/nac.adoc b/doc/antora/modules/concepts/pages/modules/components/nac.adoc similarity index 100% rename from doc/antora/modules/concepts/pages/nac.adoc rename to doc/antora/modules/concepts/pages/modules/components/nac.adoc diff --git a/doc/antora/modules/concepts/pages/nas.adoc b/doc/antora/modules/concepts/pages/modules/components/nas.adoc similarity index 87% rename from doc/antora/modules/concepts/pages/nas.adoc rename to doc/antora/modules/concepts/pages/modules/components/nas.adoc index 583fd3d063..abc3840d6f 100644 --- a/doc/antora/modules/concepts/pages/nas.adoc +++ b/doc/antora/modules/concepts/pages/modules/components/nas.adoc @@ -1,9 +1,7 @@ = Network Access Server -== Overview - A Network Access Server (NAS) is a system that provides access to -a network. In some cases also known as a Terminal Server or Remote +a network. In some cases, it's also known as a Terminal Server or Remote Access Server (RAS). The NAS is meant to act as a gateway to guard access to a @@ -54,12 +52,10 @@ RADIUS by providing error handling and inter-domain communications which is starting to be implimented in some high end NAS. -== See Also +== More Information -- RFC 2881 (Network Access Server Requirements Next Generation NAS - Model, July 2000) -- RFC 2882 (Network Access Servers Requirements: Extended RADIUS - Practices, July 2000) +- https://datatracker.ietf.org/doc/html/rfc2881[RFC 2881] Network Access Server Requirements Next Generation NAS Model +- https://datatracker.ietf.org/doc/html/rfc2881[RFC 2882] Network Access Servers Requirements: Extended RADIUS Practices // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/modules/components/policy.adoc b/doc/antora/modules/concepts/pages/modules/components/policy.adoc new file mode 100644 index 0000000000..4a0fcd80ea --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/components/policy.adoc @@ -0,0 +1,18 @@ += Server Policies +The RADIUS server processes an NAS request based on the following criteria: + +* Contents of the NAS request. +* Information available locally to the RADUS server (flat files, SQL, LDAP). + +The limitations inherent in the above processing criteria mean that the server can't negotiate with a NAS to request more information. The server takes what the NAS sends and returns either an acknowledgment or a non-acknowledgment. + +The RADIUS server has no control over the content of the request that the NAS sends. When the RADIUS server receives the request from the NAS, it uses local policies to decide how best to respond to the NAS request. The policies may be simple, such as “accept anyone with a correct user name and password”. More complex policies may be “allow basic users to request premium services in +non-premium hours, except for Sundays and holidays, if their payment status is current”. + +In all cases, the policies must be designed, implemented, and deployed by the network administrator. because policies are based on the contents of the NAS requests. Note that the NAS documentation does not always describe the content of the NAS requests. The only way for a network administrator to determine the NAS request content is to set up a test network. + +Test logins will result in the receipt of requests by the server. The administrator can then examine these requests to determine their content and create policies that look for those specific sets of attributes. Once +the policy is created, the server then uses that information to make decisions. +This process becomes more complicated when different NAS elements send the same information in different formats. + +For example, RADIUS has no MAC address data type, which means that the MAC address is sent as ASCII strings. Some NAS elements send a MAC address in the format of “00:01:02:03:04:05”, while others use the format “00-01-02-03-04-05”. The fact that these differences are not documented makes policy creation very difficult.In most cases, the administrator has to resort to trial and error methods to determine how to implement policies. diff --git a/doc/antora/modules/concepts/pages/radius.adoc b/doc/antora/modules/concepts/pages/modules/components/radius.adoc similarity index 96% rename from doc/antora/modules/concepts/pages/radius.adoc rename to doc/antora/modules/concepts/pages/modules/components/radius.adoc index ef15d8c073..62127c2283 100644 --- a/doc/antora/modules/concepts/pages/radius.adoc +++ b/doc/antora/modules/concepts/pages/modules/components/radius.adoc @@ -1,6 +1,6 @@ = RADIUS -RADIUS is a protocol for remote user Authorization, Authentication and Accounting. Its primary use is for Internet Service Providers, though it may as well be used on any network that needs a centralized authentication and/or accounting service for its workstations. +RADIUS is a protocol for remote user Authorisation, Authentication and Accounting. Its primary use is for Internet Service Providers, though it may as well be used on any network that needs a centralized authentication and/or accounting service for its workstations. RADIUS is often used in larger Wi-Fi (wireless) networks for authentication purposes, replacing the simple shared key methods which are uncomfortable if a Wi-Fi network reaches a specific size. diff --git a/doc/antora/modules/concepts/pages/modules/components/radius_servers.adoc b/doc/antora/modules/concepts/pages/modules/components/radius_servers.adoc new file mode 100644 index 0000000000..68fd4ca999 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/components/radius_servers.adoc @@ -0,0 +1,37 @@ += RADIUS Server + +A RADIUS server is a central authority that handles authentication, authorisation, and accounting (AAA) for network access. The server receives requests from network access servers (NASs) like wireless access points or VPN concentrators and determines whether a user should be granted access based on predefined policies and data stored in a datastore. + +The RADIUS server is usually a software application running on a self-contained server. A physical device such as RADIUS appliances, with simplified maintenance and management interfaces, are also used. In either scenario, the server waits for a request from an NAS, processes or forwards the request, and then returns a response to the NAS. The response can contain authorisation policies or an acknowledgment of accounting data received. + +A single RADIUS server can receive and process many simultaneous access requests from numerous types of NASs (such as ADSL, dial-up, or VPN concentrators) in many different locations. A single server may also +access flat files, SQL databases, LDAP directories, or other RADIUS servers. In order to make a decision regarding an access request, the RADIUS server must first use information from many sources. + +Once the server makes a decision, it returns a response to the NAS. The NAS may enforce the policy in that response, or it may ignore it altogether. The server is not aware if the NAS has received its response, or if the NAS is obeying the instructions in that response. Since it is customary for the NAS to log very little information about what has been received or how server responses are processed, it is very difficult to create and debug local site policies. + +The RADIUS server has no control over what the NAS does with a response. +Consider the following analogy to help illustrate the point: a Human Resources (HR) department acts like a RADIUS server, by setting policies, and a security guard acts like the NAS in a network, by carrying out those HR department policies. + +In this example, the company policy is that when an employee is fired, HR notifies security and removes building access from that employee. The security guard is then responsible for ensuring the fired employee no longer accesses the company building. If one day an employee gets fired (similar to a user +being denied access) and the HR department informs the security guard that the employee is no longer free to come and go (similar to the RADIUS server decision sent to the NAS), it is then up to the security guard at the company front desk to perform the task of refusing entry to the fired employee (similar to the NAS enforcing system access in a network). In the network, the NAS enforces system access. The RADIUS server does little more than offer advice to the NAS. + +[#policy] +== RADIUS Server Policies + +The RADIUS server processes an NAS request based on the following criteria: + +* Contents of the NAS request. +* Information available locally to the RADUS server (flat files, SQL, LDAP). + +This processing criteria limits the server ability to perform more complex authentication scenarios. The server can't negotiate with a NAS to request more information. The server uses the initial information that the NAS sends and returns either an acknowledgment or a non-acknowledgment. + +The RADIUS server has no control over the content of the request that the NAS sends. When the RADIUS server receives the request from the NAS, it uses local policies to decide how best to respond to the NAS request. The policies may be simple, such as “accept anyone with a correct user name and password”. More complex policies may be “allow basic users to request premium services in +non-premium hours, except for Sundays and holidays, if their payment status is current”. + +In all cases, the policies must be designed, implemented, and deployed by the network administrator because policies are based on the contents of the NAS requests. Often, the NAS documentation doesn't describe the content of the NAS requests. The only way for a network administrator to determine the NAS request content is to set up a test network. + +Test logins will result in the receipt of requests by the server. The administrator can examine these requests to determine their content and create policies that look for those specific sets of attributes. Once +the policy is created, the server then uses that information to make decisions. +This process becomes more complex when different NAS elements send the same information in different formats. + +For example, RADIUS has no MAC address data type, which means that the MAC address is sent as ASCII strings. Some NAS elements send a MAC address in the format of “00:01:02:03:04:05”, while others use the format “00-01-02-03-04-05”. The fact that these differences are not documented makes policy creation very difficult.In most cases, the administrator has to resort to trial and error methods to determine how to implement policies. diff --git a/doc/antora/modules/concepts/pages/modules/freeradius.adoc b/doc/antora/modules/concepts/pages/modules/freeradius.adoc new file mode 100644 index 0000000000..618ed27180 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/freeradius.adoc @@ -0,0 +1,43 @@ += What is FreeRADIUS? + +FreeRADIUS is the most popular and the most widely deployed open source RADIUS server in the world. +It serves as the basis for multiple commercial offerings, and it supplies the authentication, authorisation, and accounting (AAA) needs of many Fortune 500 companies and Tier 1 ISPs. It is also widely used by the academic community (i.e., eduroam, the world-wide roaming access service developed for the international research and education community, utilises FreeRADIUS software). + +FreeRADIUS was started in August 1999 by Alan DeKok and Miquel van Smoorenburg. Miquel had previously written the Cistron RADIUS server software, which had been widely adopted when the Livingston server was no longer in service. FreeRADIUS was developed using a modular design, to encourage more active community involvement. + +== Features + +More authentication types are supported by FreeRADIUS than by any other open source server. For example, FreeRADIUS is the only open source RADIUS server to support Extensible Authentication Protocol (EAP). + +FreeRADIUS is also the only open source RADIUS server to support virtual servers. The use of virtual servers means that complex implementations are simplified. Ongoing support and maintenance costs for network administrators are greatly reduced. FreeRADIUS's ability to support virtual servers +gives it a huge advantage over the competition. + +== Modularity + +The modular design protocol makes FreeRADIUS easy to understand. The modular interface also simplifies adding or removing modules. If a feature is not needed for a configuration, the module is removed with a simple edit of the configuration file. Once the module is removed, it does not affect server performance, memory use, or security. This flexibility enables the server to run on platforms ranging from embedded systems to multi-core machines with gigabytes of RAM. + +The server core does the basic RADIUS and network handling. Almost everyother feature is managed with a module. This modular design increases the flexibility of the policy language. The policy language can execute multiple modules in any order, allowing for highly customizable workflows. Each module handles a specific, isolated task such as authentication, logging, or database access. + +For example, each of the authentication methods (PAP,CHAP, MS-CHAP, TOTP, and EAP) are individual modules. Similarly, each database connector (SQL,Redis, LDAP, etc.) are individual modules. In many cases, no code changes to the server core have to be made in order to support complex new functionality. + +This modular design streamlines development, testing, and enhances the system’s adaptability to new requirements or technologies. + +== Scalability + +A single FreeRADIUS server is easily reconfigured to handle a wide range of workloads, from just a few requests per second to thousands—by adjusting a few default settings. This adaptability makes FreeRADIUS suitable for both small deployments and very large organisations, including those with over 10 million customers who rely on it for authentication, authorization, and accounting (AAA) services. + +A single FreeRADIUS server can transition from handling one request every few seconds to processing thousands of requests per second. These varied workloads are handled by changing a few default settings. FreeRADIUS is suitable for both small deployments and very large organisations, including those with over 10 million customers. Often, only a single FreeRADIUS server is required to fulfill an organisation's requirements for their AAA services. + +While many commercial severs offer different versions of their software to handle different needs, only the latest version of FreeRADIUS provides better performance, more realms, more RADIUS clients, and more features, with no need to purchase additional product licenses. + +== Features + +* Complete support for https://datatracker.ietf.org/doc/html/rfc2865[RFC 2865] and https://datatracker.ietf.org/doc/html/rfc2866[RFC 2866] attributes. +* Authentication Protocol supports for: +** EAP or protocol/EAP with EAP-MD5, EAP-SIM, EAP-TLS, EAP-TTLS. +** EAP-PEAP or protocol/EAP-PEAP. +** Cisco LEAP or protocol/LEAP and EAP sub-types. +* Vendor Specific Attributes for over a hundred vendors including BinTec, Foundry, Cisco, Juniper, Lucent/Ascend, HP ProCurve, Microsoft, USR/3Com. +* All known RADIUS clients. +* Flexible configurations using attribute pairs. +* Supports virtual servers. diff --git a/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc b/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc index 26e71bb179..b20d90c5a0 100644 --- a/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc +++ b/doc/antora/modules/concepts/pages/modules/ldap/authentication.adoc @@ -1,16 +1,10 @@ -== Authenticating Users with LDAP += Authentication 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. +The FreeRADIUS is an AAA server, and LDAP servers function primarily as a *database* that stores user credentials and related information. FreeRADIUS handles the authentication protocols such as `PAP`, `CHAP`, or `MS-CHAP`. LDAP is a backend accessed by the RADIUS server to verify user credentials. The xref:reference:raddb/mods-available/ldap.adoc[ldap module] interacts with these protocols by retrieving and comparing data. The FreeRADIUS server performs the authentication logic, not the LDAP server. -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. +This separation of roles means that FreeRADIUS supports multiple kinds of authentication protocols whereas a LDAP database works only the authentication method "bind as user". This authentication method is compatible only with PAP. + +Our recommendation is to use LDAP as a database. FreeRADIUS reads the "known good" password from LDAP, and then use that information to authenticate the user. It's not recommended 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" @@ -18,13 +12,13 @@ password to FreeRADIUS over a standard LDAP query. Therefore when Active Directory is used, the choices are: PAP:: -Use "bind as user" +Use "bind as user". MS-CHAP:: Use xref:reference:raddb/mods-available/ntlm_auth.adoc[`ntlm`] or xref:reference:raddb/mods-available/winbind.adoc[`winbind`]. -Due to the limitations of Active Directory, There are unfortunately no -other possible choices. +Due to these limitations of Active Directory, there are no +other alternatives. == LDAP Security Recommendations @@ -32,26 +26,25 @@ 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 +* Create a dedicated account for use by FreeRADIUS. -* Ensure that this account does not have administrator access +* Ensure that this account does not have administrator access. -* Ensure that this account is read-only, and has no write permissions +* Ensure that this account is read-only, and has no write permissions. -* Start by using 'simple authentication' instead of +* 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. + 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 + 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 + 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 +== Authentication Method Compatibility The LDAP module is compatible a few different kinds of authentication methods. Note that we say _compatible_, and not _supports_. LDAP @@ -59,13 +52,13 @@ 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) +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) +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 successful, @@ -84,7 +77,7 @@ 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 +All of these authentication methods except "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 @@ -93,114 +86,16 @@ 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 +The best method to test authentication is with the xref:howto:modules/ldap/ldapsearch/index.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 +We 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:reference: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:reference: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` calculations 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/ - // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/modules/ldap_authentication.adoc b/doc/antora/modules/concepts/pages/modules/ldap/ldap_authentication.adoc similarity index 91% rename from doc/antora/modules/concepts/pages/modules/ldap_authentication.adoc rename to doc/antora/modules/concepts/pages/modules/ldap/ldap_authentication.adoc index ac82b4971e..ea35941b05 100644 --- a/doc/antora/modules/concepts/pages/modules/ldap_authentication.adoc +++ b/doc/antora/modules/concepts/pages/modules/ldap/ldap_authentication.adoc @@ -1,4 +1,8 @@ -= Authenticating Users with LDAP += Authentication with LDAP + +LDAP servers function primarily as databases that store user credentials and related information. They do not implement or handle authentication protocols themselves. + +The RADIUS server handles the authentication protocols such as `PAP`, `CHAP`, or `MS-CHAP`. The LDAP server is a backend accessed by the RADIUS server to verify user credentials. The LDAP module interacts with these protocols by retrieving and comparing data. The RADIUS server performs the authentication logic, not the LDAP server. The LDAP module is compatible a few different kinds of authentication methods. Note that we say _compatible_, and not _supports_. LDAP @@ -45,7 +49,7 @@ 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 +We 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. diff --git a/doc/antora/modules/concepts/pages/modules/ldap/novell.adoc b/doc/antora/modules/concepts/pages/modules/ldap/novell.adoc new file mode 100644 index 0000000000..81d8edd319 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/ldap/novell.adoc @@ -0,0 +1,15 @@ += Integrate Novell eDirectory + +You can integrate Novell eDirectoryTM 8.7.1 or later with FreeRADIUS 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]. diff --git a/doc/antora/modules/concepts/pages/modules/ldap/password_storage.adoc b/doc/antora/modules/concepts/pages/modules/ldap/password_storage.adoc new file mode 100644 index 0000000000..ceea97f18e --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/ldap/password_storage.adoc @@ -0,0 +1,82 @@ += 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 understands and parses 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:reference: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:reference: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` calculations 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. diff --git a/doc/antora/modules/concepts/pages/authproto.adoc b/doc/antora/modules/concepts/pages/modules/protocol/authproto.adoc similarity index 60% rename from doc/antora/modules/concepts/pages/authproto.adoc rename to doc/antora/modules/concepts/pages/modules/protocol/authproto.adoc index eab6227add..762e0f754e 100644 --- a/doc/antora/modules/concepts/pages/authproto.adoc +++ b/doc/antora/modules/concepts/pages/modules/protocol/authproto.adoc @@ -2,15 +2,15 @@ == RADIUS Protocol -RADIUS is a protocol for remote user Authorization, Authentication, and Accounting. Its primary use is for Internet Service Providers, though it may as well be used on any network that needs a centralized authentication and/or accounting service for its workstations. +RADIUS is a protocol for remote user Authorisation, Authentication, and Accounting. It's very important for Internet Service Providers, and any network that needs a centralized authentication and/or accounting services for its infrastructure. RADIUS is often used in larger Wi-Fi (wireless) networks for authentication purposes, replacing the simple shared key methods which are uncomfortable if a Wi-Fi network reaches a specific size. The protocol originally was designed by the well known terminal server manufacturer Livingston for use with their Portmaster series of terminal servers. Since then it has been implemented by hundreds other vendors and has a become an Internet Standard RFC. The DIAMETER protocol is the designated successor, but RADIUS is still commonly used today. -=== Radius Protocol dependencies +=== RADIUS Protocol Dependencies -UDP: RADIUS uses UDP as its underlying protocol. The registered UDP port for RADIUS traffic is 1812; the early deployment of RADIUS used UDP port 1645, which conflicted with the "datametrics" service. When RADIUS is used for accounting rather than authentication and configuration, the registered UDP port is 1813; the early deployment used port 1646, which conflicted with the "sa-msg-port" service. +RADIUS uses UDP as its underlying protocol. The registered UDP port for RADIUS traffic is 1812 for authentication and configuration. The early deployment of RADIUS used UDP port 1645, which conflicted with the "datametrics" service. When RADIUS is used for accounting the registered UDP port is 1813. The earlier RADIUS version used port 1646, which conflicted with the "sa-msg-port" service. == Authentication Protocols @@ -25,100 +25,102 @@ Authentication protocols used in RADIUS are not always compatible with the way t === Authentication Protocol and Password Compatibility -Passwords may be stored in a DB in many forms. Clear-text, MD5 hashed, crypt'd, NT hash, or other methods are all commonly used. Authentication protocols used in RADIUS are not always compatible with the way the passwords have been stored. The following table shows which protocol is compatible with what kind of password. +Passwords may be stored in a datastore in many forms. Clear-text, MD5 hashed, crypt'd, NT hash, or other methods are all commonly used. Authentication protocols used in RADIUS are not always compatible with the way the passwords have been stored. The following table shows which protocol is compatible with what kind of password. +[#Proto-Password-Compat] +.Protocol Password Compatibility [cols="2,1,1,1,1,1,1,1"] |=== -|Protocol|Clear-text|NT hash|MD5 hash|Salted MD5 hash|SHA1 hash|Salted SHA1 hash|Unix Crypt -|PAP -|√ -|√ -|√ -|√ -|√ -|√ -|√ - -|CHAP -|√ -|x -|x -|x -|x -|x -|x - -|Digest -|√ -|x -|x -|x -|x -|x -|x - -|MSCHAP -|√ -|√ -|x -|x -|x -|x -|x - -|PEAP -|√ -|√ -|x -|x -|x -|x -|x - -|EA-MSCHAP2 -|√ -|√ -|x -|x -|x -|x -|x - -|Cisco-LEAP -|√ -|√ -|x -|x -|x -|x -|x - -|EAP-GTC -|√ -|√ -|√ -|√ -|√ -|√ -|√ - -|EAP-MD5 -|√ -|x -|x -|x -|x -|x -|x - -| EAP-MD5 -|√ -|x -|x -|x -|x -|x -|x +|*Protocol*|*Clear-text*|*NT hash*|*MD5 hash*|*Salted MD5 hash*|*SHA1 hash*|*Salted SHA1 hash*|*Unix Crypt* +|*PAP* +| ✔️ +| ✔️ +| ✔️ +| ✔️ +| ✔️ +| ✔️ +| ✔️ + +|*CHAP* +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ + +|*Digest* +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ + +|*MSCHAP* +| ✔️ +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ + +|*PEAP* +| ✔️ +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ + +|*EA-MSCHAP2* +| ✔️ +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ + +|*Cisco-LEAP* +| ✔️ +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ + +|*EAP-GTC* +| ✔️ +| ✔️ +| ✔️ +| ✔️ +| ✔️ +| ✔️ +| ✔️ + +|*EAP-MD5* +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ +| ❌ + +|*EAP-PWD* +| ✔️ +| ❌ +| ❌ +| ❌ +| ❌ +| ✔️ +| ✔️ |=== diff --git a/doc/antora/modules/concepts/peap.adoc b/doc/antora/modules/concepts/pages/modules/protocol/peap.adoc similarity index 100% rename from doc/antora/modules/concepts/peap.adoc rename to doc/antora/modules/concepts/pages/modules/protocol/peap.adoc diff --git a/doc/antora/modules/concepts/pages/wep.adoc b/doc/antora/modules/concepts/pages/modules/protocol/wep.adoc similarity index 100% rename from doc/antora/modules/concepts/pages/wep.adoc rename to doc/antora/modules/concepts/pages/modules/protocol/wep.adoc diff --git a/doc/antora/modules/concepts/pages/wpa.adoc b/doc/antora/modules/concepts/pages/modules/protocol/wpa.adoc similarity index 99% rename from doc/antora/modules/concepts/pages/wpa.adoc rename to doc/antora/modules/concepts/pages/modules/protocol/wpa.adoc index 5d57fa1718..078acb1965 100644 --- a/doc/antora/modules/concepts/pages/wpa.adoc +++ b/doc/antora/modules/concepts/pages/modules/protocol/wpa.adoc @@ -29,7 +29,7 @@ Pre-shared key mode (PSK, also known as *personal* mode) is designed for home an Security is strengthened by employing a PBKDF2 key derivation function. However, the weak passphrases users typically employ are vulnerable to password cracking attack. Password cracking can be defeated by using a passphrase of at least 5 Diceware words or 14 completely random letters with WPA and WPA2. For maximum strength, 8 Diceware words or 22 random characters should be employed. Passphrases should be changed at regular intervals, or whenever an individual with access is no longer authorized to use the network or when a device configured to use the network is lost or compromised. -Some consumer chip manufacturers have attempted to bypass weak passphrase choice by adding a method of automatically generating and distributing strong keys through a software or hardware interface that uses an external method of adding a new Wi-Fi adapter or appliance to a network. These methods include pushing a button (Broadcom and Buffalo AirStation One-Touch Secure System]) and entering a short challenge phrase through software (Atheros). The Wi-Fi Alliance is currently working on standardization of this approach as part of its Simple Configuration effort. +Some consumer chip manufacturers have attempted to bypass weak passphrase choice by adding a method of automatically generating and distributing strong keys through a software or hardware interface that uses an external method of adding a new Wi-Fi adapter or appliance to a network. These methods include pushing a button (Broadcom and Buffalo AirStation One-Touch Secure System]) and entering a short challenge phrase through software (Atheros). The Wi-Fi Alliance is currently working on standardisation of this approach as part of its Simple Configuration effort. == EAP types under WPA- and WPA2- Enterprise diff --git a/doc/antora/modules/concepts/pages/modules/session/processing.adoc b/doc/antora/modules/concepts/pages/modules/session/processing.adoc new file mode 100644 index 0000000000..0ee2996394 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/session/processing.adoc @@ -0,0 +1,126 @@ += Processing + +The server processes requests through local site policy. That policy is used to examine the request, the request attributes, and the attribute values. The server then builds a reply message using responses (determined by local policy) such as time of day restrictions, group access limitations, and IP address +allocation. The processing stage may include keeping track of <>. + +== How things work in RADIUS + +The client sends the server a RADIUS authentication request. You don't decide what's in the request, the client does. The server doesn't decide what's in the request, the client does. The client is 100% responsible for everything in the request. + + +.FreeRADIUS v4 Request Flow +image:request_flow_4.0.svg[Process Flow railroad diagram]. + +=== Summary of the Request Flow Steps + +. An end-user tries to access a network through a RADIUS client such as a wireless access point.  +. The RADIUS client sends a request to the RADIUS server along with the user's credentials. +. The RADIUS server verifies the user's credentials against its datastore (flat file, SQL, LDAP, etc.).  +. If authentication passes, the server returns configuration details (including authorisation) to the client. The client can now grant network access to the end-user  +. If the authentication fails, the server denies access, and the RADIUS client informs the end-user. + + +Users new to RADIUS, AAA, or EAP are encouraged to read the standards listed below. This documentation provides you with a solid foundation in RADIUS concepts and EAP at a protocol level. + +- https://datatracker.ietf.org/doc/html/rfc2865[RFC 2865] - Remote Authentication Dial In User Service (RADIUS) +- https://datatracker.ietf.org/doc/html/rfc2866[RFC 2866] - RADIUS Accounting + +- https://datatracker.ietf.org/doc/html/rfc3748[RFC 3748] - Extensible Authentication Protocol (EAP) +- https://datatracker.ietf.org/doc/html/rfc2865[RFC 3579] - RADIUS Support For Extensible Authentication Protocol (EAP) + + +== Request Processing + +When the server processes requests, it manages four xref:reference:unlang/list.adoc[attribute lists]. All of these lists are available to all modules. All of these lists are available in xref:reference:unlang/index.adoc[Unlang] + +.Attribute Lists and Details + +[cols="1,2"] +|=== +|*Attribute List*|*Description* + +|`request` +|Attributes taken from the received packet. + +|`reply` +|Attributes which will be sent in the reply. + +|`control` +|Attributes used to control how the server operates. These are never sent in a packet. + +|`session-state` +|Attributes which are saved and restored across multiple request / reply exchanges. +|=== + + + +== Select an Auth-Type - authorise {} + +The RADIUS server looks at the request and says: + +> Hmmm... can I deal with this request? + +The answer to that depends on what authentication types are enabled in the server, what the server can look up in a datastore, and what is in the request. + +The server starts querying the modules in the authorise section: + +> Unix module, can you handle this one? + +> Pap module, can you handle this one? + +> Mschap module, can you handle this one? + +At some point, one of the modules will say: + +> Yes, I see something in the request I recognize. I can do something! + +The module does this by looking for key attributes in the received request, such as MS-CHAP-Challenge (for mschap), or CHAP-Challenge (for chap), or EAP-Message (for eap). Or it may just assume it needs to add something to every request. + +If the module thinks has a possibility of authenticating the user, it'll say: + +> I can't authenticate this user now (I was just told to authorise them i.e. set the Auth-Type), +> but my pal in the Authenticate section can! +> Hey, set the Auth-Type to me! + +TThe module performs no action if it doesn't recognize anything in the request. If the module knows it doesn't need to do lookups, the module also does nothing. + +== Authenticate a user - authenticate {} + +At the end of the authorise process, the server checks if the Auth-Type has been set by a module. + +If no module sets the Auth-Type, the server immediately rejects the request. + +For example, the client sends a request with a User-Password attribute, and pap is enabled. The pap module then sets the ``Auth-Type = pap``. + +During this authenticate process, the server calls the pap module again: + +> I see a User-Password, which is what the user entered. +> That's nice, but I need to compare it with something. +> Ah! Another module added the "known good" password for this user in authorise! + +Next, the server compares the local "known good" password to the password as entered by the user. This is how authentication works. + +The "known good" password comes from another module. The pap module just does PAP authentication, and nothing more. The benefit of this approach is that the "known good" password can come from the 'users' file, SQL, LDAP, ``/etc/passwd``, or any external program. + +For this example, the ldap module is listed in the authorise section. It will have run and checked: + +> Hmm... Can I find a "known good" password for this user? + +If so, it will have added the "known good" password to the request, so that another module in authenticate can use it. + +== Insufficient information + +But WAIT! What if the client sends a MSCHAP request? What does the RADIUS server say then? + +> Well, this difficult and not the same as previous request +> That client has made this difficult. I'm limited by some constraints! + +In this case, the mschap module looks at the request, and finds the MS-CHAP attributes. It sets the *Auth-Type* to itself (mschap). A database module (such as LDAP, above) gets the "known good" password, and adds it to the request. The mschap module is then run for authentication. It looks for either a clear text password or nt-hash. See an explanation for this limitation is explained in the xref:modules/protocol/authproto.adoc#Proto-Password-Compat[Protocol Password Compatibilty] table. If one of those hasn't been added by a database, the mschap module says: + +> Sorry, I can't authenticate the user, +> because I don't have the information I need to validate MSCHAP. + +But now the server has run out of options! Its only choice was mschap because that's what the client sent in the request. The mschap module can't do anything because you didn't give it a useful "known good" password . So the server has no choice but to reject the request. The MSCHAP data might be correct, but the server has no way to know that. So it replies with a reject. + +// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. +// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/modules/session/radius_session.adoc b/doc/antora/modules/concepts/pages/modules/session/radius_session.adoc new file mode 100644 index 0000000000..6fc031f2ba --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/session/radius_session.adoc @@ -0,0 +1,39 @@ += RADIUS Sessions + +A RADIUS session consists of the following steps: + +. A remote user connects to a RADIUS client device (using Point-to-Point Protocol (PPP, 802.1X) or another Data Layer link protocol) and initiates a login: + +* The NAS initiates all conversations (Authentication Sessions) in RADIUS. +* All information sent to the server is done solely at the discretion of the client. +* The RADIUS server does not control what the NAS sends. + +. The Network Access Server communicates with the RADIUS server using a shared secret mechanism: + +* RADIUS uses User Datagram Protocol (UDP) port 1812 for authentication and 1813 for accounting. + +. The NAS sends a RADIUS message (called an Access-Request) to the server. + +* This message contains information about the user, including user name, authentication credentials, and requested service. +* In addition, the message may contain information about the NAS, such as its host name, MAC address, or wireless SSID. +* The message is sent using the Password Authentication Protocol (PAP), Challenge-Handshake Authentication Protocol (CHAP), or Extensible Authentication Protocol (EAP). +* The server must decide whether to authenticate or authorise a user based solely on the information contained within the NAS request, as it does not have access to any additional user information. +* If the NAS sends a packet with an authentication protocol that the server does not support, the server will reject that request. + +. The RADIUS server processes the request and verifies the login request against either a local data- base or the authentication service running on the network. + +* Authentication services can include: LDAP servers for a domain validation; Active Directory servers on Windows networks; Kerberos servers; SQL Server or another type of database for getting information from a database + +. The RADIUS server sends validation results back to the NAS in one of the following forms: Access Reject, Access Challenge, or Access Accept. + +* Access Reject locks the user out of the network if the user is invalid or not authorized, denying them access to the requested resource. +* Access Challenge occurs when the server requires additional information from the user. Since RADIUS packages are limited in size, Access Challenges allow the exchange of larger amounts of data. +* Access Accept provides the user access to the resource and contains policy information which the NAS uses to provide services to, and enforce the behavior of the user. An Access Accept condition does not apply to all resources. Each additional resource is checked as required. The RADIUS client also verifies the original access offered on a periodic basis. +* An Access Accept response results in the NAS providing the following services to the remote client: supplys a static or dynamic IP address; assigning a Time-to-Live for the session; downloading and applying the users’ Access Control List (ACL); setting up any L2TP , VLAN, and QoS session parameters required + +. Once the session is established on the RADIUS client, the accounting process is initiated: + +* The Accounting-Request (start) message, sent by the NAS to the server, indicates the commencement of the session. The the session account record is then created. * The Accounting-Request account record is then closed. +(stop) message indicates the end of the session; the session +* The data stored in the database during the accounting sessions is used to generate billable information and reports. +* Accounting information retained in the database includes the following: time of session, number of packets and amount of data transferred, user and machine identification, network address, and point of attachment information. diff --git a/doc/antora/modules/concepts/pages/modules/session/radius_session_msg.adoc b/doc/antora/modules/concepts/pages/modules/session/radius_session_msg.adoc new file mode 100644 index 0000000000..839a2faab6 --- /dev/null +++ b/doc/antora/modules/concepts/pages/modules/session/radius_session_msg.adoc @@ -0,0 +1,127 @@ += Messages + +A RADIUS session message consists of a single User Datagram Protocol (UDP) packet, containing a short header followed by the authentication, authorisation, or accounting data. + +== Message Attributes + +Each message contains a list of Attribute Value Pairs (AVPs), commonly referred to as attributes. These attributes carry information from the NAS to the server or virtual proxy server and from the server to the NAS. Common attributes include items such as user name, password, IP address, and NAS address; each +attribute contains only one of these items. An attribute can also contain sub-attributes, for grouping purposes. + +For a complete list of standardized attributes, see the http://freeradius.org/rfc/attributes.html[FreeRADIUS RFC Attributes] for more details. +Each client and server supports only a limited set of attributes. In some cases, attributes may not be supported because the server or NAS software may have been written before a standard was published, or the software may not support that particular functionality. + +Consult the software vendor documentation to determine what attributes are supported. If the documentation doesn't contain this information, the select attributes are probably not supported. Contact the vendor for additional information. + +In addition to standardized attributes, vendors can extend RADIUS with vendor-specific attributes (VSAs). Using VSAs means that the vendor can rapidly add functionality without having to do a time-consuming standardisation process. +In order to be useful in the RADIUS client protocol, however, VSAs must be defined on the RADIUS server. Because VSAs are non-standardized attributes, it is difficult to discover any information about them. In addition, they are all vendor-specific (only work on that vendor’s products). Thus, defining VSAs for +RADIUS server use may be difficult. + +== Attribute Types + +Basic RADIUS attribute types are defined in http://tools.ietf.org/html/rfc2865[RFC 2865]. Since the original implementation and standardisation, additional attribute types have been also defined. + +.RADIUS Attribute Types +[options="headers, autowidth"] +|=== +| *Type* | *Format* | *Description* +| integer | Value between 0 - 4294967295 | Unsigned 32-bit integer. +| ipaddr | x.x.x.x | IPv4 address +| date | 10 digit epoch time (xxxxxxxxxx)| Unix timestamp in seconds since January 1, 1970 GMT. +| string | Variable-length string field | Used by FreeRADIUS for printable text strings. +| octet | Variable-length string field | Used by FreeRADIUS for binary data. +| ifid | x.x.x.x.x.x.x.x | IPv6 interface ID (host portion). +| ipv6addr | x.x.x.x.x.x.x.x | IPv6 address. +| ipv6prefix | Value between 0 - 128 | IPv6prefix. +| byte | Single-byte integer | Supported in FreeRADIUS > v2. +Value between 0 - 255. +| short | Two-byte integer | Supported in FreeRADIUS > v3. +Values between 0 - 65535, integer64, 8-byte integer. +|=== + +See xref:reference:type/index.adoc[data types of attributes] for a more details. + +== xref:reference:dictionary/index.adoc[Attribute Definition Dictionaries] + +FreeRADIUS contains over 100 dictionaries, which hold nearly 5000 attribute definitions. + +Unlike text-based protocols such as SMTP or HTTP, RADIUS is a binary protocol; therefore, although attributes are commonly referred to by name (for example, “User-Name”), these names have no meaning in the protocol. Data (i.e., “User-Name”) are encoded in a message as a binary header with binary data, and not as text strings. + +Dictionary files are used to map between the names used by people and the binary data in the RADIUS packets. + +The packets sent by the NAS contain attributes that have a number, a length, and binary data. By contrast, a dictionary file consists of a list of entries with name, number, and data type. + +The server uses the dictionaries to interpret the binary data as follows: the server searches the dictionaries to match the number from the packet, and the corresponding data type in the dictionary entry is then used by the server to interpret the binary data in the packet. The name within the dictionary entry appears in all logs and debug messages, in order to present the attribute in a form that is understandable to people. + +This process also works in reverse: the server uses the dictionaries to encode a string (i.e., “User-Name = Bob”) as “number, length, binary data” in a packet. + +For example, a server may receive a packet that contains the number 1 and some binary data. The server would not be able to decode these attributes without knowing if the binary data were in the form of a string, an IP address, or an integer. The corresponding dictionary entry may state: the number ‘1’ is called +‘User-Name’ and it is in the form ‘string’. This information (i.e., form = ‘string’), contained in the dictionary entry, allows the server to successfully decode the packet. + +Adding new attributes to RADIUS software is made simpler through the use of dictionaries, as they allow the administrator to create new mappings without upgrading the software. + +Vendors can define new attributes in the dictionary without changing any of the server or client source code. These new attributes can then be incorporated in policy decisions or logged in an accounting record.Vendors can also define new functionality for their equipment by publishing a new dictionary file. +Server support for an NAS can easily be added by writing the correct dictionary file for that NAS. + +There is no direct connection between the NAS and the dictionary files, as the dictionary files reside only on the server. For example, if names are edited in a local dictionary file, there is no effect on any other NAS or RADIUS server, because these names appear only in the local dictionary file. The RADIUS packets remain in binary format and contain only numbers, not names. + +[NOTE] +==== +Editing attribute names in a local dictionary file does not effect any other NAS or RADIUS server. Only the attribute numbers are encoded and sent in RADIUS packets. + +The NAS and server may use different dictionaries, which may cause problems if they are not coordinated (a set of data may be interpreted differently by the NAS and the server, i.e., as a string by the NAS and an IP address by the server) +==== + +Since the attribute names are not sent in RADIUS packets, the dictionaries are limited to the local server and to the policy implemented by that server. +In this respect, NAS implementations are much simpler than server implementations. Each NAS “looks” in the RADIUS packet for what it “understands” and ignores everything else. In contrast, each RADIUS server +is presented with all of the information from every NAS in the RADIUS deployment. Each RADIUS server must be capable of “understanding” the functionality and configure-ability of every attribute that is +necessary to authenticate or authorise the users. + +== Dictionary File Format + +It is very important to use the correct dictionaries. If the wrong dictionaries are used, the server may not properly interpret local configuration, or generate the correct response for the NAS. + +If the server does not have access to the correct vendor-specific attributes and dictionaries, it cannot correctly process any VSAs it receives for that vendor. + +[NOTE] +==== +Servers must have access to a vendor dictionary to understand vendor attributes. +==== + +Some servers may not contain all the necessary dictionary files because each vendor defines their own dictionaries and release schedule. If a server does not include dictionaries for a particular vendor, contact that vendor, and not the organisation that supplied the RADIUS server. + +[#server-attr] +=== Server-side Attributes + +Server-side attributes are attributes that control the server’s behavior. It is frequently necessary to define these server-side attributes, while ensuring that information pertaining to server-side attributes never +gets sent through the network in a RADIUS message. Server-side attributes should not be included in RADIUS messages, since these attributes are internal to server implementation. + +Definitions for server-side attributes may vary by server vendor, or may vary even from one version of the same server to another. Only FreeRADIUS definitions for internal attributes are referenced in this document. Those definitions are generally the same across all versions of the server, but other vendors may have different implementations. + +Information such as “use LDAP server X”, or “remember that the user is in group Y” should be used to create local policy. This information should be stored in server-side attributes (also known as “non-protocol attributes”). + +Server-side attributes are presented using the same format as standard or vendor RADIUS attributes. This format gives the administrator the same control over internal aspects of the server behavior as over the server external responses. The server-side attribute information can be retrieved as part of one policy and checked later as part of another policy. For example, the policy can say “use LDAP server X for this request” and “respond with attribute X, value Y”. + +=== xref:modules/session/processing.adoc[Processing Requests] + +The server processes requests through local site policy. That policy is used to examine the request, the request attributes, and the attribute values. The server then builds a reply message using responses (determined by local policy) such as time of day restrictions, group access limitations, and IP address allocation. The processing stage may include keeping track of <>. FreeRADIUS maintains these attribute lists for every request. + +.Attribute Lists and Details + +[cols="1,2"] +|=== +|*Attribute List*|*Description* + +|`request` +|Attributes taken from the received packet. + +|`reply` +|Attributes which will be sent in the reply. + +|`control` +|Attributes used to control how the server operates. These are never sent in a packet. + +|`session-state` +|Attributes which are saved and restored across multiple request / reply exchanges. +|=== + +See the xref:reference:unlang/list.adoc[Attribute Lists] reference documentation for more details. diff --git a/doc/antora/modules/concepts/pages/overview.adoc b/doc/antora/modules/concepts/pages/overview.adoc index 5d19c1cce5..7b11a55fc1 100644 --- a/doc/antora/modules/concepts/pages/overview.adoc +++ b/doc/antora/modules/concepts/pages/overview.adoc @@ -1,97 +1,75 @@ = Overview -The server is written in a “plug in” model. The server core does the basic RADIUS and network handling. Almost everything else is managed as a plug-in module. This design is what enables the policy language to be incredibly exible. The policy language can simply run one or more plug-in modules, in any -order. Each plug-in module can be responsible for onelogical unit of functionality. -For example, each of the authentication methods (PAP,CHAP, MS-CHAP, TOTP, and EAP) are individual plug-in modules. Similarly, each database connector (SQL,Redis, LDAP, etc.) are individual plug-in modules. In many cases, no code changes to the server core have to be made in order to support complex new functionality. +A RADIUS (Remote Authentication Dial In User Service) server offers authentication, authorisation, and accounting (AAA) services for network access. A Network Access Servers (NAS) sends authentication and accounting requests to a RADIUS server. The server then verifies user credentials and returns configuration details to the NAS. The NAS either grants or denies network access to the end-user or device. + +The key concepts of any RADIUS include: + +* *Centralized AAA*: RADIUS servers manage network access by verifying user credentials, granting access rights, and tracking user activity.  + +* *Client-Server Protocol*: RADIUS uses a client-server protocol. Network Access Servers are RADIUS clients that send requests to the RADIUS server.  + +* *Background Process*: RADIUS servers run as background processes or daemons on UNIX systems.  + +* *User Credentials:* The server stores or can access user account information and verifies authentication requests.  + +* *Configuration Details*: The RADIUS server sends details to the client, enabling it to grant or deny network access.  == What is RADIUS? -RADIUS, which stands for “Remote Authentication Dial In User Service”, is a network protocol that defines rules and conventions for communication between network devices for remote user authentication and accounting. Commonly used by Internet Service Providers (ISPs), cellular network +RADIUS is a network protocol that defines rules and conventions for communication between network devices for remote user authentication and accounting. Commonly used by Internet Service Providers (ISPs), cellular network providers, and corporate and educational networks, the RADIUS protocol serves three primary functions: * Authenticates users or devices before allowing them access to a network. -* Authorizes those users or devices for specific network services. +* Authorises those users or devices for specific network services. * Accounts for and tracks the usage of those services. === History In 1991, Merit Network, a non-profit internet provider, required a creative way to manage dial-in access to various Points-Of-Presence (POPs) across its network. In response to this need, RADIUS was created by Livingston Enterprises. -At the time RADIUS was created, network access systems were distributed across a wide area and were run by multiple independent organizations. Central administrators wanted to prevent problems with security and scalability, and thus did not want to distribute user names and passwords; instead, they -wanted the remote access servers to contact a central server to authorize access to the requested system or service. In response to contact from the remote access server, the central server would return a -“success” or “failure” message, and the remote machines would be in charge of enforcing this response for each end user. +When RADIUS was created, network access systems were distributed across a wide area and were run by multiple independent organisations. Central administrators wanted to prevent security and scalability issues, and therefore didn't want to distribute user names and passwords. Instead, they wanted the remote access servers to contact a central server to authorise access to the requested system or service. + +[NOTE] +==== +A remote access server (RAS) is often called a Network Access Server (NAS), Network Access Client (NAC), or simply client. +==== + +In response to contact from the remote access server, the central server would return a “success” or “failure” message, and the remote machines would enforce this response for each end-user. This process ensures that authentication decisions are centralized, while enforcement happens at the network edge, maintaining both security and scalability in the system. -The goal of RADIUS was, therefore, to create a central location for user authentication, wherein users from many locations could request network access. -The simplicity, efficiency, and usability of the RADIUS system led to its widespread adoption by network equipment vendors, to the extent that currently, RADIUS is considered an industry standard and is also positioned to become an Internet Engineering Task Force (IETF) standard. +The goal of RADIUS was to create a central location for user authentication, wherein users from many locations could request network access. +The simplicity, efficiency, and usability of the RADIUS system led to its widespread adoption by network equipment vendors. RADIUS evolved into an industry and Internet Engineering Task Force (IETF) standard as outlined in https://datatracker.ietf.org/doc/html/rfc2865[RFC 2865]. === Customers -A wide and varied array of businesses currently utilize the RADIUS protocol for their authentication and accounting needs. Some examples of RADIUS customers are: +Many types of businesses and organisations use the RADIUS protocol for their authentication and accounting needs. Some examples of RADIUS customers are: * Cellular network providers with millions of users. -* Small WISP start-up providing the local neighborhood with Internet connectivity. -* Enterprise networks implementing Network Access Control (NAC) using 802.1x to ring fence their network. +* Small to large ISPs to authenticate users connecting to the internet. +* Enterprise networks implementing Network Access Control (NAC) using 802.1x or to manage access to their internal networks and VPNs. +* Wireless networks in educational institutions and campuses. === Benefits -The RADIUS client-server architecture provides an open and scalable solution that is broadly supported by a large vendor base. It can be readily modified to meet a variety of situations. Customers can modify RADIUS-based authentication servers to work with a large number of security systems on the market. -RADIUS servers work with any communications device that supports the RADIUS client protocol. In addition, the flexibility of the RADIUS authentication mechanisms allows an organization to maintain any investment they may have made in an existing security technology: customers can modify the -RADIUS server to run with any type of security technology. The flexible authentication mechanisms inherent in the RADIUS server facilitate its integration with existing and legacy systems when required. - -Another advantage of the RADIUS architecture is that any component of a security system that supports the RADIUS protocols can derive authentication and authorization from the central RADIUS server. -Alternatively, the central server can integrate with a separate authentication mechanism. -The utility of the RADIUS protocol extends beyond those systems that utilize network access devices and -terminal servers for network access. RADIUS has been widely accepted by Internet Service Providers (ISPs) -to provide Virtual Private Network (VPN) services. In this context, RADIUS technology allows an organization to use ISP infrastructure for communications securely. - -The distributive nature of RADIUS effectively separates the security processes (carried out on the authentication server) from the communications processes (implemented by the modem pool or the Network -Access Server (NAS)), allowing for a single centralized information store for authorization and authentication information. This centralization can significantly lessen the administrative burden of providing -appropriate access control for a large number of remote users. If ensuring high availability is not a priority, -then redundancy is not required; this centralization can thus be maximized, since all RADIUS-compatible -hardware on a LAN can derive authentication services from a single server. - -In summary, the RADIUS client server protocol contains many technological advantages for customers, including: - -* An open and scalable solution -* Broad support by a large vendor base -* Easy modification -* Separation of security and communication processes -* Adaptable to most security systems -* Workable with any communication device that supports RADIUS client protocol - -== What is FreeRADIUS? - -FreeRADIUS is the most popular and the most widely deployed open source RADIUS server in the world. -It serves as the basis for multiple commercial offerings, and it supplies the authentication, authorization, and accounting (AAA) needs of many Fortune 500 companies and Tier 1 ISPs. It is also widely used by the academic community (i.e., eduroam, the world-wide roaming access service developed for the international research and education community, utilizes FreeRADIUS software). -FreeRADIUS was started in August 1999 by Alan DeKok and Miquel van Smoorenburg. Miquel had previously written the Cistron RADIUS server software, which had been widely adopted when the Livingston server was no longer in service. FreeRADIUS was developed using a modular design, to encourage more active community involvement. - -=== Features - -More authentication types are supported by FreeRADIUS than by any other open source server. For example, FreeRADIUS is the only open source RADIUS server to support Extensible Authentication Protocol (EAP). -FreeRADIUS is also the only open source RADIUS server to support virtual servers. The use of virtual servers means that complex implementations are simplified and ongoing support and maintenance costs for network administrators are greatly reduced; thus, the ability of FreeRADIUS to support virtual servers -gives it a huge advantage over the competition. +The RADIUS client-server architecture is an open and scalable solution. RADIUS supports a wide range of environments and can grow to handle increased demand. Its adoption by many vendors ensures compatibility with a variety of products and systems. Organizations configure RADIUS to work with various security systems, including legacy solutions. Any RADIUS client-protocol-supporting communications device can interact with a RADIUS server, simplifying integration. -=== Modularity +The RADIUS authentication mechanisms enable organizations to integrate their existing security technologies. RADIUS architecture offers authentication and authorisation services to any supported security component. Additionally, the central server can integrate with a separate authentication mechanism. RADIUS extends beyond network access devices and terminal servers. ISPs integrating RADIUS leverage their infrastructure to provide Virtual Private Network (VPN) services. -The modular design protocol makes FreeRADIUS easy to understand. The modular interface also simplifies adding or removing modules. For example, if a feature is not needed for a particular configuration, the module is easily removed. Once the module is removed, it does not affect server performance, -memory use, or security. This flexibility enables the server to run on platforms ranging from embedded systems to multi-core machines with gigabytes of RAM. +The distributive nature of RADIUS separates security processes from the communications processes. This design provides a single centralized information store for authorisation and authentication information. Centralization reduces the administrative burden of providing adequate access control for remote users. -=== Scalability +[NOTE] +==== +The authentication server manages the security processes. The network access server (NAS) handles the communication processes. +==== -A single RADIUS server can easily transition from handling one request every few seconds to handling thousands of requests per second, simply by reconfiguring a few default settings. Many large organizations (those with more than 10 million customers) are dependent on FreeRADIUS for their AAA needs. -Often, only a single FreeRADIUS server is required to fill the needs of these large organizations. -While many commercial severs offer different versions of their software to handle different needs, only the latest version of FreeRADIUS is needed to obtain better performance, more realms, more RADIUS clients, and many other features, with no need to purchase additional product licenses. +If high availability is not a priority, redundancy is not necessary. All RADIUS-compatible hardware on the network can derive authentication services from a single server. -== Features +In summary, the RADIUS client-server protocol provides these advantages: -* Complete support for https://datatracker.ietf.org/doc/html/rfc2865[RFC 2865] and https://datatracker.ietf.org/doc/html/rfc2866[RFC 2866] attributes. -* Authentication Protocol supports for: -** EAP or protocol/EAP with EAP-MD5, EAP-SIM, EAP-TLS, EAP-TTLS. -** EAP-PEAP or protocol/EAP-PEAP. -** Cisco LEAP or protocol/LEAP and EAP sub-types. -* Vendor Specific Attributes for over a hundred vendors including BinTec, Foundry, Cisco, Juniper, Lucent/Ascend, HP ProCurve, Microsoft, USR/3Com, Acc/Newbridge. -* All known RADIUS clients. -* Flexible configurations using attribute pairs. -* Supports virtual servers. +* An open and scalable solution. +* Broad support by a large vendor base. +* Easy modification. +* Separation of security and communication processes. +* Adaptable to most security systems. +* Workable with any communication device that supports RADIUS client protocol. // Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. // This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/processing.adoc b/doc/antora/modules/concepts/pages/processing.adoc deleted file mode 100644 index 754a9b889a..0000000000 --- a/doc/antora/modules/concepts/pages/processing.adoc +++ /dev/null @@ -1,89 +0,0 @@ -= Processing - -image:request_flow.svg[Process Flow railroad diagram]. - -Users new to RADIUS, EAP or AAA in general are encouraged to read the following standards: -- RFC 2865 - Remote Authentication Dial In User Service (RADIUS) -- RFC 2866 - RADIUS Accounting - -and if working with EAP: - -- RFC 3748 - Extensible Authentication Protocol (EAP) -- RFC 3579 - RADIUS (Remote Authentication Dial In User Service) Support For Extensible Authentication Protocol (EAP) - -This should provide a solid foundation in RADIUS and EAP at a protocol level. - -== How things work in RADIUS - -The client sends the server a RADIUS authentication request. You don't decide what's in the request, the client does. The server doesn't decide what's in the request, the client does. The client is 100% responsible for everything in the request. - -== Picking an Auth-Type - authorize {} - -The radius server looks at the request and says: - -> Hmmm... can I deal with this request? - -The answer to that depends on what authentication types you have enabled in the server, what the server can look up in a database, and what is in the request. - -The server will then start querying the modules in the authorize section: - -> Unix module, can you handle this one? - -> Pap module, can you handle this one? - -> Mschap module, can you handle this one? - -At some point, one of the modules will say: - -> Yes, I see something in the request I recognize. I can do something! - -The module does this by looking in the request for key attributes, such as MS-CHAP-Challenge (for mschap), or CHAP-Challenge (for chap), or EAP-Message (for eap). Or it may just assume it needs to add something to every request. - -If the module thinks it has a shot at authenticating the user it'll say: - -> I can't authenticate this user now (I was just told to authorize them), -> but my pal in the Authenticate section can! -> Hey, set the Auth-Type to me! - -If the module doesn't see anything it recognizes, or knows it doesn't need to lookup anything, it does nothing. - -== Authenticating a user - authenticate {} - -At the end of authorize, the server will check if anything set the Auth-Type. - -If nothing did, it immediately rejects the request. - -Lets suppose that the client sends a request with a User-Password attribute, and pap is enabled, the pap module will then have set ``Auth-Type = pap``. - -So in authenticate, the server will call the pap module again: - -> I see a User-Password, which is what the user entered. -> That's nice, but I need to compare it with something. -> Ah! Another module added the "known good" password for this user in authorize! - -So it then compares the local "known good" password to the password as entered by the user. This is how authentication works. - -The "known good" password comes from another module. The pap module just does PAP authentication, and nothing more. The benefit of this approach is that the "known good" password can come from the 'users' file, SQL, LDAP, ``/etc/passwd``, external program, etc. i.e. pretty much anything. - -Lets suppose that the ldap module was listed in authorize. It will have run and checked: - -> Hmm... Can I find a "known good" password for this user? - -If so, it will have added the "known good" password to the request, so that another module in authenticate can use it. - -== Insufficient information - -But WAIT! What if the client sends a MSCHAP request? What does the radius server say then? - -> Well that's a fine kettle of fish! -> That client has really really tied my hands on this one! - -In this case, the mschap module looks at the request, and finds the MS-CHAP attributes. It sets the *Auth-Type* to itself (mschap). A database module (such as LDAP, above) gets the "known good" password, and adds it to the request. The mschap module is then run for authentication. It looks for either a clear text password or nt-hash (why? look at the protocol table(http://deployingradius.com/documents/protocols/compatibility.html)). If one of those hasn't been added by a datastore, the mschap module says: - -> Sorry, I can't authenticate the user, -> because I don't have the information I need to validate MSCHAP. - -But now the server has run out of options! Its only choice was mschap because that's what the client sent in the request. The mschap module can't do anything because you didn't give it a useful "known good" password . So the server has no choice but to reject the request. The MSCHAP data might be correct, but the server has no way to know that. So it replies with a reject. - -// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0. -// This documentation was developed by Network RADIUS SAS. diff --git a/doc/antora/modules/concepts/pages/virtual_servers.adoc b/doc/antora/modules/concepts/pages/virtual_servers.adoc index 2d7c1edf44..d16b4a866b 100644 --- a/doc/antora/modules/concepts/pages/virtual_servers.adoc +++ b/doc/antora/modules/concepts/pages/virtual_servers.adoc @@ -42,18 +42,18 @@ listen { type = auth virtual_server = one } - + listen { ipaddr = 192.0.2.2 port = 1812 type = auth virtual_server = two } - + server one { ... } - + server two { ... } @@ -65,7 +65,7 @@ received on the IP address `192.0.2.2`, they will be processed through the `server two` virtual server. The contents of the `server one` and `server two` sections are -`authorize`, `authenticate`, etc. sections used to process packets in +`authorise`, `authenticate`, etc. sections used to process packets in version 1.x. Client based @@ -84,7 +84,7 @@ listen { # no server section is defined here clients = disambiguate } - + clients disambiguate { client one { ipaddr = 192.0.2.4 -- 2.47.3