4 The mschap module provides support for MS-CHAPv1 and MS-CHAPv2, which is
5 a common authentication mechanisms for Microsoft clients.
7 If you want to support mschap, there are only 3 possibilities:
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.
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
16 3. You have Samba installed, joined into a windows domain, and use
17 the ntlm_auth helper binary to pass authentication onwards to
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.
25 http://deployingradius.com/documents/protocols/compatibility.html
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.
36 Method 3 above involves configuring the mschap module to call the Samba
42 ntlm_auth = "/path/to/bin ..."
45 You need to be careful about setting this command line. There are several
46 options for the arguments, in particular username and domain:
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
51 You'll need to fit this to your local needs.
53 Disabling ntlm_auth for some users
54 ----------------------------------
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::
59 MS-CHAP-Use-NTLM-Auth := 0
61 This will disable ntlm_auth for that user/group. This is also obeyed
62 for password changes (see below).
67 From FreeRADIUS version 3.0.0 the mschap module supports password changes.
69 There are two options, ntlm_auth and local.
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::
82 ntlm_auth = "/path/to/ntlm_auth --helper-protocol=ntlm-change-password-1"
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}"
90 ntlm_auth_username = "full-username: %{User-Name}"
91 # ntlm_auth_domain - disabled
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.
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
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::
114 local_cpw = "%{xlat:...}
118 To actually force a client to change passwords, you must set the expiry bit
119 in the SMB-Account-Ctrl value - for example::
124 SMB-Account-Ctrl-Text := '[Ue]'
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
135 local_cpw = "%{sql:select change_password('%{SQL-User-Name}','%{MS-CHAP-New-NT-Password}')}"
139 ...and an example stored procedure for Postgres might be::
141 CREATE FUNCTION change_password(raduser text, ntpassword text) RETURNS text
145 update radcheck set value=ntpassword where username=raduser and attribute='NT-Password';
147 -- the user does not exist; die
150 update radcheck set value=replace(value,'e','') where username=raduser and attribute='SMB-Account-Ctrl-Text' and value like '%e%';
156 The local_cpw xlat has access to two variables:
158 * MS-CHAP-New-NT-Password - the new value of NT-Password
159 * MS-CHAP-New-Cleartext-PAssword - the new value of Cleartext-Password
161 This allows you to do things like::
164 local_cpw = "%{sql:update radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{SQL-User-Name} and attribute='NT-Password'}"
168 # update via exec/script
169 local_cpw = "%{exec:/my/script %{User-Name} %{MS-CHAP-New-Cleartext-Password}}"
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.
179 N.B. this could be fixed, if we wanted to pull in something like iconv.
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
185 Password changes over EAP
186 =========================
188 You must set the following in eap.conf::
196 Otherwise password changes for PEAP/MSCHAPv2 will not work.