doc/aaa.rst

   1 Authorization, Authentication, and Accounting request handling
   2 ==============================================================
   3
   4 There are a lot of questions about misconfigured FreeRADIUS servers
   5 because of misunderstanding of FreeRADIUS operations.  This document
   6 explains how the server operates.
   7
   8 Normally there are 2 steps in processing authentication request coming
   9 from NAS in FreeRADIUS (plus additional steps to proxy request if we
  10 use FreeRADIUS as a proxy): authorization and authentication.
  11
  12
  13 Authorization
  14 -------------
  15
  16 Authorization is a process of obtaining information about the user
  17 from external source (file, database or LDAP), and checking that the
  18 information in request is enough to authenticate user.  Authorization
  19 modules deal with data sources, so ldap, sql, files, passwd are
  20 authorization modules.
  21
  22 The authentication method is decided during the authorization phase,
  23 along with any reply attributes.  The reason for this behaviour is
  24 that for example, a user may not be permitted to use a particular
  25 authentication method.  So during the authorize phase, we can deny
  26 them the ability to use that kind of authentication.
  27
  28 Authentication
  29 --------------
  30
  31 Authentication is simply a process of comparing user's credentials in
  32 request with credentials stored in database.  Authentication usually
  33 deals with password encryption.  PAP, CHAP, MS-CHAP are authentication
  34 modules.  Few modules act as both authorization and authentication.
  35 For example, the MS-CHAP module is normally authentication only, but it
  36 may be used during authorization to verify that request contains
  37 MS-CHAP related attribute and only in this case perform MS-CHAP based
  38 authentication. LDAP is normally an authorization module, but it may
  39 be used for authentication (In this case FreeRADIUS will authenticate
  40 user in case he can connect to LDAP server with his account).  SQL is
  41 only an authorization module, as dial-in users are not normally given
  42 passwords to access an SQL server.
  43
  44
  45 Request Processing
  46 ------------------
  47
  48 During authorization and authentication processes, there are 3 lists
  49 of RADIUS attributes supported by FreeRADIUS: request items, config
  50 items and reply items.  (See 'man 5 users' for additional
  51 information.)  Attributes from the RADIUS authentication request
  52 packet are included into request items list.  Both authorization and
  53 authentication modules can add attributes into reply items list. These
  54 attributes will be added to reply will be sent by RADIUS server to
  55 NAS.  There is third list, called config items.  It's used for
  56 internal FreeRADIUS operations, for example to pass some data from
  57 authorization to authentication module.
  58
  59 Before authorization begins FreeRADIUS creates request items list with
  60 attributes from request and empty config and reply lists.
  61
  62 An authorization module searches a database with attributes
  63 (e.g. User-Name) taken from request list as a key, and fetches all
  64 relevant records.  It retrieves 3 types of attributes: check
  65 attributes, configure attributes and reply attributes. It compares the
  66 check attributes with attributes from request items. If none of
  67 database record for this User-Name matches in check attributes with
  68 request items authorization will fail. If a matching record is found,
  69 then the configure attributes will be added to configure items, and
  70 the reply attributes will be added to reply items list.  The check
  71 list may be required if we need to authenticate users with same name
  72 for different services (for example to treat User1 from NAS1 and User1
  73 from NAS2 as different users).
  74
  75 There should be at list one configure attribute provided by
  76 authorization module, called Auth-Type (since this attribute is from
  77 config items list it can't be in request or reply).  This attribute
  78 decides which module will be used to authenticate the user.  The
  79 Config items also contains information from database required to
  80 authenticate user, for example valid user's password or it's hash,
  81 login restrictions, etc.
  82
  83 A quite common mistake is to place the attributes in the wrong lists,
  84 for example placing Auth-Type, Password, NT-Password etc in the check
  85 list, or in the reply list.  When run in debugging mode, the server
  86 will normally issue 'WARNING' messages saying that the attributes are
  87 in the wrong list.
  88
  89 If you place Password into check list and user does cleartext
  90 authentication it may work, because authorization module compares 2
  91 cleartext passwords.  But if user does some encrypted authentication
  92 (for example MS-CHAP), then the authorization will fail, because the
  93 Password in the request items will not match the password in the check
  94 attributes.  You should place Password attribute obtained from
  95 database into configure items and also place Auth-Type attribute with
  96 value of 'MS-CHAP' into same list.  The same goes for NT-Password
  97 (before calling MS-CHAP Password attribute should be converted to
  98 NT-Password, it may be achieved by calling mschap module in
  99 authorization section after module which does actual authorization).