rlm_mschap

Synopsis

Microsoft CHAP authentication.

This module supports MS-CHAP and MS-CHAPv2 authentication. It also enforces the SMB-Account-Ctrl attribute.

As of Version 3.0.8, the module allows for direct connection to a Samba server, version 4.2.1 or above. This connection is much faster than using the ntlm_auth program.

Default configuration

Processing Sections

authorize

When listed in the authorize section, the mschap module looks for MS-CHAP-* attributes, and sets &control:Auth-Type := MS-CHAP.

Return codes: noop There were no MS-CHAP attributes in the request.
: fail The module could not set &control:Auth-Type := MS-CHAP.
: ok The module succeeded in setting &control:Auth-Type := MS-CHAP.

authenticate

When listed in the authenticate section, the mschap module performs MS-CHAP authentication.

Return codes: notfound The users account was disabled.
: userlock The users account was locked.
: invalid The module was unable to find or calculate an NT-Password attribute, or there were no MS-CHAP attributes in the request, or the MS-CHAP attributes were malformed.
: fail An error prevented the module from calculating the MS-CHAP data.
: reject The user failed authentication.
: ok The user was successfully authenticated.

Expansions

This module registers only one expansion.

mschap

Syntax: %{mschap: …}
Contents: The contents of the expansion is one of the following keywords, with the following meanings.

Table 1. Keyword
Keyword	Description
Challenge	the MS-CHAPv1 challenge string.
LM-Hash	The LM hash of the following string. e.g. `%{mschap:LM-Hash password}`
LM-Response	The LM Response field. Typically all zeros.
NT-Hash	The NT hash of the following string. e.g. `%{mschap:NT-Hash password}`
NT-Domain	The domain field. e.g. for `DOMAIN\name`, it is `DOMAIN`
User-Name	The user name fild. e.g. for `DOMAIN\name`, it is `name`

Directives

allow_retry

Syntax: allow_retry = boolean
Default: yes
Description: On failure, set (or not) the MS-CHAP error code saying "retries allowed".

ntlm_auth

Syntax: ntlm_auth = string
Default: "/path/to/ntlm_auth --request-nt-key --username=%%%{Stripped-User-Name}:-%%%{User-Name}:-None}} --challenge=%%%\{mschap:Challenge}:-00} --nt-response=%%%\{mschap:NT-Response}:-00}"
Description: If ntlm_auth is configured below, then the mschap module will call ntlm_auth for every MS-CHAP authentication request. If there is a cleartext or NT hashed password available, you can set MS-CHAP-Use-NTLM-Auth := No in the control items, and the mschap module will do the authentication itself, without calling ntlm_auth.

Be VERY careful when editing ntlm_auth because it won’t work if you get it wrong!

The user name may also be set as: --username=%\{mschap:User-Name\}

In that case, the mschap module will look at the User-Name attribute and do prefix/suffix checks in order to obtain the "best" user name for the request.

require_encryption

Syntax: require_encryption = boolean
Default: yes
Description: If use_mppe is set to yes, then require_encryption makes encryption moderate.

require_strong

Syntax: require_strong = boolean
Default: yes
Description: require_strong always requires 128 bit key encryption. The module can perform authentication itself, OR use a Windows Domain Controller. This configuration directive tells the module to call the ntlm_auth program, which will do the authentication and return the NT-Key. Note that you MUST have winbindd and numbed running on the local machine for ntlm_auth to work. See the ntlm_auth program documentation for details.

retry_msg

Syntax: retry_msg = string
Default: "Re-enter (or reset) the password"
Description: An optional retry message.

use_mppe

Syntax: use_mppe = boolean
Default: no
Description: If you are using '/etc/smbpasswd', see the passwd module for an example of how to use '/etc/smbpasswd'
: If use_mppe is not set to no mschap will add MS-CHAP-MPPE-Keys for MS-CHAPv1 and MS-MPPE-Recv-Key/MS-MPPE-Send-Key for MS-CHAPv2

use_open_directory

Syntax: use_open_directory = boolean
Default: yes
Description: For Apple Server, when running on the same machine as Open Directory. It has no effect on other systems.

pool

Syntax: pool { … }
Description: A sub-section which manages connections to the Samba winbind server. See the pool documentation for more information.

winbind_username:

Syntax: winbind_username = "%{mschap:User-Name}"
Description: The user name to use for authentication, when binding directly to Winbindd.
: This option requires libwbclient from Samba 4.2.1 or later. The ntlm_auth directive, above, cannot be used at the same time as this one.

winbind_domain:

Syntax: winbind_domain = "%{mschap:NT-Domain}"
Description: The domain name to use for authentication, when binding directly to Winbindd.
: This option requires libwbclient from Samba 4.2.1 or later. The ntlm_auth directive, above, cannot be used at the same time as this one.

passchange

Synopsis

The passchange subsection allows users passwords to be changed via MS-CHAP and Samba. As password change is different from authentication, there is a separate set of configuration for this behavior.

: The module supports MS-CHAPv2, not v1, password change requests. See mschap.rst for more information on how to configure this behavior.

Directives

local_cpw

Syntax: local_cpw = "%{exec:/path/to/script %\{mschap:User-Name} %{MS-CHAP-New-Cleartext-Password}}"
: local_cpw = "%{sql:UPDATE radcheck set value='%{MS-CHAP-New-NT-Password}' where username='%{SQL-User-Name}' and attribute='NT-Password'}"
Description: This directive gives a local command to change the password.
: To implement a local password change, you need to supply a string, which is then expanded so that the password can be placed somewhere, e.g., passed to a script (exec) or written to SQL (UPDATE/INSERT). We give both examples here (above), but only one will be used.

ntlm_auth

Syntax: ntlm_auth = "/usr/bin/ntlm_auth --helper-protocol=ntlm-change-password-1"
Description: The path and arguments to the ntlm_auth program which will be used to change the password.

ntlm_auth_username

Syntax: ntlm_auth_username = "username: %\{mschap:User-Name}"
Description: The user name argument for the password change.

ntlm_auth_domain

Syntax: ntlm_auth_domain = "nt-domain: %\{mschap:NT-Domain}"
Description: The domain name argument for the password change.