Microsoft CHAP authentication Module

The mschap module performs MS-CHAP and MS-CHAPv2 authentication.

MS-CHAP authentication requires access to either the Password.Cleartext or Password.NT attribute for the user. Due to the limitations of MS-CHAP, no other password "encryption" methods are possible.

This module validates a user with MS-CHAP or MS-CHAPv2 authentication. If called in recv Access-Request, it will look for MS-CHAP Challenge/Response attributes in the request list and adds an Auth-Type attribute set to mschap in the Config-Items list unless Auth-Type has already set.

The module also enforces the SMB-Account-Ctrl attribute. See the Samba documentation for the meaning of SMB account control. The module does not read Samba password files. Instead, the rlm_passwd module can be used to read a Samba password file, and then supply an Password.NT attribute which this module can use.

The mschap module registers a few xlat functions.

Function Description

Function	Description
`Challenge`	The MS-CHAP challenge.
`Domain-Name`	The full domain name, taken from the `User-Name` attribute
`NT-Domain`	The NT domain portion of the domain name, taken from the `User-Name` attribute
`NT-Hash`	Take the NT-Hash of the string passed into the xlat
`NT-Response`	The MS-CHAP response.
`User-Name`	The MS-CHAP username portion of the `User-Name` attribute.

Challenge

The MS-CHAP challenge.

Domain-Name

The full domain name, taken from the User-Name attribute

NT-Domain

The NT domain portion of the domain name, taken from the User-Name attribute

NT-Hash

Take the NT-Hash of the string passed into the xlat

NT-Response

The MS-CHAP response.

User-Name

The MS-CHAP username portion of the User-Name attribute.

For more documentation on integrating FreeRADIUS with Active Directory, please see the following web page: http://deployingradius.com/documents/configuration/active_directory.html

Configuration Settings

If you are using /etc/smbpasswd, see the passwd module for an example of how to use /etc/smbpasswd

normalise: By default the server will use heuristics to try and automatically handle base64 or hex encoded passwords or hashes. This behaviour can be disabled by setting the following to no.

The default is yes

use_mppe: By default the mschap will add MS-CHAP-MPPE-Keys for MS-CHAPv1 and MS-MPPE-Recv-Key and MS-MPPE-Send-Key for MS-CHAPv2. Set this configuration item to no in order to not add the MPPE keys.

Default is yes.

require_encryption: if use_mppe is enabled, the require_encryption makes encryption moderate.

Default is no.

require_strong: It always requires 128 bit key encryption.

Default is no.

with_ntdomain_hack: Windows clients send User-Name in the form of "DOMAIN\User", but send the challenge/response based only on the User portion.

Default is yes.

ntlm_auth: Path and arguments to the ntlm_auth program.

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.

you MUST have the such services "winbindd" and "nmbd" running on the local machine for ntlm_auth to work.

See the ntlm_auth program documentation for details.

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.

You can also set MS-CHAP-Use-NTLM-Auth := Auto. If a password is available, it will be used. Otherwise the module will fall back to ntlm_auth.

You can also try setting the user name 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.

Depending on the AD / Samba configuration, you may also need to add:

--allow-mschapv2

to the list of command-line options.

Be VERY careful when editing the following line! Change the path, and ideally nothing else.

ntlm_auth_timeout: Time to wait for ntlm_auth to run.

This is a long time, and if ntlm_auth is taking that long then you likely have other problems in your domain.

The length of time can be decreased with the following option, which can save clients waiting if your ntlm_auth usually finishes quicker.

Range 1 to 10 seconds.

Default is 10 seconds.

winbind { …}: Configuration options for talking to Winbind.
username: User name for winbind
domain: Domain name for winbind

An alternative to using ntlm_auth is to connect to the winbind daemon directly for authentication. This option is likely to be faster and may be useful on busy systems.

Performance seems to be about twice that of ntlm_auth, which still isn’t a lot.

Using this option requires libwbclient from Samba 4.2.1 or later to be installed. Make sure that ntlm_auth above is commented out.

retry_with_normalised_username: When using single sign-on with a winbind connection and the client uses a different casing for the username than the casing is according to the backend, reauth may fail because of some Windows internals. This switch tries to find the user in the correct casing in the backend, and retry authentication with that username.

Pool

Information for the winbind connection pool. The configuration items below are the same for all modules which use the connection pool.

start: Connections to create during module instantiation.

If the server cannot create specified number of connections during instantiation it will exit. Set to 0 to allow the server to start without the external service being available.

min: Minimum number of connections to keep open.
max: Maximum number of connections.

If these connections are all in use and a new one is requested, the request will NOT get a connection.

Setting max to LESS than the number of threads means that some threads may starve, and you will see errors like No connections available and at max connection limit.

Setting max to MORE than the number of threads means that there are more connections than necessary.

If max is not specified, then it defaults to the number of workers configured.

spare: Spare connections to be left idle.

Idle connections WILL be closed if idle_timeout is set. This should be less than or equal to max above.

uses: Number of uses before the connection is closed.

0 means "infinite"

retry_delay: The number of seconds to wait after the server tries to open a connection, and fails. During this time, no new connections will be opened.
lifetime: The lifetime (in seconds) of the connection.

A setting of 0 means infinite (no limit).

