docs: update howto/Datastores/Active Directory install/configure instructions.
Added 3 sub-sections - Integrating AD, Configuring ntlm, Installing winbind
**** xref:modules/sqlippool/insert.adoc[Inserting IPs into SQL]
** xref:datastores/index.adoc[Setting up Datastores]
-*** xref:datastores/ad.adoc[Active Directory]
+*** xref:datastores/ad/index.adoc[Active Directory]
+**** xref:datastores/ad/samba.adoc[Using Samba]
+**** xref:datastores/ad/ntlm_mschap.adoc[Configuring ntlm]
+**** xref:datastores/ad/winbind.adoc[Installing Winbind]
*** xref:datastores/ldap.adoc[LDAP]
*** xref:datastores/redis.adoc[Redis]
*** xref:datastores/sql.adoc[SQL]
+++ /dev/null
-= Active Directory (AD)
-
-== What is it?
-
-== How to connect
-
-== Why use AD
-
-== Setting up an AD Datastore
--- /dev/null
+= Active Directory (AD)
+
+Microsoft Active Directory (AD) is a directory service that stores and manages user accounts, credentials, and other network resources within a domain. The AD server receives and processes access requests from the FreeRADIUS server. AD provides a centralized location for managing authentications and access by:
+
+* authenticating users by verifying their identity and credentials, and
+* authorizating resource access to that user by applying policies to restrict access to data.
+
+== What is it?
+
+When FreeRADIUS is integrated with Active Directory, the AD server functions as an “authentication oracle.” FreeRADIUS doesn’t store user credentials internally, but instead, passes these credentials to AD for verification.
+
+For PAP and MS-CHAP based authentications, FreeRADIUS uses tools such as Samba, including winbind, and the `ntlm_auth` helper program to communicate with the AD server.
+
+=== FreeRADIUS Active Directory Authentication Process
+
+The authentication process flow of steps to authenticate a user is as follows:
+
+. FreeRADIUS receives a set user credentials requesting access to a network resource or service, and forwards this information to the Active Directory service via Samba.
+. AD verifies the submitted user's credentials such as name and password, against the stored credentials in the datastore.
+. AD determines the access level for the verified user and passes the authorization result back to FreeRADIUS via Samba.
+. FreeRADIUS grants access to the user according to the information received from AD i.e. user's rights and permissions to access a network resource.
+
+
+== How to connect
+
+For the following example, the FreeRADIUS server is installed and operational with basic authentication working (pap/chap). The FreeRADIUS server must also have Samba installed to be able to join the domain (or samba realm).
+
+*Join the FreeRADIUS server to AD with `net ads join` command:*
+
+`sudo /opt/samba4.x/bin/net ads join -U Administrator`
+
+Enter the administrator password at the prompt.
+
+*Add the following line to the [global] section of the `smb.conf` file:*
+
+`ntlm auth = mschapv2-and-ntlmv2-only`
+
+This setting allows for MS-CHAPv2 authentications against the AD using the ntlm authorization process.
+
+*Configure Freeradius to use mschapv2 with ntlmv1 disabled globally by setting this in /mods-available/mschap:*
+
+
+```
+mschap {
+
+.....
+
+ntlm_auth = "/path/to/ntlm_auth --allow-mschapv2 --request-nt-key
+--username=%{mschap:User-Name} --domain=WINDOWSDOMAIN
+--challenge=%{%{mschap:Challenge}:-00}
+--nt-response=%{%{mschap:NT-Response}:-00}"
+```
+
+This configuration works without modification to Freeradius.
+
+OR use winbind
+
+```
+winbind_username = "%{mschap:User-Name}"
+winbind_domain = "%{mschap:NT-Domain}"}
+.....
+```
+
+
+This configuration requires Freeradius to be built with winbind auth. For example, on linux-based systems, you rebuild the packages and add the winbind libraries to the ./configure path. See xref:datastores/ad/winbind.adoc[Installing winbind] for more details.
+
+=== Testing
+
+If everything works successfully, you'll see an entry in the AD Domain Controller's audit log similar to the snippit below:
+
+
+```
+{"timestamp": "some-date0", "type": "Authentication", "Authentication":
+{"version": {"major": 1, "minor": 0}, "status": "NT_STATUS_OK",
+"localAddress": "ipv4:xxx.xxx.xxx.xxx", "remoteAddress":
+"ipv4:xxx.xxx.xxx.xxx:58046", "serviceDescription": "SamLogon",
+"authDescription": "network", "clientDomain": "WINDOWSDOMAIN",
+"clientAccount": "some-user", "workstation": "\\\\SOME-HOST",
+"becameAccount": "some-user", "becameDomain": "WINDOWSDOMAIN",
+"becameSid": "SOME-SID", "mappedAccount": "some-user", "mappedDomain":
+"WINDOWSDOMAIN", "netlogonComputer": "SOME-HOST",
+"netlogonTrustAccount": "SOME-HOST$", "netlogonNegotiateFlags":
+"0x610FFFFF", "netlogonSecureChannelType": 2, "netlogonTrustAccountSid":
+"somesid, *"passwordType": "MSCHAPv2"*}}
+```
+
+Without the "--allow-mschapv2" setting, you would see "passwordType":"NTLMv1"
+
+== Why use Active Directory?
+
+When FreeRADIUS is integrated with Active Directory, only authorized users gain access to network resources, enhancing the overall security of your network. Active Directory functions as a centralized datastore for user accounts and security policies, simplifying user management and access rights across the network. By integrating with AD, FreeRADIUS can leverage the exisiting infrastructure and be scaled up for larger systems.
+
+== xref:datastores/ad/samba.adoc[Using Samba]
+
+FreeRADIUS uses Samba to integrate with Active Directory for authentication. For authorization such as group membership, FreeRADIUS can query Active Directory over LDAP.
+
+For the next steps, see the following:
+
+* xref:datastores/ad/samba.adoc[Using Samba]
+* xref:datastores/ad/ntlm_mschap.adoc[Configuring ntlm]
+* xref:datastores/ad/winbind.adoc[Installing winbind]
--- /dev/null
+= Configuring 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 use the exec module, and will run the exact command line used in the previous testing step.
+
+Edit the `ntlm_auth` module configuration which saved as raddb/mods-enabled/ntlm_auth. The example snippet shown below needs to be updated with your site parameters which includes the path and domain.
+
+```
+
+ 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:
+
+```
+authenticate {
+ ...
+ ntlm_auth
+ ...
+}
+```
+
+== Testing `ntlm_auth`
+
+Add the following text for testing purposes only to the top of the users file. The "users" file is located at `raddb/mods-config/files/authorize`.
+
+```
+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".
+
+Start the server using `radiusd -X`, and wait for the debugging text to stop. If all goes well, you'll' see the following text:
+
+Ready to process requests.
+
+In another terminal window on the same machine, type the following command:
+
+`$ radtest user password localhost 0 testing123`
+
+If successful, you'll see the server returning an Access-Accept message, and the window with radtest prints 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.
+
+`$ 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 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.
+
+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.
+
+== Password changes
+
+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.
--- /dev/null
+= Integrating with Active Directory (AD)
+
+The main steps to integrate FreeRADIUS authentication with Active Directory are:
+
+. 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.
+
+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.
+
+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
+...
+# Security mode. Most people will want user level security. See
+# security_level.txt for details.
+ security = ads
+# Use password server option only with security = server
+ password server = nt-server-hostname.company.com
+...
+ realm = realm.company.com
+```
+
+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.
+
+```
+[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:
+
+```
+[libdefaults]
+ default_realm = realm.company.com
+ dns_lookup_realm = false
+ dns_lookup_kdc = true
+```
+
+After all file updates are complete, start the Samba and Kerberos servers.
+
+== Join the domain as root:
+
+From a terminal window on the FreeRADIUS server, enter the command:
+
+`$ net join -U Administrator`
+
+Enter the administrator password at the prompt.
+
+== Verify user authentication
+
+Authentication must be achieved using the `wbinfo` tool before FreeRADIUS will
+be able to successfully authenticate users performing a MS-CHAPv2 based method.
+
+.Example winbind
+```
+$ wbinfo -a user%password
+```
+
+If authentication using winbind works, you'll see a number of lines of text, followed by an authentication succeeded message.
+
+The next step is to try the same login with the ntlm_auth program, which is what FreeRADIUS will be using:
+
+.Example ntlm_auth
+```
+$ ntlm_auth --request-nt-key --domain=MYDOMAIN --username=user --password=password
+```
+
+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.
+
+Your next step is to configure FreeRADIUS to use xref:datastores/ad/ntlm_mschap.adoc[ntlm with MS-CHAP] to perform all user authentications.
--- /dev/null
+= Installing Winbind
+
+To integrate linux-based systems with a Windows Active Directory domain, you need to install Winbind.
+
+== Build winbind from packages
+
+*Debian or Ubuntu*
+`apt-get install -y samba winbind krb5-user`
+
+*RHEL or Rocky or Linux based systems
+`yum install -y samba-winbind krb5-workstation`
+
+== Restart the winbind service:
+
+ `systemctl stop winbind`
+ `systemctl start winbind`
+
+A description of how to test and troubleshoot winbind is provided in the
+[Troubleshooting guide].
To configure a datastore with FreeRADIUS, you'll need to edit the FreeRADIUS configuration files and enable the relevant modules. This section outlines the supported datastores, how to connect, and implementations. See the following sub-sections for your specific datastore application instructions:
-* xref:datastores/ad.adoc[Active Directory]
+* xref:datastores/ad/index.adoc[Active Directory]
* xref:datastores/ldap.adoc[LDAP]
* xref:datastores/redis.adoc[Redis]
* xref:datastores/sql.adoc[SQL]
projects / thirdparty / freeradius-server.git / commitdiff
