doc/mschap.rst

   1 rlm_mschap
   2 ==========
   3
   4 The mschap module provides support for MS-CHAPv1 and MS-CHAPv2, which is
   5 a common authentication mechanisms for Microsoft clients.
   6
   7 If you want to support mschap, there are only 3 possibilities:
   8
   9  1. You have access to the users plaintext password, and you configure
  10     FreeRADIUS to read this, and set the Cleartext-Password control attribute.
  11
  12  2. You have access to the NT (MS-CHAPv2) or LM (MS-CHAPv1) hashes,
  13     and you configure FreeRADIUS to read this and set the NT/LM-Password
  14     control attribute.
  15
  16  3. You have Samba installed, joined into a windows domain, and use
  17     the ntlm_auth helper binary to pass authentication onwards to
  18     a domain controller.
  19
  20 These are the ONLY possibilities; MS-CHAP is IMPOSSIBLE if you e.g. only
  21 have the unix/md5/sha crypt of your users password.
  22
  23 For more info, see:
  24
  25  http://deployingradius.com/documents/protocols/compatibility.html
  26
  27 EAP-MSCHAPv2
  28 ============
  29
  30 The EAP module provides MS-CHAPv2 support as well. It simply passes the
  31 data through to the mschap module, so you must configure mschap properly.
  32
  33 ntlm_auth
  34 =========
  35
  36 Method 3 above involves configuring the mschap module to call the Samba
  37 ntlm_auth helper:
  38
  39 ::
  40
  41   mschap {
  42     ntlm_auth = "/path/to/bin ..."
  43   }
  44
  45 You need to be careful about setting this command line. There are several
  46 options for the arguments, in particular username and domain:
  47
  48  * --username=%{User-Name} - this will fail if you're using realms or host-based auth
  49  * --username=%{mschap:User-Name} - this will fail if using using suffix i.e. user@domain
  50
  51 You'll need to fit this to your local needs.
  52
  53 Disabling ntlm_auth for some users
  54 ----------------------------------
  55
  56 You might have some users in the domain, and others in files or SQL that you
  57 want to authenticate locally. To do this, set::
  58
  59  MS-CHAP-Use-NTLM-Auth := 0
  60
  61 This will disable ntlm_auth for that user/group. This is also obeyed
  62 for password changes (see below).
  63
  64 Password changes
  65 ================
  66
  67 From FreeRADIUS version 3.0.0 the mschap module supports password changes.
  68
  69 There are two options, ntlm_auth and local.
  70
  71 ntlm_auth
  72 ---------
  73
  74 If you are using ntlm_auth to check passwords, you must also use
  75 ntlm_auth to change passwords. In modules/mschap you should configure::
  76
  77   mschap {
  78     ntlm_auth = "...."
  79     passchange {
  80
  81       # path to the binary
  82       ntlm_auth = "/path/to/ntlm_auth --helper-protocol=ntlm-change-password-1"
  83
  84       # initial data to send
  85       # this MUST be supplied
  86       ntlm_auth_username = "username: %{mschap:User-Name}"
  87       ntlm_auth_domain = "nt-domain: %{%{mschap:NT-Domain}:-YOURDOMAIN}"
  88
  89       # Or, you could try:
  90       ntlm_auth_username = "full-username: %{User-Name}"
  91       # ntlm_auth_domain - disabled
  92
  93     }
  94
  95
  96 If you are using ntlm_auth, then domain controllers might say
  97 "Password expired" if the user password is valid but has expired; the
  98 mschap module will detect this and return error 648 to the client,
  99 instructing it to try a password change.
 100
 101 Note: if you have disabled ntlm_auth for a user/group, this will apply
 102 for password changes too - they will fall through to using the Local
 103 method.
 104
 105 Local
 106 -----
 107
 108 If you are performing mschap locally with Cleartext-Password/NT-Password, you
 109 can decrypt and process the password change locally. To do this, you configure
 110 the "local_cpw" string::
 111
 112   mschap {
 113     passchange {
 114       local_cpw = "%{xlat:...}
 115     }
 116   }
 117
 118 To actually force a client to change passwords, you must set the expiry bit
 119 in the SMB-Account-Ctrl value - for example::
 120
 121   update control {
 122     # U == user
 123     # e == expired
 124     SMB-Account-Ctrl-Text := '[Ue]'
 125   }
 126
 127 This will cause the client to receive "error 648 - password
 128 expired". Obviously you will need to ensure your local_cpw xlat clears
 129 this value, or else the client password will be expired the next time
 130 they log in. For example, you might use an SQL stored procedure to
 131 change passwords::
 132
 133   mschap {
 134     passchange {
 135       local_cpw = "%{sql:select change_password('%{SQL-User-Name}','%{MS-CHAP-New-NT-Password}')}"
 136     }
 137   }
 138
 139 ...and an example stored procedure for Postgres might be::
 140
 141   CREATE FUNCTION change_password(raduser text, ntpassword text) RETURNS text
 142       LANGUAGE plpgsql
 143       AS $$
 144   BEGIN
 145           update radcheck set value=ntpassword where username=raduser and attribute='NT-Password';
 146           if not FOUND then
 147                   -- the user does not exist; die
 148                   return '';
 149           end if;
 150           update radcheck set value=replace(value,'e','') where username=raduser and attribute='SMB-Account-Ctrl-Text' and value like '%e%';
 151           return 'ok';
 152   END;
 153   $$;
 154
 155
 156 The local_cpw xlat has access to two variables:
 157
 158  * MS-CHAP-New-NT-Password        - the new value of NT-Password
 159  * MS-CHAP-New-Cleartext-PAssword - the new value of Cleartext-Password
 160
 161 This allows you to do things like::
 162
 163   # update via SQL
 164   local_cpw = "%{sql:update radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{SQL-User-Name} and attribute='NT-Password'}"
 165
 166 Or::
 167
 168   # update via exec/script
 169   local_cpw = "%{exec:/my/script %{User-Name} %{MS-CHAP-New-Cleartext-Password}}"
 170
 171 WARNING - wherever possible, you should use
 172 MS-CHAP-New-NT-Password. The reason is that cleartext passwords have
 173 undergone unicode transformation from the client encoding (utf-16) to
 174 the server encoding (utf-8) and the current code does this in a very
 175 ad-hoc way. The reverse transformation is also not done - when the
 176 server reads Cleartext-Password out of files/database, it assumes
 177 US-ASCII and thus international characters will fail.
 178
 179 N.B. this could be fixed, if we wanted to pull in something like iconv.
 180
 181 In addition, you should beware of Cleartext-Password when using SQL;
 182 any password character not in safe-characters will be encoded as a hex
 183 number, e.g. =20.
 184
 185 Password changes over EAP
 186 =========================
 187
 188 You must set the following in eap.conf::
 189
 190  eap {
 191    mschapv2 {
 192      send_error = yes
 193    }
 194  }
 195
 196 Otherwise password changes for PEAP/MSCHAPv2 will not work.