Wednesday 15 May 2013

Join Debian Wheezy to Windows Active Directory Domain

While looking for something to keep me busy on a quiet day I decided to work out how to get Debian 7 authenticating against our Active Directory domain. I have been doing this for a few years with our Redhat/CentOS systems but we have a few Debian boxes for variety and as they are small/unimportant/just keep ticking over without issues getting them on the domain has never been a high priority. For Redhat there is a very good and thorough guide HERE which does an excellent job of explaining the options and how to setup various configurations. By contrast this guide is far more focused on a single scenario and nowhere near as detailed - but it should contain everything required to get a fresh Debian Wheezy (7)  install authenticating users using Active Directory accounts as well as local accounts.

Other than authenticating against the Windows domain I also want to ensure that all domain users get the same UID/GID so that sharing files between systems is easier.

The first steps are to ensure that the time is correct on the servers and that DNS is working correctly.
# apt-get install ntp
edit /etc/netp.conf and set the server lines to point to the systems you want to use for time updates then restart ntp and check the current time is correct
# /etc/init.d/ntp restart
# date
Tue May 14 11:03:42 BST 2013

Check that the "hostname -f" command returns the correct fully qualified server host name. If not edit both /etc/hostname and /etc/hosts and then reboot. Also check that another host on your network can ping the machine by hostname and if not then fix your DNS server so it can.

Install samba and winbind:
#  apt-get install samba smbclient samba-common winbind
Start smb service and set it to start up on boot from now on:
# /etc/init.d/samba start
# update-rc.d samba enable

Install Kerberos, backup the original config file and then replace with minimal setup
# apt-get install krb5-user
# cp -p /etc/krb5.conf /etc/krb5.conf.orig
# vi /etc/krb5.conf
replace with the contents below, changing DOMAIN.COM for your domain and DC.DOMAIN.COM for your primary domin controller - if you have more than one domain controller you can have multiple kdc= lines.

 default_realm = DOMAIN.COM
 dns_lookup_realm = false
 dns_lookup_kdc = false
 ticket_lifetime = 24h
 renew_lifetime = 7d
 forwardable = true
  kdc =
  admin_server =
[domain_realm] = DOMAIN.COM = DOMAIN.COM
Clear anything cached and then try to get a kerberos ticket - the first klist should report no credentials, the second klist should show expiry dates for the user's kerberos ticket.
# kdestroy
# klist
# kinit [email protected]
# klist
Your machine can now get tickets from the AD domain successfully. Next we need to join the domain then enable this for login and then sort out the UID's so they match across servers.
# apt-get install libpam-krb5
# cp -p /etc/samba/smb.conf /etc/samba/smb.conf.orig
Now edit /etc/samba/smb.conf and make the following changes. If a variable is not in the config file then add it. ("domain logons = no" controls if this machine can authenticate users for other machines, not if domain users can logon here...):
workgroup = DOMAIN
security = ads
realm =
password server =
domain logons = no
template homedir = /home/%D/%U
template shell = /bin/bash
winbind enum groups = yes
winbind enum users = yes
winbind use default domain = yes
domain master = no
local master = no
prefered master = no
os level = 0
idmap config *:backend = tdb
idmap config *:range = 11000-20000
idmap config DOMAIN:backend = rid
idmap config DOMAIN:range=10000000-19000000
And then comment out the entire [homes], [printers] and [print$] sections at the bottom (unless you plan to use them...)

Stop and restart the services:

# /etc/init.d/winbind stop
# /etc/init.d/samba restart
# /etc/init.d/winbind start
Then try to join the domain and test it is all working(replace dc with the hostname of your domain controller):
# net join -S dc -U administrator
# net ads testjoin
# net ads info
# wbinfo -u
# wbinfo -g
Check that the wbinfo commands show users and groups from active directory. For some reason my Winbind shuts down when i join a domain so I get an error "Error looking up domain users" - starting winbind again seems to fix this and it has not died for me since. Hopefully you have now joined the domain and if you look on your domain controller you should see the computer on the domain. Next we need to setup authentication so you can log in using domain credentials.

Edit /etc/nsswitch.conf to add winbind for looking up passwords and groups
# vi /etc/nsswitch.conf
passwd:    compat winbind
group:       compat winbind
shadow:    compat
And check that domain users and groups are returned by the following commands:

# getent passwd
# getent group 
Note that if you have a problem with these two getent commands not returning any domain level records check your smb.conf file for the idmap syntax - for some reason the version of the config file I received with samba had a different structure for the idmap line that stopped getent working. Entering it as shown above makes these two command work.

Finally set the system up to automatically create home folders for users when they first log on by adding the following two lines (if not already in the file).
# vi /etc/pam.d/common-session
session required
session required umask=0022 skel=/etc/skel

You should now be able to log in to the system using a domain username/password combination and a home folder will be automatically created for you on first logon. If the backend=rid part is working then the user ID on each system should be the same for all users making it easier to share files between machines. you can check the UID with the "id" command which will show the user id (UID), group id (GID) and all the groups that the current user is a member of.

My next steps are to add a domain administrators group to the visudo permissions file to allow jumping to root when required and then to block root access by ssh.

You can also now list windows fileshares with:

