2 files changed, 217 insertions, 0 deletions
diff --git a/doc/concepts/aaa.rst b/doc/concepts/aaa.rst
new file mode 100644
index 0000000..5d897c6
--- /dev/null
+++ b/doc/concepts/aaa.rst
@@ -0,0 +1,99 @@
+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 2 steps in processing authentication request coming
+from NAS in FreeRADIUS (plus additional steps to proxy request if we
+use FreeRADIUS as a proxy): authorization and authentication.
+
+
+Authorization
+-------------
+
+Authorization is a process of obtaining information about the user
+from external source (file, database or LDAP), and checking that the
+information in request is enough to authenticate user.  Authorization
+modules deal with data sources, so ldap, sql, files, passwd are
+authorization modules.
+
+The authentication method is decided during the authorization phase,
+along with any reply attributes.  The reason for this behaviour is
+that for example, a user may not be permitted to use a particular
+authentication method.  So during the authorize phase, we can deny
+them the ability to use that kind of authentication.
+
+Authentication
+--------------
+
+Authentication is simply a process of comparing user's credentials in
+request with credentials stored in database.  Authentication usually
+deals with password encryption.  PAP, CHAP, MS-CHAP are authentication
+modules.  Few modules act as both authorization and authentication.
+For example, the MS-CHAP module is normally authentication only, but it
+may be used during authorization to verify that request contains
+MS-CHAP related attribute and only in this case perform MS-CHAP based
+authentication. LDAP is normally an authorization module, but it may
+be used for authentication (In this case FreeRADIUS will authenticate
+user in case he can connect to LDAP server with his account).  SQL is
+only an authorization module, as dial-in users are not normally given
+passwords to access an SQL server.
+
+
+Request Processing
+------------------
+
+During authorization and authentication processes, there are 3 lists
+of RADIUS attributes supported by FreeRADIUS: request items, config
+items and reply items.  (See 'man 5 users' for additional
+information.)  Attributes from the RADIUS authentication request
+packet are included into request items list.  Both authorization and
+authentication modules can add attributes into reply items list. These
+attributes will be added to reply will be sent by RADIUS server to
+NAS.  There is third list, called config items.  It's used for
+internal FreeRADIUS operations, for example to pass some data from
+authorization to authentication module.
+
+Before authorization begins FreeRADIUS creates request items list with
+attributes from request and empty config and reply lists.
+
+An authorization module searches a database with attributes
+(e.g. User-Name) taken from request list as a key, and fetches all
+relevant records.  It retrieves 3 types of attributes: check
+attributes, configure attributes and reply attributes. It compares the
+check attributes with attributes from request items. If none of
+database record for this User-Name matches in check attributes with
+request items authorization will fail. If a matching record is found,
+then the configure attributes will be added to configure items, and
+the reply attributes will be added to reply items list.  The check
+list may be required if we need to authenticate users with same name
+for different services (for example to treat User1 from NAS1 and User1
+from NAS2 as different users).
+
+There should be at list one configure attribute provided by
+authorization module, called Auth-Type (since this attribute is from
+config items list it can't be in request or reply).  This attribute
+decides which module will be used to authenticate the user.  The
+Config items also contains information from database required to
+authenticate user, for example valid user's password or it's hash,
+login restrictions, etc.
+
+A quite common mistake is to place the attributes in the wrong lists,
+for example placing Auth-Type, Password, NT-Password etc in the check
+list, or in the reply list.  When run in debugging mode, the server
+will normally issue 'WARNING' messages saying that the attributes are
+in the wrong list.
+
+If you place Password into check list and user does cleartext
+authentication it may work, because authorization module compares 2
+cleartext passwords.  But if user does some encrypted authentication
+(for example MS-CHAP), then the authorization will fail, because the
+Password in the request items will not match the password in the check
+attributes.  You should place Password attribute obtained from
+database into configure items and also place Auth-Type attribute with
+value of 'MS-CHAP' into same list.  The same goes for NT-Password
+(before calling MS-CHAP Password attribute should be converted to
+NT-Password, it may be achieved by calling mschap module in
+authorization section after module which does actual authorization).
diff --git a/doc/concepts/proxy.rst b/doc/concepts/proxy.rst
new file mode 100644
index 0000000..1af597a
--- /dev/null
+++ b/doc/concepts/proxy.rst
@@ -0,0 +1,118 @@
+FreeRADIUS as a proxy RADIUS server.
+====================================
+
+
+Introduction
+------------
+
+It is possible to use FreeRADIUS as a proxy RADIUS server. This
+means that it can consult a remote RADIUS server to validate a user.
+This is handy for roaming setups, or for renting ports to someone else.
+
+Files
+-----
+
+If a user logs in with a defined realm syntax, the "realm" portion is
+matched against the configuration to determine how the request should
+be handled.  Common realm formats are:
+
+::
+
+  username@realm
+  realm/username
+  username%realm
+  realm\username
+
+The realm parsing syntax ( and search order ) is user definable via the
+realm module config in the ``/etc/raddb/mods-available/realm`` configuration
+file.
+
+You can define multiple instances of the realm module to support multiple
+realm syntax's at the same time.  Be sure to pay close attention to the
+search order that you define, as you may inadvertently get unexpected
+behaviour ( by having a user use ``realm1/username@realm2`` for instance ).
+If you need to proxy to IPASS, it should go first, because usernames will
+be in the form ``IPASS/username@realm`` and you want to proxy these users to
+IPASS, not to the realm behind the ``@``.
+
+The realms are configured in the file ``/etc/raddb/proxy.conf``, which is
+included by ``radiusd.conf``. The formats and sample configurations are
+included as comments.
+
+The realm ``DEFAULT`` (without the quotes) matches all realms.
+The realm ``NULL`` matches any requests WITHOUT a realm.
+
+If you set the remote server to ``LOCAL``, the request will be handled
+locally as usual, without sending it to a remote radius server.
+
+There are several options you can add in ``/etc/raddb/proxy.conf``:
+
+- nostrip:
+  By default the realm is stripped from the username before sending it
+  on to the remote radius server. By specifying the "nostrip" option
+  the @realm suffix will not be stripped.
+- hints
+  By default the original username is sent to the remote radius
+  server. By specifying the "hints" option the username will be
+  sent as it is after the "hints" file was processed.
+- notrealm:
+  By default if a realm is matched, it will be proxied to the server
+  specified.  However, if you are using Replication functionality, you
+  may want to override this behaviour.  This option will prevent a
+  user who enters ``user@foobar`` from being proxied if the ``foobar``
+  realm configuration contains ``notrealm``.  This function used to be
+  called ``notsuffix``, and the old syntax is still supported.
+
+The ``/etc/raddb/realms`` file is deprecated and should not be used anymore.
+If you use the ``/etc/raddb/realms`` file to enter realm configurations you will
+need to add the hostname and secret for the remote server in the
+file ``/etc/raddb/clients.conf``.
+It is not recommended to use both the realms file and the proxy.conf file,
+as that could cause confusion.
+
+Accounting
+----------
+
+All accounting data for proxied requests does `not` get stored in the
+standard logfiles, but in a separate directory. The name of this
+directory is the name of the remote radius server.
+
+Remote Server
+----------------
+
+When your server proxies requests to another server, it acts as a NAS for
+the remote server. On the remote server, you need to add the hostname of
+your server and the same secret to ``/etc/raddb/clients.conf`` as well.
+
+As you might not control the remote radius server, you might want to
+control the attributes sent back by the remote server in an Access-Accept
+packet. Have a look at the attrs file for this!
+
+What Happens
+---------------
+The exact thing that happens is this:
+
+- A user logs in with a realm
+- The hints file gets processed as usual
+- The user is checked against the huntgroups file. At this point
+  the user `might` already be rejected.
+- The realm is looked up in the realms file. If it isn't defined,
+  the users file is processed normally.
+- If the ``notrealm`` option is defined, the user is processed
+  locally.
+- The realm is stripped from the username unless ``nostrip`` was
+  set, and the request is sent to a remote radius server. Note that
+  any stripping done in the hints file doesn't have an effect on the
+  username sent to the remote radius server unless you set the
+  ``hints`` option.
+- The remote server replies with Access-Accept or Access-Reject
+
+::
+
+  On Access-Accept:    The initial Auth-Type is set to Accept
+  On Access-Reject:    The initial Auth-Type is set to Reject
+
+Then the users file is processed as usual. The username used at
+this point is the one after hints file processing (regardless of
+the ``hints`` option). It also includes the realm (regardless of the
+setting of the ``nostrip`` option) unless the realm is ``LOCAL``.