This page describes how to configure Linux systems to connect to an Active Directory domain as the database for users and groups.

<<TableOfContents>>

== sssd or winbind - an introduction ==

'''TL;DR:''' Try [[#Manual_configuration_of_sssd]] (if the automated [[SOE]] does not work for you)

There are two main options for joining Linux machines to AD domains:
 * [[https://sssd.io/|sssd]], System Security Services Daemon
 * [[https://www.samba.org/samba/docs/current/man-html/winbindd.8.html|winbind]] (part of Samba)

They're mostly interchangeable, but we've been using sssd except where it's buggy. When switching from one to the other, be sure to purge the old one to avoid confusion.

Both `sssd` and `winbind` are services which run in the background and provide a source of:
 * user IDs and information listing, similar to the contents of the UNIX `/etc/passwd` file
 * group IDs and membership, similar to the contents of the UNIX `/etc/group` file

Active Directory is based on the Windows security model, which is somewhat more complex than the POSIX standard implemented in Linux, so this software is used to map the Windows/AD model onto the Linux/UNIX/POSIX equivalents.

=== Manual configuration of sssd ===

Configuring `sssd` manually is recommended. (because using [[https://www.freedesktop.org/software/realmd/|realmd]] to do it has been a bit unreliable in our environment - see the next section)

There is a very informative [[https://access.redhat.com/articles/3023951|Red Hat article]] about configuring `sssd` manually. The following instructions are a functional adaptation. For a more detailed understanding of what these config files and options mean, please start by reading the manpages for sssd, sssd-ad, sssd-krb5, sssd-ldap, sssd.conf, krb5.conf and smb.conf and the above article.

These instructions are confirmed working on Linux Mint 19 (Tara), using `sssd` version 1.16.1 and `samba-common-bin` package version 4.7.6.

 1. Install the necessary packages and uninstall the bad ones: {{{
apt-get install samba-common-bin samba-dsdb-modules sssd sssd-ad sssd-krb5 sssd-ldap sssd-tools krb5-user krb5-doc libpam-sss libnss-sss adcli libsasl2-modules-gssapi-mit
apt-get remove winbind realmd libpam-krb5 libpam-ldap libpam-winbind libnss-ldap libnss-winbind
}}}
 2. Remove any configuration files if they exist and stop services: {{{
mv /etc/samba/smb.conf /etc/samba/smb.conf.old
mv /etc/nsswitch.conf /etc/nsswitch.conf.old
rm /etc/krb5.conf /etc/krb5.keytab /etc/sssd/sssd.conf
systemctl stop sssd winbind samba-ad-dc smbd nmbd
}}}
 3. Put the following into various config files:
  * `vim /etc/sssd/sssd.conf` {{{
[sssd]
config_file_version = 2
domains = ad.v.ucc.asn.au
services = nss, pam, pac

# domain configuration: see manpages sssd.conf, sssd-ldap, sssd-krb5 and sssd-ad
# see https://access.redhat.com/articles/3023951
# needs correct configution for: /etc/nsswitch.conf /etc/samba/smb.conf /etc/resolv.conf `pam-auth-update`
[domain/AD.V.UCC.ASN.AU]
enumerate = true
id_provider = ad
auth_provider = ad
chpass_provider = ad
access_provider = ad
ldap_id_mapping = false

cache_credentials = true
# if you want to use a custom CA certificate for AD
#ldap_tls_cacert = /etc/sssd/ad.v.ucc.asn.au_ca.cert
# or just allow invalid (self-signed) certificates
ldap_tls_reqcert = allow

# allow local users to be included in AD groups
ldap_rfc2307_fallback_to_local_users = true

# Kerberos konfiguration - see also /etc/krb5.conf
#krb5_use_kdcinfo = true  # let sssd tell krb5 what to do
krb5_realm = AD.V.UCC.ASN.AU
krb5_keytab = /etc/krb5.keytab

# which attributes to use for AD object to POSIX mappings
#ldap_user_name = uid
#ldap_user_uid_number = uidNumber
#ldap_user_gid_number = gidNumber
#ldap_user_object_class = user
#ldap_schema = ad
}}}
  * `vim /etc/nsswitch.conf` {{{
# /etc/nsswitch.conf

passwd:         compat systemd sss
group:          compat systemd sss
shadow:         compat sss
gshadow:        files

hosts:          files mdns4_minimal [NOTFOUND=return] dns myhostname
networks:       files

protocols:      db files
services:       db files sss
ethers:         db files
rpc:            db files

netgroup:       nis sss
}}}
  * `vim /etc/krb5.conf` {{{
[libdefaults]
    default_realm = AD.V.UCC.ASN.AU
    dns_lookup_realm = true
    dns_lookup_kdc = true
    rdns = false
    ticket_lifetime = 24h
    renew_lifetime = 7d
    forwardable = yes
}}}
  * `vim /etc/samba/smb.conf` {{{
[global]
        realm = AD.V.UCC.ASN.AU
        workgroup = VUCC
        security = ads
        client signing = mandatory
        client use spnego = yes
        tls enabled = yes
        kerberos method = secrets and keytab
        dedicated keytab file = /etc/krb5.keytab
        log file = /var/log/samba/%m.log
}}}
 4. Run `pam-auth-update` and check that `SSS authentication` is enabled and that `winbind authentication` (if present) is disabled.
 5. Create the machine account in AD and produce a keytab for sssd containing the machine account credentials. If using a user other than `Administrator`, ensure they have sufficient privileges to join a machine to the domain. {{{
rm /etc/krb5.keytab
kinit Administrator
net ads join --no-dns-updates -k
# verify the machine account credentials are in the keytab:
klist -k
}}}
 6. Start the necessary services: {{{
systemctl start sssd
}}}
 7. Verify that you can see the correct user and group info using `getent passwd` and `getent group` respectively. The output format is equivalent to the `/etc/passwd` and `/etc/group` files.

==== Automatic configuration of sssd using realmd ====
'''Note''': `realmd` is a misnomer - it is not a daemon but simply a utility which automatically generates configuration files for `sssd` or `winbind`.

See the [[https://freedesktop.org/software/realmd/docs|official realmd website]] for more information.

Realmd is supposedly able to generate valid configuration files and automatically detect the necessary configuration settings, and this might work when joining a Linux machine to a normal, functional and correctly configured AD domain using Windows domain controllers, but in the case of the VUCC domain it simply fails to work.

Installation instructions:
 1. Install packages: `apt install realmd krb5-user sssd-ad sssd-krb5 sssd-tools sssd-ldap samba-common-bin adcli libnss-sss libpam-sss`
 2. Test to make sure you can connect to the domain: `realm discover ad.v.ucc.asn.au`
 3. Join to the domain using `realm join -v -U <user> ad.ucc.gu.uwa.edu.au`
   * realmd defaults to using sssd, which is fine
   * It installs any necessary packages.
   * It generates the configuration files `/etc/krb5.conf`, `/etc/samba/smb.conf`, `/etc/sssd/sssd.conf`, modifies `/etc/nsswitch.conf`, creates a machine account on the domain and populates `/etc/krb5.keytab` with machine account credentials, and configures PAM to use SSS authentication.
    * The automatically generated configurations are not very clean, contain redundant information and are broken.
    * Comment the line `use_fully_qualified_names = True` in `/etc/sssd/sssd.conf`
 4. It might just work - if not then verify the config files are correct according to the [[#Manual_configuration_of_sssd|manual instructions]], or just give up and do it manually.

=== Manual configuration of winbind ===

Based on the instructions from [[https://wiki.samba.org/index.php/Setting_up_Samba_as_a_Domain_Member]] and [[https://wiki.samba.org/index.php/Authenticating_Domain_Users_Using_PAM]]
Before configuring the domain ensure the following:
 * Install the required packages: `apt install samba winbind krb5-user libpam-krb5 libpam-winbind libnss-winbind`

 * Ensure the system is configured according to the [[StandardOperatingEnvironment|SOE]].

 * edit `/etc/krb5.conf` to point to the new domain:
 . {{{
   [libdefaults]
	default_realm = ad.ucc.gu.uwa.edu.au
	dns_lookup_realm = false
	dns_lookup_kdc = true
}}}

 * Make the following `/etc/samba/smb.conf`:
 . {{{
[global]
# Configure the domain infomation
        security = ads
        realm = ad.ucc.gu.uwa.edu.au
        workgroup = UCCDOMAYNE

# use winbind to map users and groups
        winbind enum users = yes
        winbind enum groups = yes
        winbind use default domain = yes
        kerberos method = secrets and keytab

#Config gid/sid mapping based on AD attributes
        winbind nss info = rfc2307

        idmap config * : backend = tdb
        idmap config * : range = 13000-17999
        
        #idmap config for UCCDOMAYNE
        idmap config UCCDOMAYNE:backend = ad
        idmap config UCCDOMAYNE:schema_mode = rfc2307
        idmap config UCCDOMAYNE:range = 1-999999
        idmap config UCCDOMAYNE:unix_nss_info = yes
        idmap config UCCDOMAYNE:unix_primary_group = yes

}}}

 * Join the machine to the domain with: `net ads join -U <username>`.

 * configure pam using `pam-auth-update` and enable `Winbind NT/AD authentication`.

 * configure `nsswitch.conf`
 . {{{
# /etc/nsswitch.conf
#
# Example configuration of GNU Name Service Switch functionality.
# If you have the `glibc-doc-reference' and `info' packages installed, try:
# `info libc "Name Service Switch"' for information about this file.

passwd:         compat winbind
group:          compat winbind
shadow:         files
gshadow:        files

hosts:          files mdns4_minimal [NOTFOUND=return] dns
networks:       files

protocols:      db files
services:       db files 
ethers:         db files
rpc:            db files

netgroup:       nis 

}}}
 * start the services:
 . {{{
winbindd
nmbd
smbd
}}}

 * Make sure the computer can fetch the domain users and groups with: 
 . {{{
wbinfo -g` and `wbinfo -u`
}}}