<?xml version='1.0' ?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>

  <article id="ext-auth-install">
    <title>Installation</title>

    <authorblurb>
      <para>
      by <ulink url="http://openacs.org/shared/community-member?user_id=8561">Joel Aufrecht</ulink>
      </para>
    </authorblurb>

    <sect1 id="ext-auth-pam-install">
      <title>Using Pluggable Authentication Modules (PAM) with OpenACS</title>
      <para>OpenACS supports PAM authetication via the ns_pam module in AOLserver.</para>
      <orderedlist>
        <listitem>
          <formalpara>
            <title>Add PAM support to AOLserver</title>
            <para>OpenACS supports PAM support via the PAM AOLserver
        module.  PAM is system of modular support, and can provide
        local (unix password), RADIUS, LDAP (<ulink
        url="http://www.tldp.org/HOWTO/LDAP-Implementation-HOWTO/pamnss.html">more
        information</ulink>), and other forms of
        authentication.  Note that due to security issues, the
        AOLserver PAM module cannot be used for local password
        authentication.  </para>
            </formalpara>
          <orderedlist>
            <listitem>
              <formalpara id="install-nspam">
                <title>Compile and install ns_pam</title>
                <para>Download the <ulink url="/doc/nspam-download">tarball</ulink> to
            <computeroutput>/tmp</computeroutput>.</para>
              </formalpara>
              <para>Debian users: first do <userinput>apt-get install libpam-dev</userinput></para>
              <screen>[root@yourserver root]# <userinput>cd /usr/local/src/aolserver</userinput>
[root@yourserver aolserver]# <userinput>tar xzf /tmp/ns_pam-0.1.tar.gz</userinput>
[root@yourserver aolserver]# <userinput>cd nspam</userinput>
[root@yourserver nspam]# <userinput>make</userinput>
gcc -I/usr/include/pam -I/usr/local/aolserver/include -D_REENTRANT=1 
  -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 
  -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1   -c -o nspam.o nspam.c
