DokuWiki

It's better when it's simple

User Tools

Site Tools


auth:ad

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
auth:ad [2015-04-23 22:27] 216.191.119.186auth:ad [Unknown date] (current) – removed - external edit (Unknown date) 127.0.0.1
Line 1: Line 1:
-====== Active Directory Authentication ====== 
  
-| :!: Since the release 2013-05-10 “Weatherwax”\\ see [[plugin:AuthAD]] plugin page\\ \\ :!: For releases 2012-10-13 “Adora Belle” and older\\ see info below| 
- 
-This [[:auth|auth backend]] allows DokuWiki to authenticate against an Active Directory Server. 
- 
-While Active Directory authentication can be   set up with the default [[LDAP]] backend it should be easier to do with this dedicated auth backend. It makes use of the excellent [[http://adldap.sourceforge.net/|adLDAP library]] and is based on the work by James Van Lommel. You do not need to download the adLDAP library yourself, it is included with DokuWiki. 
- 
-In addition it allows the use of NTLM and Kerberos based Single-Sign-On .  
- 
-This backend is included in DokuWiki since version rc2009-12-02 "Mulled Wine". 
- 
-You will also need to enable LDAP on the PHP server. LDAP is not enabled by default in PHP. This can be as easy as editing php.ini in most of the cases, however you might need to check your php installation to enable the LDAP support if you are using some specialty server installation. 
- 
-===== Server Configuration ===== 
- 
-Your server configuration must meet the requirements of the [[http://adldap.sourceforge.net/|adLDAP]] PHP library. 
- 
-If you're using Apache on Ubuntu or Debian, just install the ''php5-ldap'' package. On CENTOS install ''php-ldap''. If you're using Apache on another distro, follow [[http://adldap.sourceforge.net/wiki/doku.php?id=apache|this guide]].\\ 
-Installing ''php5-ldap'' also works on SLES. 
- 
-For MS IIS7 server ''php-ldap'' and ''php-openssl'' extensions needs to be installed (the second one only when SSL support required). For ''php-openssl'' dependency dlls ''ssleay32.dll'' and ''libeay32.dll'' needs to be available in your system too. When accessing AD using SSL, you must create file ''ldap.conf'' in ''C:\OpenLDAP\sysconf'' with line ''TLS_REQCERT never''. which disables AD certificate checking when making LDAP call. **WARNING!** This could lead to Man-In-The-Middle attacks, so probably better solution is configure valid certificate using this file (more on [[http://linux.die.net/man/5/ldap.conf]]). 
- 
-If you're using a web server other than Apache or IIS7, you have to figure it out yourself. :( Please update this article if you succeed. 
- 
-===== Configuration ===== 
- 
-(Ensure that authad is enabled  in '''conf/plugins.local.php'' with ''$plugins['authad'   = 1;''.) 
- 
-To avoid having them overridden by the config manager it is recommended to place the configuration in ''conf/local.protected.php''. 
- 
-You probably want to set at least these options: 
- 
-<code php> 
-  <?php 
-  // general DokuWiki options 
-  $conf['useacl'        = 1; 
-  $conf['disableactions'] = 'register'; 
-  $conf['authtype'      = 'ad'; 
- 
-  // configure your Active Directory data here 
-  $conf['auth']['ad']['account_suffix'    = '@my.domain.org'; 
-  $conf['auth']['ad']['base_dn'           = 'DC=my,DC=domain,DC=org'; 
-  $conf['auth']['ad']['domain_controllers'] = 'srv1.domain.org, srv2.domain.org'; //multiple can be given 
-</code> 
- 
-Optionally the following parameters can be given: 
- 
-<code php> 
-  $conf['auth']['ad']['ad_username'       = 'root'; 
-  $conf['auth']['ad']['ad_password'       = 'pass'; 
-  $conf['auth']['ad']['sso'               = 1; 
-  $conf['auth']['ad']['real_primarygroup' = 1; 
-  $conf['auth']['ad']['use_ssl'           = 1; // Don't have ssl/tls options enabled at the same time.  
-  $conf['auth']['ad']['use_tls'           = 1; // Only one of them. 
-  $conf['auth']['ad']['debug'             = 1; 
-  $conf['auth']['ad']['recursive_groups'  = 1; // If number of groups in AD is large switching to 0 will improve performance, but indirect membership will not work 
-  $conf['auth']['ad']['additional'        = 'department,office'; // additional attributes to fetch 
-  // warn user about expiring password this many days in advance (in version 2012-03-10 and higher): 
-  $conf['auth']['ad']['expirywarn'        = 5; 
-</code> 
- 
-''ad_username'' and ''ad_password'' are e.g. required to enable user [[:subscription|email subscriptions]]. This account binds to the AD for querying user details. 
- 
-Use this code snippet in local.protected.php to set superuser rights: 
- 
-<code php> 
-$conf['manager'  = '@LDAPGROUPNAME'; 
-$conf['superuser'] = '@LDAPGROUPNAME'; 
-</code> 
- 
-AD group names should be preceded with "@" and all spaces should be replaced with underscores.  For example, if my AD group is called "Internal DokuWiki Admins", it should be "@Internal_DokuWiki_Admins" in DokuWiki.  Any additional LDAP syntax is unneeded (e.g. all "CN=", "DN=", etc.).  Only the name of the group is needed. 
- 
-Any other options given in $conf['auth']['ad'] are directly passed to the adldap library. Please refer to the [[http://adldap.sourceforge.net/wiki/doku.php?id=api|adLDAP documentation]] for a detailed description of what other options might be available. 
- 
-In combination with Single-Sign-On, you can also add Windows domain specific setups. E.g. to authenticate against different Active Directory Servers depending on the NTLM or Kerberos Domain of a given user. The (lowercased) Domain just has to be used as a subkey to the ''$conf['auth']['ad']'' setting. E.g. to identify all users coming from the ''Foobar'' Windows Domain using a non-default AD Server and user just put the following additional lines into your config: 
- 
-<code php> 
-  $conf['auth']['ad']['foobar']['account_suffix'    = '@foobar.domain.org'; 
-  $conf['auth']['ad']['foobar']['base_dn'           = 'DC=foobar,DC=domain,DC=org'; 
-  $conf['auth']['ad']['foobar']['domain_controllers'] = 'otherad.domain.org'; 
-  $conf['auth']['ad']['foobar']['ad_username'       = 'otherroot'; 
-  $conf['auth']['ad']['foobar']['ad_password'       = 'otherpass'; 
-</code>   
- 
-If you have an organisation with multiple DCs under a single parent, you may need to connect to port 3268, rather than the default port 389. Otherwise, users from the remote DC may not show up as members of any groups. The easiest way to do this is to change adLDAP.php in the source code, because the base call to ldap_connect needs port as a separate argument (line 364 in inc/adLdap.php version 3.3.2). 
-===== User Profile and Password Changes ===== 
- 
-Users can change their user details (name, email and passwords) using the profile button. This may require to set up a privileged user through the ''ad_username'' and ''ad_password'' options. Password changing is only supported via SSL or TLS. See [[http://adldap.sourceforge.net/wiki/doku.php?id=ldap_over_ssl|LDAP over SSL]] in the adLDAP documentation. 
- 
-Please note that DokuWiki's auto generated passwords do not match with the Active Directory default [[http://technet.microsoft.com/en-us/library/cc875814.aspx|password policy]]. Either adjust your AD password policy or disable the "Forget Password" option using the [[config:disableactions]] config option. 
- 
- 
- 
-===== Group and User Names ===== 
- 
-Group and user names are cleaned up internally so they might differ from what is configured in your Active Directory server. Spaces are replaced with underscore and backslashes and hash symbols are removed. 
- 
-Example: ''Domain Users'' becomes ''Domain_Users'' in DokuWiki.  When you edit your ACLs manually, remember the correct encoding: ''Domain%5fUsers'' The "%5f" represents an underscore. 
- 
-Keep this in mind when specifying users and groups in [[:ACL]] setup or configuration. 
- 
-===== Enabling SSO ===== 
- 
-Single Sign On (SSO) means that DokuWiki will use your Windows login name to identify you without the need for you to log in. This relies on the server setting the ''REMOTE_USER'' environment variable. The ad backend then will use this username to fetch additional data like your group membership. 
- 
-To make this work you need to enable the ''sso'' setting in ''local.protected.php'' and most probably also need to setup a management account with enough permissions to fetch the user info: 
- 
-<code php> 
-$conf['auth']['ad']['sso'] = 1; 
-$conf['auth']['ad']['ad_username'] = 'MyManager'; 
-$conf['auth']['ad']['ad_password'] = 'ManagerPass'; 
-</code> 
- 
-Additonally some settings have to be made for your server and the used Browser. 
- 
-==== Web Server ==== 
- 
-=== NTLM on IIS 7.5 === 
- 
-  - Open the IIS configuration console (Start -> Internet Information Services (IIS) Manager) 
-  - Click on the site or virtual directory 
-  - Double-click on IIS -> Authentication 
-  - Click "Anonymous Authentication" and disable it 
-  - Click "Windows Authentication" and enable it (Note: If you do not see Windows Authentication, you need to install it via "Turn Windows features on or off" in Control Panel) 
- 
-=== NTLM on IIS 6 === 
- 
-First configure IIS to use the Windows Logon for authentication (see screenshots): 
- 
-  - Open the IIS configuration console using "Start" -> "Run" -> ''inetmgr'' 
-  - Right click on the "Default Web Site" entry and choose "Properties"  
-  - Switch to the "Directory Security" tab 
-  - Click the "Edit" button on "Anonymous access and authentication control". 
-  - Disable "Anonymous access" 
-  - Enable "Integrated Windows Authentication" 
- 
- 
-{{:auth:step1.jpg?330}} {{:auth:step2.jpg?230}} {{:auth:step3.jpg?170}} 
- 
-Then make sure NTLM is used as authentication protocol. This has to be done on the commandline: 
- 
-  - Open a command line: "Start" -> "Run" -> ''cmd'' 
-  - Change to the admin script directory: ''cd \Inetpub\Adminscripts'' 
-  - Check the current protocol: ''cscript adsutil.vbs get w3svc/NTAuthenticationProviders'' 
-  - if it doesn't say NTLM, set it: ''cscript adsutil.vbs set w3svc/NTAuthenticationProviders "NTLM"'' 
- 
-Now restart IIS. 
- 
-=== NTLM on Apache (Windows) === 
- 
-Download [[http://sourceforge.net/projects/mod-auth-sspi/]] 
-Copy the mod_auth_sspi.so file into your apache modules directory. 
-Add into httpd.conf: 
-<code> 
-LoadModule sspi_auth_module modules/mod_auth_sspi.so  
- 
-<Directory "c:/wamp/www/"> 
-    AuthName "My Intranet" 
-    AuthType SSPI 
-    SSPIAuth On 
-    SSPIAuthoritative On 
- 
-    require valid-user 
- 
-</Directory> 
-</code> 
- 
-Now restart Apache 
- 
-=== NTLM on Apache (Linux) === 
-  - Install mod_python, sudo apt-get install libapache2-mod-python 
-  - Get PyAuthenNTLM2, wget https://github.com/Legrandin/PyAuthenNTLM2/zipball/master 
-  - Rename to PyAuthenNTLM2.zip 
-  - Unzip 
-  - cd to new dir 
-  - Install, sudo python setup.py install 
-  - Add config to Apache2: 
-<code> 
-<Directory /var/lib/some_directory> 
-AuthType NTLM 
-AuthName !!DOMAIN!! 
-require valid-user 
-PythonAuthenHandler pyntlm 
-PythonOption Domain !!DOMAIN!! 
-PythonOption PDC !!PRIMARY_DOMAIN_CONTROLLER!! 
-PythonOption BDC !!BACKUP_DOMAIN_CONTROLLER!! 
-</Directory> 
-</code> 
-[[http://codebreaker.dk/2012/09/18/ntlm2-auth-pa-en-linux-boks/|Reference]] 
- 
-=== Kerberos on Apache (Linux) === 
- 
-This setup enables an Apache Server on Linux to verify Kerberos Tickets against an Active Directory server. 
- 
-Good references for Apache/Kerberos can be found at 
-  * http://www.grolmsnet.de/kerbtut/ 
-  * http://www.itefix.no/i2/node/11683 
- 
-The following examples assume your wiki to be running on ''dokuwiki.yourdomain.com'', with your Active Directory server running at ''dc1.yourdomain.com''; 
- 
-**Note: Kerberos is case sensitive, if it is all caps - it should be!** 
- 
-  - Install Kerberos client((Redhat: yum install krb5-workstation, Debian: krb5-user)) 
-  - Install [[http://modauthkerb.sourceforge.net|mod_auth_kerb]]((Redhat: yum install mod_auth_kerb, Debian: libapache2-mod-auth-kerb)) 
-  - Configure Kerberos if necessary, sample ''/etc/krb5.conf'':<code> 
-[logging] 
- default = FILE:/var/log/krb5libs.log 
- kdc = FILE:/var/log/krb5kdc.log 
- admin_server = FILE:/var/log/kadmind.log 
- 
-[libdefaults] 
- default_realm = YOURDOMAIN.COM 
- ticket_lifetime = 24h 
- forwardable = yes 
- 
-[realms] 
- YOURDOMAIN.COM = { 
-  kdc = dc1.yourdomain.com 
-  admin_server = dc1.yourdomain.com 
-  default_domain = yourdomain.com 
- } 
- 
-[domain_realm] 
- dokuwiki.yourdomain.com = YOURDOMAIN.COM 
- .yourdomain.com = YOURDOMAIN.COM 
- yourdomain.com = YOURDOMAIN.COM 
- 
-[appdefaults] 
- pam = { 
-  debug = false 
-   ticket_lifetime = 36000 
-   renew_lifetime = 36000 
-   forwardable = true 
-   krb4_convert = false 
- } 
-</code> 
-  - Verify that the time on the DokuWiki server is within 5 minutes of the Active Directory server. Otherwise Kerberos will not authenticate. 
-  - Verify that the Kerberos environment is working by running:<code> 
-kinit username@YOURDOMAIN.COM 
-klist 
-kdestroy 
-(If you get any errors here, make sure your DNS setup is working and you wrote all marked as "YOURDOMAIN.COM" hosts in uppercase in your krb5.conf. Try resolve every hostname manually.</code> 
-  - Create a keytab file for your DokuWiki server. Make sure you have created a non-admin user in Active Directory with no password expiration. Run this as a Domain Admin on a Windows server with Support Tools installed:<code>ktpass -princ HTTP/dokuwiki.yourdomain.com@YOURDOMAIN.COM -mapuser name_of_ad_user_you_have_created -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -pass the_ad_users_password -out dokuwiki.HTTP.keytab</code> Use the following if you're running Windows 7/Server 2008 R2 clients because [[http://technet.microsoft.com/en-us/library/dd560670(WS.10).aspx|des is disabled by default]] on these operating systems: <code>ktpass -princ HTTP/dokuwiki.yourdomain.com@YOURDOMAIN.COM -mapuser name_of_ad_user_you_have_created@yourdomain.com -crypto RC4-HMAC-NT -ptype KRB5_NT_PRINCIPAL -pass the_ad_users_password -out dokuwiki.HTTP.keytab </code> RC4-HMAC is supported on Windows 2000 and higher. 
-  - If no errors occurred, copy the keytab file to /etc/httpd/conf/. 
-  - Create /etc/httpd/conf.d/dokuwiki.conf:<code apache> 
-<Directory "/var/www/html/dokuwiki"> 
-        # Kerberos Auth 
-        AuthType Kerberos 
-        KrbAuthRealms YOURDOMAIN.COM 
-        KrbServiceName HTTP/dokuwiki.yourdomain.com 
-        Krb5Keytab /etc/httpd/conf/dokuwiki.HTTP.keytab 
-        KrbMethodNegotiate on 
-        KrbMethodK5Passwd on 
-        require valid-user 
-</Directory> 
-</code> 
-  - (Re)start Apache: service httpd restart. 
- 
-== Troubleshooting == 
- 
-  * Restart Apache. Web server config changes won't apply until restarted. 
-  * Try using the FQDN of the DokuWiki server, i.e. <nowiki>http://dokuwiki.yourdomain.com/dokuwiki</nowiki>. 
-  * If you are presented with a login window, do not enter domain/realm info, just user name and password. 
-  * Verify that the time on the DokuWiki server is within 5 minutes of the Active Directory server. Otherwise Kerberos will not authenticate. 
-  * Check all Kerberos files for case inconsistencies. 
-  * Review this instruction from start to end. See reference links where possible. 
-==== Browser ==== 
- 
-Your browser needs to be setup to forward authentication info to the Webserver. 
- 
-=== Setup MS Internet Explorer === 
- 
-FIXME add detailed description 
- 
-  - add dokuwiki server to trusted zone 
-  - Enable authentication forwarding (Windows Integrated Authentication). Restart your browser to complete the change. IE 8 shown here: 
-{{http://img97.imageshack.us/img97/9099/ieenableintegratedwindo.jpg|}} 
- 
-=== Setup Firefox === 
- 
-  - Open Firefox and type //about:config// in the address bar. 
-  - In the ‘Filter’ field type one of the following (depending if you're using NTLM or Kerberos) //network.automatic-ntlm-auth.trusted-uris// or //network.negotiate-auth.trusted-uris// 
-  - Double click the name of the preference that we just searched for 
-  - Enter the URLs of the sites you wish to pass NTLM auth info to in the form of: 
-<code> 
-    http://intranet.company.com,http://email.company.lan 
-</code> 
-Notice that you can use a comma separated list in this field. 
- 
-===== Effect on Plug-Ins ===== 
-Some plug-ins may not gracefully work once you've switched over to the ad auth backend. Specifically, pulling the user's display name will not work if you don't provide valid authentication information. One such plugin is WikiStatistics, where a simple workaround to only display the username can be employed. 
- 
-Due to [[http://adldap.sourceforge.net/wiki/doku.php?id=api_pagingsupport|missing support for paged queries in PHP's LDAP extension]], plugins that try to get all users from the auth backend will fail if you use AUTH:AD and have more than 1000 objects in Active Directory. One example is the [[:plugin:issuetracker#faq|IssueTracker]] plugin. 
auth/ad.1429820873.txt.gz · Last modified: 2015-04-23 22:27 by 216.191.119.186

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki