path: root/raddb/mods-available/mschap

# -*- text -*-
#
#  $Id$

#
#  Microsoft CHAP authentication
#
#  This module supports MS-CHAP and MS-CHAPv2 authentication.
#  It also enforces the SMB-Account-Ctrl attribute.
#
mschap {
	#
	#  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_mppe = no

	#
	#  If MPPE is enabled, require_encryption makes
	#  encryption moderate
	#
#	require_encryption = yes

	#
	#  require_strong always requires 128 bit key
	#  encryption
	#
#	require_strong = yes

	#
	#  This 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
	#  "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.
	#
	#  This authentication can go wrong for a number of reasons:
	#    1) the user does not exist in AD
	#    2) the password entered by the user is not the same as
	#      what is in AD
	#    3) some magic MS-CHAP data is wrong.
	#
	#  These situations can be checked by running ntlm_auth
	#  from the command line with a name and a password:
	#
	#	ntlm_auth --username=NAME --password=PASSWORD
	#
	#  If that works, you know both that the user exists, and the
	#  password is correct.  You also know what AD expects for the
	#  username.
	#
	#  There is often confusion between different formats of the
	#  username.  Is it "user", or "user@domain" or "DOMAIN\\user"?
	#  The answer is "that depends on your local AD system".
	#
	#  One solution is to use this for the username:
	#
	#	... --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.
	#
	#  Another option is to use the Stripped-User-Name, as in the
	#  example configuration below.
	#
	#  You can test which format works by running the server in
	#  debug mode, and copying the hex strings from the
	#  --challenge=... and --nt-response=... output.
	#
	#  Then, run ntlm_auth from the command line, using the same
	#  command-line options as given below.  Since you can't
	#  change the challenge or nt-response strings, try changing
	#  the --username=... and --domain=... parameters.  Try
	#  different formats for them until one works.  There should only
	#  be a small number of variations possible.
	#
	#  That is the username and domain format which you need to
	#  configure here in this file.
	#
	#  For Samba 4, you should also set the "ntlm auth" parameter
	#  in the Samba configuration:
	#
	#	ntlm auth = yes
	#
	#  or
	#
	#	ntlm auth = mschapv2-and-ntlmv2-only
	#
	#  This will let Samba 4 accept the MS-CHAP authentication
	#  method that is needed by FreeRADIUS.
	#
	#  Depending on the Samba version, you may also need to add:
	#
	#	--allow-mschapv2
	#
	#  to the command-line parameters.
	#
#	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}"

	#
	#  The default is to wait 10 seconds for ntlm_auth to
	#  complete.  This is a long time, and if it's 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.
	#
#	ntlm_auth_timeout = 10

	#
	#  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,
	#  but is less well tested.
	#
	#  Using this option requires libwbclient from Samba 4.2.1
	#  or later to be installed. Make sure that ntlm_auth above is
	#  commented out.
	#
#	winbind_username = "%{mschap:User-Name}"
#	winbind_domain = "%{mschap:NT-Domain}"

	#
	#  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.
	#
#	winbind_retry_with_normalised_username = no

	#
	#  Information for the winbind connection pool.  The configuration
	#  items below are the same for all modules which use the new
	#  connection pool.
	#
	pool {
		#
		#  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
		#  winbind daemon being available.
		#
		start = ${thread[pool].start_servers}

		#
		#  Minimum number of connections to keep open
		#
		min = ${thread[pool].min_spare_servers}

		#
		#  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.
		#
		max = ${thread[pool].max_servers}

		#
		#  Spare connections to be left idle
		#
		#  NOTE: Idle connections WILL be closed if "idle_timeout"
		#  is set.  This should be less than or equal to "max" above.
		#
		spare = ${thread[pool].max_spare_servers}

		#
		#  Number of uses before the connection is closed
		#
		#  0 means "infinite"
		#
		uses = 0

		#
		#  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.
		#
		retry_delay = 30

		#
		#  The lifetime (in seconds) of the connection
		#
		#  NOTE: A setting of 0 means infinite (no limit).
		#
		lifetime = 86400

		#
		#  The pool is checked for free connections every
		#  "cleanup_interval".  If there are free connections,
		#  then one of them is closed.
		#
		cleanup_interval = 300

		#
		#  The idle timeout (in seconds).  A connection which is
		#  unused for this length of time will be closed.
		#
		#  NOTE: A setting of 0 means infinite (no timeout).
		#
		idle_timeout = 600

		#
		#  NOTE: 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.
		#
	}

	passchange {
		#
		#  This support MS-CHAPv2 (not v1) password change
		#  requests.  See doc/mschap.rst for more 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.
		#
#		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}"

		#
		#  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 will be
		#  used.
		#
#		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'}"
	}

	#
	#  For Apple Server, when running on the same machine as
	#  Open Directory.  It has no effect on other systems.
	#
#	use_open_directory = yes

	#
	#  On failure, set (or not) the MS-CHAP error code saying
	#  "retries allowed".
	#
#	allow_retry = yes

	#
	#  An optional retry message.
	#
#	retry_msg = "Re-enter (or reset) the password"
}