nspam.c: In function `PamCmd':
nspam.c:107: warning: implicit declaration of function `Tcl_SetObjResult'
nspam.c:107: warning: implicit declaration of function `Tcl_NewIntObj'
gcc -I/usr/include/pam -I/usr/local/aolserver/include -D_REENTRANT=1 
  -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 
  -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1   -c -o pam_support.o pam_support.c
/bin/rm -f nspam.so
gcc -shared -nostartfiles -o nspam.so nspam.o pam_support.o -lpam
[root@yourserver nspam]# <userinput>make install</userinput>
[root@yourserver nspam]#
<action>cd /usr/local/src/aolserver
tar xzf /tmp/ns_pam-0.1.tar.gz
cd nspam
make
make install</action></screen>
            </listitem>
            
            <listitem>
              <formalpara>
                <title>Set up a PAM domain</title>
                <para>A PAM domain is a set of rules for granting
            privileges based on other programs.  Each instance of
              AOLserver uses a domain; different aolserver instances
              can use the same domain but one AOLserver instance
              cannot use two domains.  The domain describes
              which intermediate programs will be used to check
              permissions.  You may need to install software to
              perform new types of authentication.
</para>
              </formalpara>
              <itemizedlist>
                <listitem>
                  <formalpara>
                    <title>RADIUS in PAM</title>
                    <para></para>
                  </formalpara>
                  <orderedlist>
                    <listitem>
                      <para>Untar the <ulink url="/doc/individual-programs.html#pam-radius-download">pam_radius
                    tarball</ulink> and compile and install.  (<ulink
                    url="http://www.freeradius.org/pam_radius_auth/">more
                    information</ulink>)</para>
                      <screen>[root@yourserver root]# <userinput>cd /usr/local/src/</userinput>
[root@yourserver src]# <userinput>tar xf /tmp/pam_radius-1.3.16.tar</userinput>
[root@yourserver src]# <userinput>cd pam_radius-1.3.16</userinput>
[root@yourserver pam_radius-1.3.16]# <userinput>make</userinput>
cc -Wall -fPIC -c pam_radius_auth.c -o pam_radius_auth.o
cc -Wall -fPIC   -c -o md5.o md5.c
ld -Bshareable pam_radius_auth.o md5.o -lpam -o pam_radius_auth.so
[root@yourserver pam_radius-1.3.16]# <userinput>cp pam_radius_auth.so /lib/security/pam_radius_auth.so</userinput>
[root@yourserver pam_radius-1.3.16]#
<action>cd /usr/local/src/
tar xf /tmp/pam_radius-1.3.16.tar
cd pam_radius-1.3.16
make
cp pam_radius_auth.so /lib/security/pam_radius_auth.so</action></screen>
                      <para>Debian users: <userinput>apt-get install libpam-radius-auth</userinput></para>
                    </listitem>
                    <listitem>
                      <para>Set up the PAM domain.  Recent PAM
                distributions have a different file for each domain,
                all in <computeroutput>/etc/pam.d</computeroutput>.
                Previous PAM setups put all domain configuration lines
                into a single file,
                <computeroutput>/etc/pam.conf</computeroutput>.  On
                Red Hat, create the file
                <computeroutput>/etc/pam.d/<replaceable>service0</replaceable></computeroutput>
                with these contents:</para>
                      <programlisting>auth       sufficient   /lib/security/pam_radius_auth.so
</programlisting>
                      </listitem>
                    <listitem>
                      <para>Modify the AOLserver configuration file to use
                this PAM domain.  Edit the line</para>
                      <programlisting>ns_param   PamDomain             "<replaceable>service0</replaceable>"</programlisting>
                      <para>So that the value of the parameter matches the name (just the file name, not the fully pathed name) of the domain file in <programlisting>/etc/pam.d/</programlisting></para>
                    </listitem>
                  </orderedlist>
                </listitem>
                <listitem>
                  <formalpara>
                    <title>LDAP in PAM</title>
                    <para><ulink url="http://www.tldp.org/HOWTO/LDAP-Implementation-HOWTO/pamnss.html#AEN110">more information</ulink></para>
                  </formalpara>
                </listitem>
              </itemizedlist>
            </listitem>
            <listitem>
              <formalpara>
                <title>Modify the AOLserver configuration file to support ns_pam.</title>
                <para></para>
              </formalpara>
              <para>In
          <computeroutput>/var/lib/aolserver/<replaceable>service0</replaceable>/etc/config.tcl</computeroutput>, enable the nspam module by uncommenting this line:</para>
              <programlisting>ns_param   nspam           ${bindir}/nspam.so</programlisting>
            </listitem>
          </orderedlist>
        </listitem>
        <listitem>
          <formalpara>
            <title>Install auth-pam OpenACS service package</title>
            <para><ulink url="/acs-admin/install/">Install</ulink> <computeroutput>auth-pam</computeroutput> and restart the server.</para>
          </formalpara>
        </listitem>
        <listitem>
          <formalpara id="ext-auth-create-authority">
            <title>Create an OpenACS authority</title>
            <para>OpenACS supports multiple authentication authorities.
        The OpenACS server itself is the "Local Authority," used by
        default.</para>
          </formalpara>
          <orderedlist>
            <listitem>
              <para>Browse to the authentication administration page,
            <computeroutput>http://<replaceable>yourserver</replaceable><ulink
            url="/acs-admin/auth/">/acs-admin/auth/</ulink></computeroutput>.
             Create and name an authority (in the sitewide admin UI)</para>
            </listitem>
            <listitem>
              <para>Set Authentication to PAM.</para>
            </listitem>
            <listitem>
              <para>If the PAM domain defines a <computeroutput>password</computeroutput> command, you can set Password Management to PAM.  If not, the PAM module cannot change the user's password and you should leave this option Disabled.</para>
            </listitem>
            <listitem>
              <para>Leave Account Registration disabed.</para>
            </listitem>
            <listitem>
              <para><link linkend="configure-batch-sync">Configure Batch Synchronization</link>
</para>
            </listitem>
          </orderedlist>
        </listitem>
      </orderedlist>
    </sect1>

    <sect1 id="ext-auth-ldap-install">
    <title>Using LDAP/Active Directory with OpenACS</title>
    <authorblurb>by <ulink url="http://openacs.org/shared/community-member?user_id=8551">John Sequeira</ulink>, <ulink url="http://openacs.org/shared/community-member?user_id=8263">Michael Steigman</ulink>, and <ulink url="http://openacs.org/shared/community-member?user_id=12805">Carl Blesius</ulink>.</authorblurb>
    <formalpara>
    <title>ToDo:</title>
    <para>Add/verify information on on-demand sync, account registration, and batch synchronization. Add section on ldapsearch. </para></formalpara>
    <formalpara>
    <title>Overview</title>
    <para>You do not want to make users remember yet another password and username. If you can avoid it you do not want to store their passwords either. This document should help you set your system up so your users can seamlessly log in to your OpenACS instance using the password they are accustomed to using for other things at your institution.</para></formalpara>
    <formalpara>
    <title>Background</title>
     <para>The original OpenACS LDAP implementation (which has been depreciated by this package) treated the LDAP server as another data store similar to Oracle or Postgresql. It opened a connection using a priveleged account and read or stored an encrypted password for the user in question. This password was independent of the user's operating system or network account, and had to be synchronized if you wanted the same password for OpenACS.</para>
     <para>Save their passwords? Sync passwords? Deal with forgotten password requests? No Thanks. Using ldap bind, you can delegate authentication completely to LDAP. This way you can let the IT department (if you are lucky) worry about password storage/synchronization/etc. The bind operation takes a username and password and returns a true of false depending on whether they match up. This document takes the 'bind' approach so that your users LDAP/AD password (or whatever else you use) can be used to login to OpenACS.</para></formalpara>
    <formalpara>
     <title>Note on Account Creation</title>
     <para>On the authentication driver configure screens, you will also see lots of options for synchronizing users between your directory and OpenACS. This document takes the approach of provisioning users on demand instead of ahead-of-time. This means that when they attempt to login to OpenACS, if they have a valid Windows account, we'll create an account for them in OpenACS and log them in.</para></formalpara>
     <orderedlist>
        <listitem>
          <formalpara id="ext-auth-ldap-setup">
            <title>Installing AOLserver LDAP support (openldap and nsldap)</title>
            <para>Install openldap and nsldap using
            <ulink url="http://openacs.org/doc/current/install-ldap-radius.html">the document Malte created</ulink> </para>
            <para>Next, modify your config.tcl file as directed in the nsldap README. </para>
	    <para>Here's what the relevant additions should look like:</para>
 <screen>
  <computeroutput>
# LDAP authentication
ns_param   nsldap             ${bindir}/nsldap.so

...

ns_section "ns/ldap/pool/ldap"
ns_param user "cn=Administrator, cn=Users, dc=mydomain, dc=com"
ns_param password "password"
ns_param host "directory.mydomain.com"
ns_param connections 1
ns_param verbose On

ns_section "ns/ldap/pools"
ns_param ldap ldap

ns_section "ns/server/${server}/ldap"
ns_param pools *
ns_param defaultpool ldap
   </computeroutput>
  </screen>
<para>To verify that this is all working, restart Aolserver and ensure that you see something like this in your error.log:</para>
   <screen>
    <computeroutput>
[10/Jan/2006:11:11:07][22553.3076437088][-main-] Notice: modload: loading '/usr/local/aolserver/bin/nsldap.so'
[10/Jan/2006:11:11:08][22553.3076437088][-main-] Debug: nsldap: allowing * -> pool ldap
[10/Jan/2006:11:11:08][22553.3076437088][-main-] Debug: nsldap: adding pool ldap to the list of allowed pools
[10/Jan/2006:11:11:08][22553.3076437088][-main-] Debug: nsldap: Registering LDAPCheckPools (600)
    </computeroutput>
   </screen>
  </formalpara>
 </listitem>
 <listitem>
  <formalpara>
   <title>auth-ldap + driver installation</title>
   <para>Next, visit the software installation page in acs-admin and install the auth-ldap package. Your OpenACS installation now has all the code required to authenticate using nsldap, so now you need to configure your site's authentication to take advantage of it. To add the authentication driver to your OpenACS instance, go to: Main Site, Site-Wide Administration, and then Authentication</para>
   <para>Here's some sample Authentication Driver values:</para>
   <para>Name=Active Directory, Short Name=AD, Enabled=Yes, Authentication=LDAP, Password Management=LDAP</para>
   <para>You may wish to push this new authority to the top of the list so it will become the default for users on the login screen.</para>
   <para>Next, you have to configure the authentication driver parameters by going to: Main Site, Site-Wide Administration,  Authentication, Active Directory, and then Configure</para>
   <para>Parameters that match our example will look like:</para>
   <para>UsernameAttribute=sAMAccountNMame, BaseDN= cn=Users,dc=mydomain,dc=com,
InfoAttributeMap=first_names=givenName;last_name=sn;email=mail,
PasswordHash=N/A</para>
  </formalpara>
 </listitem>
<listitem>
  <formalpara>
   <title>Code Tweaks for Bind</title>
   <para>Bind-style authentication is not supported via configuration parameters, so we will have to modify the tcl authentication routine to provide this behavior.</para>
   <para>You'll have to modify the existing ./packages/auth-ldap/tcl/auth-ldap-procs.tcl file to support bind authentication.</para>
   <para>First toggle ldap bind support.</para>
   <para>Change this:</para>
   <screen>
    <computeroutput>
# LDAP bind based authentication ?
set ldap_bind_p 0
if {$ldap_bind_p==1} {
...
    </computeroutput>
   </screen>
   <para>to this:</para>
   <screen>
    <computeroutput>
# LDAP bind based authentication ?
set ldap_bind_p 1

if {$ldap_bind_p==1} {
...
    </computeroutput>
   </screen>
   <para>Then change the bind to first do a search to resolve to account name provided by the user to a fully qualified domain name (FQDN), which the LDAP server uses as a primary key.</para>
   <para>Change this:</para>
   <screen>
    <computeroutput>
set lh [ns_ldap gethandle]

if {[ns_ldap bind $lh "cn=$cn" "$password"]} {
    set result(auth_status) ok
}    
    </computeroutput>
   </screen>
   <para>to this</para>
<screen>
<computeroutput>
set lh [ns_ldap gethandle]

set fdn [lindex [lindex [ns_ldap search $lh -scope subtree $params(BaseDN) "($params(UsernameAttribute)=$username)" dn] 0] 1]

if {[ns_ldap bind $lh $fdn $password]} {
    set result(auth_status) ok
}    
    </computeroutput>
   </screen>
   </formalpara>
 </listitem>
</orderedlist>
<formalpara>
 <title>Troubleshooting</title>
 <para>If you're having trouble figuring out some the values for the ldapm, see this useful page on <ulink url="http://bugzilla.glob.com.au/activedirectory/">setting up Active Directory integration with Bugzilla</ulink>. It explains how distinguished names are defined in Active Directory, and how to test that you have the correct values for connectivity and base DN using the OpenLDAP command-line utility ldapsearch.</para>
<para>John had an issue where nsldap was not loading because AOLServer couldn't find the openldap client libraries, but he was able to fix it by adding the openldap libraries to his LD_LIBRARY_PATH (e.g. /usr/local/openldap/lib)</para></formalpara>
 <formalpara>
  <title>Credits</title>
  <para>Thanks to Malte Sussdorf for his help and the <ulink url="http://www.lcs.mgh.harvard.edu/">Laboratory of Computer Science at Massachusetts General Hospital</ulink> for underwriting this work.</para></formalpara>
    </sect1>
    <sect1 id="configure-batch-sync">
      <title>Configure Batch Synchronization</title>
      <orderedlist>
            <listitem>
              <para>Browse to the authentication administration page,
            <computeroutput>http://<replaceable>yourserver</replaceable><ulink
            url="/acs-admin/auth/">/acs-admin/auth/</ulink></computeroutput>
            and choose an authority for batch sync.</para>
            </listitem>
            <listitem>
              <para>Set Batch sync enabled to Yes.  Set GetDocument
              Implementation to HTTP GET.  Set ProcessDocument Implementation to IMS Enterprise 1.1.  These settings will cause OpenACS to attempt to retrieve via HTTP a list of users in XML format from a location we will specify in a few steps.</para>
            </listitem>
            <listitem>
              <para>Click OK.</para>
            </listitem>
            <listitem>
              <para>On the next page, click <computeroutput>Configure</computeroutput> on the GetDocument Implementation line.</para>
            </listitem>
            <listitem>
              <para>Enter either or both the IncrementalURL and SnapshotURL.  These are the URLs which the external Authority will supply with XML files in IMS Enterprise 1.1 format.</para>
            </listitem>
          <listitem>
            <para>Configure your Authority (RADIUS server, etc) to
            supply XML files to the URLs IncrementalURL and
            SnapshotURL.  A typical set of incremental file record
            looks like:</para>
<programlisting><xi:include href="example.xml" xi:parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"><xi:fallback>example missing</xi:fallback></xi:include></programlisting>
          <para>A snapshot file is similar but doesn't have recstatus,
  since it's not a delta but a list of valid records.  See the larger example in the design document for more details.
</para>
              <para>(More information: <xref linkend="ims-sync-driver-design"/>, <ulink url="http://www.imsproject.org/enterprise/">The IMS 1.1 spec</ulink>)</para>
          </listitem>
      </orderedlist>
      <para><phrase role="cvstag">($Id: install.xml,v 1.5 2006/06/04 00:45:21 donb Exp $)</phrase></para>
    </sect1>
  </article>
