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.

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.