$ smbclient -L WindowsServer -k
and mount them with:
$ sudo mount ­t cifs //WindowsServer/Share /mnt/WindowsServerShare ­-o username=AD_UserName
Although this will only give you read only access unless you jump to root. Adding it to your fstab file will give you a more useable share.


  1. Thank you, I was having trouble with getting this to work after upgrading a server. Following this has made everything work properly now.

  2. Thank you very much. I just tried it on a test machine and it worked really well. I will implement this on my other Linux machines too!

  3. Great documentation!! I ran into one hitch that took me forever to figure out, however. libnss-winbind had to be installed also on my system for the getent commands to work.

  4. Thank you for the documentation. It is concise and accurate. Two questions came up for me since I cut my teeth as a Windows admin and Debian admin is pretty new to me, so I thought I'd contribute here.

    1) Multiple domain controllers: smb.conf, accepts comma-delimited values on the following line:

    password server =

    So if you have multiple DCs, indicate them this way:

    password server =,,

    2) Adding groups to sudoers:

    If you want to bless Domain Admins as sudoers, the line can be added through visudo as follows:

    %domain\ admins ALL=(ALL:ALL) ALL

    * The % symbol represents a group.
    * The word "domain" is literal. Don't substitute your domain name.
    * We've already specified that groupname lookup should include domain groups, via referencing winbind in nsswitch.conf.
    * The backslash+space is just a space but it has to be approached with the backslash as an escape character.

  5. Great tutorial, worked perfectly on every debian system I have.
    The only thing I changed, in my case, is in the umask applied on homedir creation.. I would recommend to use umask=0077 for security and privacy reason.
    Thanks a lot for you work.

  6. Thanks for the job!

  7. Great tutorial thanks.

    If you want limit access using ssh only to root and domain admins you have to edit /etc/pam.d/shh and add the line:

    session required onerr=fail item=group sense=allow file=/etc/

    Then you have to create and edit file /etc/ and write in:

    domain admins

    Of course this is a list then you can put here also other groups.

    1. File corrected is /etc/pam.d/shhd


  8. Moreover if you want enable some groups to use sudo command BUT avoid to use dangerous command like su, you launch command visudo and add lines:

    Cmnd_Alias NSHELLS = /bin/sh,/bin/bash
    Cmnd_Alias NSU = /bin/su
    Cmnd_Alias NPKG = /usr/bin/apt-get,/usr/bin/dpkg

    %domain\ admins ALL=ALL, !NSHELLS, !NSU, !NPKG

    1. Thanks for the comments Anon! don't forget that you need to block more than just those 2 shells (look in /etc/shells for a full list) and that things like vi can execute shell commands as root even if blocked by sudo.

      I was not aware of the way to restrict logins to a group of users though - that will come in handy. Previously I've used active directory itself to set which users are allowed to login to a host but this would be a lot quicker for a one off change.

  9. Hello everyone, i am new in linux. Is there config for offline cache? Thank you.

  10. Hello,
    Thanks for this tutorial, but I stuck on editing "common-session" file.
    Do I need to add these two lines in this file or replace some other setting?

    My default "common-session" file:
    # here are the per-package modules (the "Primary" block)
    session [default=1]
    # here's the fallback if no module succeeds
    session requisite
    # prime the stack with a positive return value if there isn't one already;
    # this avoids us returning an error just because nothing sets a success code
    # since the modules above will each just jump around
    session required
    # and here are more per-package modules (the "Additional" block)
    session optional minimum_uid=1000
    session required
    session optional

    Best Regards

    1. Hi, I could have been clearer there... You need to add the two lines to the file - however you already have "session required" so I would just put the line underneath so the end of your file looks like this:

      # and here are more per-package modules (the "Additional" block)
      session optional minimum_uid=1000
      session required
      session required umask=0022 skel=/etc/skel
      session optional

      Best of luck!

  11. Great document! Your a live saver :-)
    I just missed one package which must be installed to get it working:

    apt-get install libnss-winbind

    The winbind NSS library no longer comes with winbind and you need it.

    I also had the same error

    The error "Error looking up domain users" regarding winbind which in my case also happend once's.

  12. Thanks for the tut.

    Just a note that helped fix the ads error that could not connect to DC server. I added the domain controllers to /etc/hosts file. That allowed successful connection and the rest works flawlessly.

  13. IT Jedi, Genius....Super Genius.!

  14. Hello,

    First thank you for you tutorial.
    On my hand it work fine until the line:
    # net join -S dc -U administrator
    after entering the administrator password I got the following error message:
    Failed to join domain: failed to join domain 'XXX.YYYY' over rpc: NT_STATUS_NOT_SUPPORTED

    I have tried several times and one time a second message came up:
    ADS join did not work, falling back to RPC...

    I have been searching on the web for hours without any improvement.
    Any help would be greatly appreciated!

    FYI, the command line # net ads info returns the following information:
    LDAP server:
    LDAP server name:
    Realm: XXX.YYYY
    Bind Path: dc=XXX,dc=YYYY
    LDAP port: 389
    Server time: Thu, 15 Oct 2015 17:01:34 CEST
    KDC server:
    Server time offset: 0

    And I am on a raspberry pi using the OS Raspbian

    PS: I am wondering if I could use LDAP instead of RPC since I think that my dc doesn't know the rpc protocol.

    Thank you in advance,

  15. Hello Neal,

    Thanks for the great tut. I need some help. Please do sir.

    When I ran net join, I was shown "

    Using short domain -- ***
    Joined 'your-pi' to dns domain '***.***'
    No DNS domain configured for your-pi. Unable to perform DNS update.

    After this the computer object is created in AD. I can ping everything IP / hostnames from here to there and everywhere in domain.

    But, I cannot login with my domain creds.
    I have kdestroyed and kinit tickets with my and other domain IDs. ticekts get created and all but still I cannot logon.

    I get incorrect password.

    What do you think?

  16. That allowed successful connection and the rest works flawlessly.