cleanup_interval: The pool is checked for free connections every cleanup_interval. If there are free connections, then one of them is closed.
idle_timeout: The idle timeout (in seconds). A connection which is unused for this length of time will be closed.

A setting of 0 means infinite (no timeout).

All configuration settings are enforced. If a connection is closed because of idle_timeout, uses, or lifetime, then the total number of connections MAY fall below min. When that happens, it will open a new connection. It will also log a WARNING message.

The solution is to either lower the min connections, or increase lifetime/idle_timeout.

Pass Change

ntlm_auth: Path and arguments to ntlm_auth for password change.
ntlm_auth_username: The user name for ntlm_auth password change.
ntlm_auth_domain: The domain name for ntlm_auth password change.

This module support MS-CHAPv2 (not v1) password change requests. See doc/howto/modules/mschap.adoc for some IMPORTANT information.

Samba/ntlm_auth - if you are using ntlm_auth to validate passwords, you will need to use ntlm_auth to change passwords.

Uncomment the three lines below, and change the path to `ntlm_auth.

local_cpw: 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, but only one should be used.

use_open_directory: For Apple Server, when running on the same machine as Open Directory. It has no effect on other systems.
allow_retry: On failure, set (or not) the MS-CHAP error code saying retries allowed.
retry_msg: An optional retry message.

Attributes

The mschap module needs to be configured with which attributes contain MS-CHAP data in the request and which should be used for MS-CHAP data in the reply.

This varies for different protocols. The defaults show below are for RADIUS.

username: The attribute containing the user name.
chap_challenge: The attribute containing the CHAP Challenge.
chap_response: The attribute containing the CHAP Response for MS-CHAPv1.
chap2_response: The attribute containing the CHAP Response for MS-CHAPv2.
chap2_success: The attribute MS-CHAPv2 success messages are returned in.
chap_error: The attribute CHAP error messages are returned in.
chap_mppe_keys: The attribute MPPE keys are returned in for MS-CHAPv1
mppe_recv_key: The attribute MPPE recv key is returned in for MS-CHAPv2
mppe_send_key: The attribute MPPE send key is returned in for MS-CHAPv2
mppe_encryption_policy: The attribute that MPPE encryption policy is returned in.
mppe_encryption_types: The attribute that MPPE encryption type is returned in.
chap2_cpw: The attribute used to change a users' password
chap_nt_enc_pw: The attribute containing the encrypted new NT password

To use this instance of the mschap module to handle TACACS+ the attribute section should be replaced with the following.

TACACS+ does not have any inherent support for MPPE keys or password changing using MSCHAP.

Default Configuration

mschap {
#	normalise = no
#	use_mppe = no
#	require_encryption = yes
#	require_strong = yes
#	with_ntdomain_hack = no
#	ntlm_auth = "/path/to/ntlm_auth --request-nt-key  --allow-mschapv2 --username=%{&Stripped-User-Name || &User-Name || 'None'} --challenge=%{%mschap(Challenge) || 00} --nt-response=%{%mschap(NT-Response) || 00}"
#	ntlm_auth_timeout = 10
	winbind {
#		username = "%mschap(User-Name)"
#		domain = "%mschap(NT-Domain)"
#		retry_with_normalised_username = no
	}
	pool {
		start = 0
		min = 0
#		max =
		spare = 1
		uses = 0
		retry_delay = 30
		lifetime = 86400
		cleanup_interval = 300
		idle_timeout = 600
	}
	passchange {
#		ntlm_auth = "/usr/bin/ntlm_auth --helper-protocol=ntlm-change-password-1"
#		ntlm_auth_username = "username: %mschap(User-Name)"
#		ntlm_auth_domain = "nt-domain: %mschap(NT-Domain)"
#		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='%{User-Name}' and attribute='Password.NT'")
	}
#	use_open_directory = yes
#	allow_retry = yes
#	retry_msg = "Re-enter (or reset) the password"
	Xattributes {
		username = &User-Name
		chap_challenge = &Vendor-Specific.Microsoft.CHAP-Challenge
		chap_response = &Vendor-Specific.Microsoft.CHAP-Response
		chap2_response = &Vendor-Specific.Microsoft.CHAP2-Response
		chap2_success = &Vendor-Specific.Microsoft.CHAP2-Success
		chap_error = &Vendor-Specific.Microsoft.CHAP-Error
		chap_mppe_keys = &Vendor-Specific.Microsoft.CHAP-MPPE-Keys
		mppe_recv_key = &Vendor-Specific.Microsoft.MPPE-Recv-Key
		mppe_send_key = &Vendor-Specific.Microsoft.MPPE-Send-Key
		mppe_encryption_policy = &Vendor-Specific.Microsoft.MPPE-Encryption-Policy
		mppe_encryption_types = &Vendor-Specific.Microsoft.MPPE-Encryption-Types
		chap2_cpw =  &Vendor-Specific.Microsoft.CHAP2-CPW
		chap_nt_enc_pw = &Vendor-Specific.Microsoft.CHAP-NT-Enc-PW
	}
	attributes {
		username = &User-Name
		chap_challenge = &MS-CHAP-Challenge
		chap_response = &MS-CHAP-Response
		chap2_response = &MS-CHAP2-Response
		chap2_success = &MS-CHAP2-Success
		chap_error = &MS-CHAP-Error
	}
}