You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@vcl.apache.org by bu...@apache.org on 2012/07/30 18:21:10 UTC
svn commit: r827426 - in /websites/staging/vcl/trunk/content: ./
docs/ldapauth.html
Author: buildbot
Date: Mon Jul 30 16:21:09 2012
New Revision: 827426
Log:
Staging update by buildbot for vcl
Modified:
websites/staging/vcl/trunk/content/ (props changed)
websites/staging/vcl/trunk/content/docs/ldapauth.html
Propchange: websites/staging/vcl/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Mon Jul 30 16:21:09 2012
@@ -1 +1 @@
-1366533
+1367148
Modified: websites/staging/vcl/trunk/content/docs/ldapauth.html
==============================================================================
--- websites/staging/vcl/trunk/content/docs/ldapauth.html (original)
+++ websites/staging/vcl/trunk/content/docs/ldapauth.html Mon Jul 30 16:21:09 2012
@@ -78,7 +78,17 @@
<div id="content">
<h1 class="title">LDAP Authentication</h1>
<h2 id="why-ldap-authentication">Why LDAP Authentication?</h2>
+<p>Authenticating your users to VCL via LDAP allows you to use your enterprise managed
+accounts to log in to the VCL web site. Additionally, you can mirror certain user
+groups from your LDAP system into VCL so that you do not need to manage the user
+group memberships both in your enterprise system and in VCL.</p>
<h2 id="overview">Overview</h2>
+<p>First, you need an LDAP server with SSL enabled. You already have this if you have
+an Active Directory system set up. Next, you (probably) need to add an affiliation
+to VCL so that users logging in via the new LDAP connection will all be associated
+together. Finally, you need to modify the web code conf.php file to have information
+about how to connect to the LDAP server. You will also need to make sure your web
+server can trust the SSL certificate and access it through any firewalls.</p>
<h2 id="prerequisites-for-your-ldap-server">Prerequisites for your LDAP server:</h2>
<ul>
<li>SSL must be enabled on your LDAP server</li>
@@ -196,6 +206,91 @@ authentication method explaining why the
</li>
<li>Uncomment the <strong>require_once</strong> line for <strong>ldapauth.php</strong> toward the bottom of the file</li>
</ul>
+<h2 id="mirroring-ldap-user-groups">Mirroring LDAP User Groups</h2>
+<p>This part is a little more complicated because it actually requires modifying some
+of the VCL code. Before modifying VCL, you first need to create user groups in your
+LDAP system and configure things so that a lookup of a user in your LDAP system will
+list the groups of which the user is a member. Doing these items is beyond the scope
+of this document.</p>
+<p>In the vcl/.ht-inc/authmethods/ldapauth.php file, there is an example function at
+the end named <strong>updateEXAMPLE1Groups</strong>. In a previous step, you modified conf.php
+and changed <strong>EXAMPLE1 LDAP</strong> to something to match your location. <strong>NCSU LDAP</strong>
+was used as an example. We'll continue using that here.</p>
+<p>You need to change the name of <strong>updateEXAMPLE1Groups</strong> to match your location.
+We'll change it to <strong>updateNCSUGroups</strong> for our example. Next, on the 2nd line of
+the function, change <strong>EXAMPLE1 LDAP</strong> to match your location (ex. <strong>NCSU LDAP</strong>).
+Next, you need to determine what attribute is used when looking up users in your
+LDAP system to reference user group memberships. For Active Directory, this is typically
+<strong>memberof</strong>. Now, if needed, change the two references in the function from <strong>memberof</strong>
+to the attribute used in your LDAP system. Finally, there are three example regular
+expressions in the <strong>for</strong> loop at the bottom of the function that match various
+example names of user groups. You'll need to modify these to match the OU structure
+of your LDAP system.</p>
+<p>These are the three example rules in VCL 2.3:</p>
+<div class="codehilite"><pre><span class="o">^</span><span class="n">CN</span><span class="o">=</span><span class="p">(</span><span class="o">.+</span><span class="p">),</span><span class="n">OU</span><span class="o">=</span><span class="n">CourseRolls</span><span class="p">,</span><span class="n">DC</span><span class="o">=</span><span class="n">example1</span><span class="p">,</span><span class="n">DC</span><span class="o">=</span><span class="n">com</span>
+<span class="o">^</span><span class="n">CN</span><span class="o">=</span><span class="p">(</span><span class="n">Students_Enrolled</span><span class="p">),</span><span class="n">OU</span><span class="o">=</span><span class="n">Students</span><span class="p">,</span><span class="n">DC</span><span class="o">=</span><span class="n">example1</span><span class="p">,</span><span class="n">DC</span><span class="o">=</span><span class="n">com</span><span class="nv">$</span>
+<span class="err">^</span><span class="nv">CN</span><span class="o">=</span><span class="p">(</span><span class="n">Staff</span><span class="p">),</span><span class="n">OU</span><span class="o">=</span><span class="n">IT</span><span class="p">,</span><span class="n">DC</span><span class="o">=</span><span class="n">example1</span><span class="p">,</span><span class="n">DC</span><span class="o">=</span><span class="n">com</span><span class="nv">$</span>
+</pre></div>
+
+
+<p>The first one matches any groups under the CourseRolls OU. The second one specifically
+matches the <strong>Students_Enrolled</strong> group under the Students OU. The third one matches
+the <strong>Staff</strong> group under the IT OU. If you need help creating regular expressions
+to match your LDAP system, please feel free to ask on our user email list or via IRC.</p>
+<p>Finally, you'll also need to modify the updateLDAPUser function in the same file.
+Toward the end of the function is a <strong>switch</strong> statement based on affiliation names.
+Change the <strong>EXAMPLE1</strong> entry to the affiliation you created for your site. Then,
+change the name of the function called for that affiliation to your new name for the
+<strong>updateEXAMPLE1Groups</strong> function. Here is an example of that part of the function:</p>
+<div class="codehilite"><pre><span class="n">switch</span><span class="p">(</span><span class="n">getAffiliationName</span><span class="p">(</span><span class="nv">$affilid</span><span class="p">))</span> <span class="p">{</span>
+ <span class="k">case</span> <span class="s">'NCSU'</span><span class="p">:</span>
+ <span class="n">updateNCSUGroups</span><span class="p">(</span><span class="nv">$user</span><span class="p">);</span>
+ <span class="n">break</span><span class="p">;</span>
+ <span class="n">default:</span>
+ <span class="sr">//</span><span class="n">TODO</span> <span class="n">possibly</span> <span class="n">add</span> <span class="n">to</span> <span class="n">a</span> <span class="n">default</span> <span class="n">group</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>Here is an example function using NCSU instead of EXAMPLE1, and using an Active
+Directory LDAP system:</p>
+<div class="codehilite"><pre><span class="n">function</span> <span class="n">updateNCSUGroups</span><span class="p">(</span><span class="nv">$user</span><span class="p">)</span> <span class="p">{</span>
+ <span class="n">global</span> <span class="nv">$authMechs</span><span class="p">;</span>
+ <span class="nv">$auth</span> <span class="o">=</span> <span class="nv">$authMechs</span><span class="p">[</span><span class="s">'NCSU LDAP'</span><span class="p">];</span>
+ <span class="nv">$ds</span> <span class="o">=</span> <span class="n">ldap_connect</span><span class="p">(</span><span class="s">"ldaps://{$auth['server']}/"</span><span class="p">);</span>
+ <span class="k">if</span><span class="p">(</span><span class="o">!</span> <span class="nv">$ds</span><span class="p">)</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+ <span class="n">ldap_set_option</span><span class="p">(</span><span class="nv">$ds</span><span class="p">,</span> <span class="n">LDAP_OPT_PROTOCOL_VERSION</span><span class="p">,</span> <span class="mi">3</span><span class="p">);</span>
+ <span class="n">ldap_set_option</span><span class="p">(</span><span class="nv">$ds</span><span class="p">,</span> <span class="n">LDAP_OPT_REFERRALS</span><span class="p">,</span> <span class="mi">0</span><span class="p">);</span>
+
+ <span class="nv">$res</span> <span class="o">=</span> <span class="n">ldap_bind</span><span class="p">(</span><span class="nv">$ds</span><span class="p">,</span> <span class="nv">$auth</span><span class="p">[</span><span class="s">'masterlogin'</span><span class="p">],</span>
+ <span class="nv">$auth</span><span class="p">[</span><span class="s">'masterpwd'</span><span class="p">]);</span>
+ <span class="k">if</span><span class="p">(</span><span class="o">!</span> <span class="nv">$res</span><span class="p">)</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="nv">$search</span> <span class="o">=</span> <span class="n">ldap_search</span><span class="p">(</span><span class="nv">$ds</span><span class="p">,</span>
+ <span class="nv">$auth</span><span class="p">[</span><span class="s">'binddn'</span><span class="p">],</span>
+ <span class="s">"{$auth['unityid']}={$user['unityid']}"</span><span class="p">,</span>
+ <span class="n">array</span><span class="p">(</span><span class="s">'memberof'</span><span class="p">),</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">15</span><span class="p">);</span>
+ <span class="k">if</span><span class="p">(</span><span class="o">!</span> <span class="nv">$search</span><span class="p">)</span>
+ <span class="k">return</span> <span class="mi">0</span><span class="p">;</span>
+
+ <span class="nv">$data</span> <span class="o">=</span> <span class="n">ldap_get_entries</span><span class="p">(</span><span class="nv">$ds</span><span class="p">,</span> <span class="nv">$search</span><span class="p">);</span>
+ <span class="nv">$newusergroups</span> <span class="o">=</span> <span class="n">array</span><span class="p">();</span>
+ <span class="k">if</span><span class="p">(</span><span class="o">!</span> <span class="n">array_key_exists</span><span class="p">(</span><span class="s">'memberof'</span><span class="p">,</span> <span class="nv">$data</span><span class="p">[</span><span class="mi">0</span><span class="p">]))</span>
+ <span class="k">return</span><span class="p">;</span>
+ <span class="k">for</span><span class="p">(</span><span class="nv">$i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="nv">$i</span> <span class="o"><</span> <span class="nv">$data</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s">'memberof'</span><span class="p">][</span><span class="s">'count'</span><span class="p">];</span> <span class="nv">$i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">if</span><span class="p">(</span><span class="n">preg_match</span><span class="p">(</span><span class="s">'/^CN=(.+),OU=VCLGroups,DC=ad,DC=ncsu,DC=edu/'</span><span class="p">,</span> <span class="nv">$data</span><span class="p">[</span><span class="mi">0</span><span class="p">][</span><span class="s">'memberof'</span><span class="p">][</span><span class="nv">$i</span><span class="p">],</span> <span class="nv">$match</span><span class="p">))</span>
+ <span class="n">array_push</span><span class="p">(</span><span class="nv">$newusergroups</span><span class="p">,</span> <span class="n">getUserGroupID</span><span class="p">(</span><span class="nv">$match</span><span class="p">[</span><span class="mi">1</span><span class="p">],</span> <span class="nv">$user</span><span class="p">[</span><span class="s">'affiliationid'</span><span class="p">]));</span>
+ <span class="p">}</span>
+ <span class="nv">$newusergroups</span> <span class="o">=</span> <span class="n">array_unique</span><span class="p">(</span><span class="nv">$newusergroups</span><span class="p">);</span>
+ <span class="n">updateGroups</span><span class="p">(</span><span class="nv">$newusergroups</span><span class="p">,</span> <span class="nv">$user</span><span class="p">[</span><span class="s">"id"</span><span class="p">]);</span>
+<span class="p">}</span>
+</pre></div>
+
+
+<p>If you add other affiliations that need to be tied in with LDAP, you can copy this
+function and rename things in a similar fashion to match the new LDAP system.</p>
</div>
<div id="footer">