--- /dev/null
+= Join FreeRADIUS to AD Domain
+
+Some deployments use Active Directory services to use in mschap based authentications. The RADIUS server must alreay be up and running and basic authentication works (pap/chap). For a freeRADIUS server to fully leverage the AD server and relevant services, the RADIUS server must first be configured and then joined to the domain (or samba realm).
+
+
+ == Configuration of variables
+
+ Requires the following variables to be set by the including template:
+
+ - orch_minion: First orchestrator minion
+ - orch: Hostname of the orchestrator
+ - orch_fqdn: FQDN of the orchestrator
+ - host_exam: Example RADIUS authentication server hostname
+ - netbios_exam: Example netbios name for auth server host
+ - realm: Samba realm
+ - workgroup: Samba workgroup
+ - domains: List of domains mapping to the Kerberos realm
+ - dcs: List of AD domain controllers
+ - preferred: A preferred domain controller.
+ Default: No preference ("password server = *")
+ - admin: DC acting as the Kerberos master. Default: First entry in dcs.
+ - join_user: User privileged to perform domain joins. Optional.
+ - join_server: DC to use for the join operation. Optional.
+
+
+== Install packages for AD integration
+
+{%- if g[orch_minion]['os_family'] == 'RedHat' %}
+{%- set pkg = 'rpm' %}
+{%- elif g[orch_minion]['os_family'] == 'Debian' %}
+{%- set pkg = 'deb' %}
+{%- endif %}
+
+{%- if admin is not defined or admin == '' %}
+{%- set admin = dcs[0] %}
+{%- endif %}
+
+{%- if join_user is not defined or join_user == '' %}
+{%- set join_user = '[ privileged user ]' %}
+{%- endif %}
+
+{%- set join_server_opt = '-S ' ~ join_server if join_server is defined else '' %}
+
+
+== Domain membership for MS-CHAPv2 based authentication
+
+A prerequisite for authenticating domain users via MS-CHAPv2 is that the RADIUS
+authentication servers have been successfully joined to the domain and winbind
+configured.
+
+[NOTE]
+====
+Establishing and maintaining each host's domain membership is the
+responsibility of the customer, so only an outline process is provided here.
+Configuration varies between organisations and over time, so an organisation's
+domain administrator should be consulted for details.
+====
+
+Perform the following manual steps on each authentication server...
+
+=== Install winbind as follows:
+
+{% if pkg == 'deb' %}
+ {{ host_exam }}# apt-get install -y samba winbind krb5-user
+{% elif pkg == 'rpm' %}
+ {{ host_exam }}# yum install -y samba-winbind krb5-workstation
+{% else %}
+{%- set error = 'No instructions for this OS' + (0/0)|string %}
+{% endif %}
+
+== Configure `/etc/krb5.conf` as follows:
+
+```
+[libdefaults]
+ default_realm = {{ realm }}
+ dns_lookup_realm = false
+ dns_lookup_kdc = true
+
+[realms]
+ {{ realm }} = {
+{%- for d in dcs %}
+ kdc = {{ d }}
+{%- endfor %}
+ admin_server = {{ admin }}
+ }
+
+[domain_realm]
+{%- for d in domains %}
+ .{{ d }} = {{ realm }}
+ {{ d }} = {{ realm }}
+{%- endfor %}
+```
+
+=== Configure `/etc/samba/smb.conf` as follows:
+
+```
+[global]
+ netbios name = {{ netbios_exam }}
+ workgroup = {{ workgroup }}
+ server string = RADIUS server
+ dns proxy = no
+ security = ads
+ invalid users = root
+ unix password sync = no
+ pam password change = no
+
+ socket options = TCP_NODELAY
+ idmap uid = 16777216-33554431
+ idmap gid = 16777216-33554431
+ template shell = /bin/sh
+
+ winbind use default domain = no
+ winbind max domain connections = 10
+ winbind max clients = 1000
+{%- if preferred is defined %}
+ password server = {{ preferred }}, *
+{%- else %}
+ password server = *
+{%- endif %}
+ allow trusted domains = no
+ realm = {{ realm }}
+```
+
+== Join the host to the domain:
+
+ radius-auth1# net ads join -U {{ join_user }} {{ join_server_opt }}
+
+[NOTE]
+====
+ It is normal to receive an error message about failure to update DNS.
+====
+
+== Restart the winbind service:
+
+ radius-auth1# systemctl stop winbind
+ radius-auth1# systemctl start winbind
+
+A description of how to test and troubleshoot winbind is provided in the
+[Operations and troubleshooting guide](/doc/html/ops/operations.html) document.
+
+Authentication must be achieved using the `wbinfo` tool before FreeRADIUS will
+be able to successfully authenticate users performing a MS-CHAPv2 based method.
+
+If there are going to be password changes with freeradius ("your password has expired" - type - scenarios) You should probably also configure in /mods-available/mschap:
+
+passchange {
+ntlm_auth = "/path/to/ntlm_auth
+--helper-protocol=ntlm-change-password-1 --allow-mschapv2
+ntlm_auth_username = "username: %{mschap:User-Name}
+ntlm_auth_domain = "nt-domain: %{mschap:NT-Domain}"
+With the settings above it works correctly, so even if it is unnecessary, it doesn't break anything. It hasn't been tested without this option while denying ntlmv1 overall on the AD DC, but it is thought that it will work without it.
+
-= Integrating with Active Directory (AD)
+== Configuring Authentication with Active Directory (AD)
-The main steps to integrate FreeRADIUS authentication with Active Directory are:
+Once the PAP authentication test has been successful, the next step for sites using Active Directory is to configure the system to perform user authentication against Active Directory. The clear-text passwords are unavailable through Active Directory, so we have to use Samba, and the ntlm_auth helper program. In this configuration, we are using Active Directory as an authentication oracle, and not as an LDAP database.
-. Install and configure Samba by editing the `smb.conf` file.
-. Configure FreeRADIUS by editing the relevent modules such as `ntlm_auth` and ms-chap.
-. Join the FreeRADIUS server to the Active Directory domain.
-. Configure Samba to authenticate against Active Directory and test authentications using `winbind` and `ntlm`.
-. Configure FreeRADIUS to use the `ntlm_auth` module for authentication.
+Using ntlm_auth for PAP authentication may not work on recent versions of Samba and Active Directory. If so, just skip to the next section.
-After the PAP authentication has been successful, the next step for sites using Active Directory is to configure the system to perform user authentication against Active Directory. The clear-text passwords are unavailable through Active Directory, so we use Samba, and the `ntlm_auth` helper program. In this configuration, we are using Active Directory as an authentication oracle, and not as an LDAP database.
+Once Samba has been installed on your system, you should edit the smb.conf file, and configure the [global] section to point to your NT server, including hostname and NT domain.
-Samba uses the SMB protocol along with the winbind module to authenticate users against Active Directory. Users are verified using either the PAP or MS-CHAP authentication methods.
-
-Using `ntlm_auth` for PAP authentication may not work on recent versions of Samba and Active Directory. If you have this issue, proceed to the xref:datastores/ad/configure_ntlm_mschap.adoc[Configuring ntlm] section.
-
-== Configuring Samba
-
-Once Samba has been installed on your system, edit the `smb.conf` file, and update the [global] section to point to your NT server, including hostname and NT domain.
-
-=== Configure `/opt/samba/etc/smb.conf` file
-
-The example snippet shown below needs to be modified with your site parameters which includes updating the workgroup, security, and realm fields.
-
-```
# workgroup = NT-Domain-Name
workgroup = MYDOMAIN
...
password server = nt-server-hostname.company.com
...
realm = realm.company.com
-```
+For Samba 4, you also have to set the ntlm authconfiguration variable. It should be set to either yes, or to mschapv2-and-ntlmv2-only. This configuration needs to be set all participating Samba members, and also on (Samba4) AD-DC servers.
-Next, update the ntlm authconfiguration variable for Samba 4 to set the authentication protocol used between the FreeRADIUS and AD servers. This variable can be set to either `yes` or to `mschapv2-and-ntlmv2-only`. This configuration needs to be added to all participating Samba members, and also on (Samba4) AD Domain Controller (DC) servers.
-```
ntlm auth = mschapv2-and-ntlmv2-only
...
-```
-=== Configure `/etc/krb5.conf` file
-
-Edit the `/etc/krb5.conf` file by adding an entry to point to the AD server.
+You may also have to edit the /etc/krb5.conf file, to add an entry that points to the Active Directory Server. This is often not necessary, as Samba can just "figure it out" when Active Directory is also the main DNS server.
-```
[realms]
...
realm.company.com = {
kdc = nt-server-hostname.company.com
}
...
-```
-If the Active Directory server is also the main DNS server, this previous step isn't necessary. Samba resolves the name from a local dns lookup and therefore may require setting `libdefaults` in the `/etc/krb5.conf` file:
+== Start the Samba and Kerberos servers, and as root join the domain:
-```
-[libdefaults]
- default_realm = realm.company.com
- dns_lookup_realm = false
- dns_lookup_kdc = true
-```
+$ net join -U Administrator
+Enter the administrator password at the prompt.
-After all file updates are complete, start the Samba and Kerberos servers.
+Next, verify that a user in the domain can be authenticated:
-== Join the domain as root:
+$ wbinfo -a user%password
+You should see a number of lines of text, followed by authentication succeeded. The next step is to try the same login with the ntlm_auth program, which is what FreeRADIUS will be using:
-From a terminal window on the FreeRADIUS server, enter the command:
-`$ net join -U Administrator`
+$ ntlm_auth --request-nt-key --domain=MYDOMAIN --username=user --password=password
+If all goes well, you should see authentication succeeding (NT_STATUS_OK). You may also see the NT_KEY output, which is needed in order for FreeRADIUS to perform MS-CHAP authentication.
-Enter the administrator password at the prompt.
+== Configuring FreeRADIUS to use ntlm_auth
+Once you have verified that Samba is installed and working correctly, and that the ntlm_auth program works, you can proceed with configuring FreeRADIUS to use ntlm_auth. For initial testing, we will be using the exec module, and will run the exact command line used above.
-== Verify user authentication
+Create or edit the ntlm_auth module configuration. In version 2, this file should be saved as raddb/modules/ntlm_auth. In version 3, it should be saved as raddb/mods-enabled/ntlm_auth. The contents of the file are below, with the fields to edit in bold.
-Authentication must be achieved using the `wbinfo` tool before FreeRADIUS will
-be able to successfully authenticate users performing a MS-CHAPv2 based method.
+ exec ntlm_auth {
+ wait = yes
+ program = "/path/to/ntlm_auth --request-nt-key --domain=MYDOMAIN --username=%{mschap:User-Name} --password=%{User-Password}"
+ }
+This configuration tells the server to run the ntlm_auth program with the user name and password obtained from the Access-Request. You will also have to list ntlm_auth in the authenticate sections of each the raddb/sites-enabled/default file, and of the raddb/sites-enabled/inner-tunnel file:
-.Example winbind
-```
-$ wbinfo -a user%password
-```
+authenticate {
+ ...
+ ntlm_auth
+ ...
+}
+and add the following text for testing purposes only to the top of the users file. In version 3, the "users" file has moved to raddb/mods-config/files/authorize.
-If authentication using winbind works, you'll see a number of lines of text, followed by an authentication succeeded message.
+DEFAULT Auth-Type = ntlm_auth
+This configuration says "for all users, if the authenticate method has not been set, set it to use the ntlm_auth program".
-The next step is to try the same login with the ntlm_auth program, which is what FreeRADIUS will be using:
+Start the server using radiusd -X, and wait for the debugging text to stop scrolling by. If all goes well, you should see the following text:
-.Example ntlm_auth
-```
-$ ntlm_auth --request-nt-key --domain=MYDOMAIN --username=user --password=password
-```
+Ready to process requests.
+In another terminal window on the same machine, type the following command:
+
+$ radtest user password localhost 0 testing123
+If all goes well, you should see the server returning an Access-Accept message, and the window with radtest should print text similar to the following:
+
+rad_recv: Access-Accept packet from host 127.0.0.1 port 1812, length=20
+This text means that authentication succeeded. A few lines above this text, the debug output will also show the exact command line used to run ntlm_auth.
+
+== Configuring FreeRADIUS to use ntlm_auth for MS-CHAP
+Once you have the previous steps working, configuring FreeRADIUS to use ntlm_auth for MS-CHAP is simple. First, delete the testing entry used above from the users file, as leaving it in will break other authentication types. Then, find the mschap module in raddb/modules/mschap file, and look for the line containing ntlm_auth = . It is commented out by default, and should be uncommented, and edited to be as follows. As before, update the fields in bold to match your local configuration.
+
+ntlm_auth = "/path/to/ntlm_auth --request-nt-key --allow-mschapv2 --username=%{mschap:User-Name:-None} --domain=%{%{mschap:NT-Domain}:-MYDOMAIN} --challenge=%{mschap:Challenge:-00} --nt-response=%{mschap:NT-Response:-00}"
+Start the server and use radtest to send an MS-CHAP authentication request. You will need to have version 2.1.10 or later for this to work:
+
+$ radtest -t mschap bob hello localhost 0 testing123
+If everything goes well, you should see the server returning an Access-Accept message as above.
-If authentication using `ntlm` works, you'll see authentication succeeding (NT_STATUS_OK). You may also see the `NT_KEY` output, which is needed in order for FreeRADIUS to perform MS-CHAP authentication.
+If it does not work, double-check the password you entered on the supplicant against the password in Active Directory. If it still does not work, it might be a bug in Samba. Change your version of Samba, either by installing a fixed version, or by repeatedly down-grading it (and testing) until it works.
-Your next step is to configure FreeRADIUS to use xref:datastores/ad/ntlm_mschap.adoc[ntlm with MS-CHAP] to perform all user authentications.
+If it does not work, then it is possible to test authentication with just the ntlm_auth command-line. Look at the FreeRADIUS debug output, and see the arguments passed to ntlm_auth. Copy and paste them to a command-line, and then use that command line for testing. This limited test is often simpler and faster than running a complex test with a full RADIUS server. When this limited test passes, then authentication with FreeRADIUS will work, too.
projects / thirdparty / freeradius-server.git / commitdiff
