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 2013/11/06 03:54:40 UTC
svn commit: r885573 - in /websites/staging/vcl/trunk/content: ./
docs/shibauth.html
Author: buildbot
Date: Wed Nov 6 02:54:39 2013
New Revision: 885573
Log:
Staging update by buildbot for vcl
Modified:
websites/staging/vcl/trunk/content/ (props changed)
websites/staging/vcl/trunk/content/docs/shibauth.html
Propchange: websites/staging/vcl/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Wed Nov 6 02:54:39 2013
@@ -1 +1 @@
-1495531
+1539218
Modified: websites/staging/vcl/trunk/content/docs/shibauth.html
==============================================================================
--- websites/staging/vcl/trunk/content/docs/shibauth.html (original)
+++ websites/staging/vcl/trunk/content/docs/shibauth.html Wed Nov 6 02:54:39 2013
@@ -72,7 +72,200 @@
<div id="content">
<h1 class="title">Shibboleth Authentication</h1>
- <p>stub page</p>
+ <h1 id="shibboleth-authentication">Shibboleth Authentication</h1>
+<p>The VCL is designed to support Shibboleth authentication for one or more affiliations. Using Shibboleth
+does not preclude the use of LDAP for other affiliations in the same VCL infrastructure. The principal
+advantage of using Shibboleth with the VCL is the ability to completely externalize authentication
+ (and, to a certain degree, authorization) decisions. That is, by using Shibboleth authentication, a user's
+password will never pass through the VCL system.</p>
+<h2 id="configure-apache">Configure Apache</h2>
+<p>The first step is to configure Apache by protecting the <code>/shibauth</code> directory on your webserver.
+If the VCL is installed in the webserver root, the configuration will look like this:</p>
+<div class="codehilite"><pre><span class="nt"><Location</span> <span class="err">/shibauth</span><span class="nt">></span>
+ AuthType shibboleth
+ ShibRequestSetting requireSession 1
+ require valid-user
+<span class="nt"></Location></span>
+</pre></div>
+
+
+<h2 id="test-shibboleth-attributes">Test Shibboleth Attributes</h2>
+<p>Before proceeding, it is generally a good idea to test that the shibboleth attributes are being correctly sent
+from the Identity Provider (IdP) to the Service Provider (SP). To do that, create a PHP file in your
+<code>/shibauth</code> directory (e.g. <code>test.php</code>):</p>
+<div class="codehilite"><pre><span class="cp"><!DOCTYPE html></span>
+<span class="nt"><html</span> <span class="na">lang=</span><span class="s">"en"</span><span class="nt">></span>
+<span class="nt"><head></span>
+ <span class="nt"><title></span>Shibboleth Test<span class="nt"></title></span>
+<span class="nt"></head></span>
+<span class="nt"><body></span>
+ <span class="nt"><h1></span>Shibboleth Test<span class="nt"></h1></span>
+<span class="cp"><?php</span>
+<span class="c1">// Include the Shibboleth attributes you intend to test here</span>
+<span class="nv">$attributes</span> <span class="o">=</span> <span class="k">array</span><span class="p">(</span><span class="s1">'displayName'</span><span class="p">,</span> <span class="s1">'mail'</span><span class="p">,</span> <span class="s1">'eppn'</span><span class="p">,</span>
+ <span class="s1">'givenName'</span><span class="p">,</span> <span class="s1">'sn'</span><span class="p">,</span> <span class="s1">'affiliation'</span><span class="p">,</span> <span class="s1">'unscoped-affiliation'</span><span class="p">);</span>
+<span class="k">foreach</span><span class="p">(</span><span class="nv">$attributes</span> <span class="k">as</span> <span class="nv">$a</span><span class="p">){</span>
+ <span class="k">print</span> <span class="s2">"<p>"</span><span class="p">;</span>
+ <span class="k">print</span> <span class="s2">"<strong></span><span class="si">$a</span><span class="s2"></strong> = "</span><span class="p">;</span>
+ <span class="k">print</span> <span class="nb">isset</span><span class="p">(</span><span class="nv">$_SERVER</span><span class="p">[</span><span class="nv">$a</span><span class="p">])</span> <span class="o">?</span> <span class="nv">$_SERVER</span><span class="p">[</span><span class="nv">$a</span><span class="p">]</span> <span class="o">:</span> <span class="s2">"<em>Undefined</em>"</span><span class="p">;</span>
+ <span class="k">print</span> <span class="s2">"</p>"</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="cp">?></span>
+<span class="nt"></body></span>
+<span class="nt"></html></span>
+</pre></div>
+
+
+<p>Then visit this page at <code>https://vcl.yourdomain.edu/shibauth/test.php</code></p>
+<p>The only attribute that is absolutely required is <code>eppn</code>, but the VCL also expects
+the following attributes to be defined:</p>
+<ul>
+<li>either <code>displayName</code> or both <code>givenName</code> and <code>sn</code></li>
+<li><code>mail</code></li>
+<li><code>affiliation</code></li>
+</ul>
+<p>If these attributes are not present or not correct, then you may need to fix the configuration of
+Shibboleth on your system. Either the SP is not mapping the attributes properly or the IdP is not
+releasing them. Some good places to start include inspecting the full contents of the
+<code>$_SERVER</code> array or write a script that calls <code>phpinfo();</code>.</p>
+<h2 id="configure-the-vcl-for-shibboleth-authentication">Configure the VCL for Shibboleth authentication</h2>
+<p>Open the <code>.ht-inc/conf.php</code> file in a text editor</p>
+<p>Define your institution in the <code>$authMechs</code> array like so:</p>
+<div class="codehilite"><pre>$<span class="n">authMechs</span> <span class="p">=</span> <span class="n">array</span><span class="p">(</span>
+ "<span class="n">My</span> <span class="n">Institution</span>" <span class="p">=</span><span class="o">></span> <span class="n">array</span><span class="p">(</span>
+ "<span class="n">type</span>" <span class="p">=</span><span class="o">></span> "<span class="n">redirect</span>"<span class="p">,</span>
+ "<span class="n">URL</span>" <span class="p">=</span><span class="o">></span> "<span class="o">/</span><span class="n">Shibboleth</span><span class="p">.</span><span class="n">sso</span><span class="o">/</span><span class="n">Login</span>?<span class="n">target</span><span class="p">=</span><span class="o">/</span><span class="n">shibauth</span><span class="o">&</span><span class="n">entityID</span><span class="p">={</span><span class="n">the</span> <span class="n">URL</span><span class="o">-</span><span class="n">encoded</span> <span class="n">location</span> <span class="n">of</span> <span class="n">your</span> <span class="n">IdP</span><span class="p">}</span>"<span class="p">,</span>
+ "<span class="n">affiliationid</span>" <span class="p">=</span><span class="o">></span> 0<span class="p">,</span>
+ "<span class="n">help</span>" <span class="p">=</span><span class="o">></span> "<span class="p">...</span>"<span class="p">),</span>
+ <span class="p">....</span>
+<span class="p">);</span>
+</pre></div>
+
+
+<p>Notice that affiliationid is set to 0.</p>
+<p>If you wish to be able to manually add users to groups through the web interface (that is, Shibboleth users who
+have not previously logged in), then you will need to have this line in the configuration:</p>
+<div class="codehilite"><pre><span class="n">define</span><span class="p">(</span>"<span class="n">ALLOWADDSHIBUSERS</span>"<span class="p">,</span> 1<span class="p">);</span>
+</pre></div>
+
+
+<p>By default this is set as 0.</p>
+<p>Finallly, uncomment this line at the bottom of the configuration file:</p>
+<div class="codehilite"><pre><span class="n">require_once</span><span class="p">(</span>"<span class="p">.</span><span class="n">ht</span><span class="o">-</span><span class="n">inc</span><span class="o">/</span><span class="n">authmethods</span><span class="o">/</span><span class="n">shibauth</span><span class="p">.</span><span class="n">php</span>"<span class="p">);</span>
+</pre></div>
+
+
+<h2 id="test-the-login-process">Test the login process</h2>
+<p>At this point, you should be able to login via shibboleth. A user account will be created for you
+and if there is an <code>affiliation</code> attribute sent from the IdP, you will be placed into any groups listed
+there: for instance, if the <code>affiliation</code> attribute is <code>faculty;staff</code>, then the user will be placed in the
+<code>shib-faculty@AFFILIATION</code> and <code>shib-staff@AFFILIATION</code> groups. You should confirm that this works.
+Please also note that Shibboleth uses the word affiliation to refer to groups that a user is associated with;
+for example, "employee" or "student". The VCL uses the word affiliation to refer to an institution that uses
+the system. This can be confusing.</p>
+<h2 id="further-configuration">Further configuration</h2>
+<p>If you wish to further customize how Shibboleth works, you can edit the <code>shibauth/index.php</code> file.
+If, for instance, you wish to add all users to an <code>All users@AFFILIATION</code> group, then add this line of
+code (after the <code>$affilid</code> variable has been defined):</p>
+<div class="codehilite"><pre><span class="n">updateGroups</span><span class="p">(</span><span class="n">array</span><span class="p">(</span><span class="n">getUserGroupID</span><span class="p">(</span><span class="s">'All users'</span><span class="p">,</span> $<span class="n">affilid</span><span class="p">)),</span> $<span class="n">usernid</span><span class="p">);</span>
+</pre></div>
+
+
+<p>This file would also be a good place to define a <code>Shib-logouturl</code> and a <code>Shib-IdP-Logout</code> value in the
+<code>$shibdata</code> array. More about that below.</p>
+<h2 id="logging-out">Logging out</h2>
+<p>Logging out is very complicated when it comes to Shibboleth. The best way to log out is to completely
+close (i.e. quit) your browser. However, if you would like the "logout" link to work as users will generally
+expect, these instructions will explain how to set that up.</p>
+<p><strong>Please note</strong>: these instructions do not describe the so-called "global logout". That is, these examples
+only provide a means for logging the user out of the VCL. If a user is also logged into another shibbolized
+application, he or she will continue (depending to some degree on the server settings) to be logged in to
+that application, even after logging out of the VCL.</p>
+<p>The main thing to realize is that for any shib-enabled VCL session, there are (at least) three session cookies,
+and for a user to truly "logout", all three of them must be destroyed. The first cookie is the VCL application
+cookie, "VCLAUTH". That can be destroyed by overwriting it from within the VCL application -- this typically
+happens automatically. </p>
+<p>The next cookie is the for the SP session. If that cookie continues to exist, then when a browser lands on
+the <code>/shibauth</code> directory, the previous SP session will be used and the user will be immediately back in the
+application. To destroy the SP session, you need to issue a GET request to <code>/Shibboleth.sso/Logout</code>.</p>
+<p>The third cookie exists on the IdP. If that cookie isn't destroyed (and hasn't timed out), then the next time a
+user is redirected to the IdP, she or he will be immediately be sent back to the SP with a valid session -- and then
+on to the application with a valid session. To destroy the cookie on the IdP, you will need to have code placed
+there to destroy the cookie. If the IdP cookie is named _idp_session, then you could, for instance, have a script
+on the IdP that looks like this:</p>
+<div class="codehilite"><pre>https://idp.yourinstitution.edu/logout.php
+
+<span class="cp"><?php</span>
+<span class="nx">setcookie</span><span class="p">(</span><span class="nx">_idp_session</span><span class="s2">", 0, 0, "</span><span class="o">/</span><span class="nx">idp</span><span class="s2">", "", TRUE);</span>
+<span class="s2">header("</span><span class="nx">Content</span><span class="o">-</span><span class="nx">type</span><span class="o">:</span> <span class="nx">text</span><span class="o">/</span><span class="nx">html</span><span class="s2">");</span>
+<span class="s2">?></span>
+<span class="s2"><!DOCTYPE html></span>
+<span class="s2"><html lang="</span><span class="nx">en</span><span class="s2">"></span>
+<span class="s2"><head><title>Session Logout</title></head></span>
+<span class="s2"><body></span>
+<span class="s2"> <h1>Session Logout</h1></span>
+<span class="s2"> <p>You have logged out of your application session.</p></span>
+<span class="s2"></body></span>
+<span class="s2"></html></span>
+</pre></div>
+
+
+<p>The way the VCL handles logout is that it loads a page that overwrites the application cookie and which loads
+two hidden iframes -- the first one destroys the SP cookie, and the second one tries to destroy the IdP cookie.
+The problem is just that it assumes your IdP logout script is located at this address:</p>
+<div class="codehilite"><pre><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">MYIDP</span><span class="o">/</span><span class="n">idp</span><span class="o">/</span><span class="n">logout</span><span class="p">.</span><span class="n">jsp</span>
+</pre></div>
+
+
+<p>The best way to override this behavior is to modify the <code>shibauth/index.php</code> script and set a <code>Shib-logouturl</code>
+value in the <code>$shibdata</code> array. You may also want to define a value for <code>Shib-IdP-Logout</code> so that it is
+available to your script. This is useful if there are multiple institutions using your VCL system.</p>
+<p>That should be a path to a file within the VCL web directory, such as <code>/logout.php</code>.</p>
+<p>You can then customize this new file to display whatever you like; here is a bare-bones example:</p>
+<div class="codehilite"><pre><span class="cp"><?php</span>
+<span class="k">require_once</span><span class="p">(</span><span class="s2">".ht-inc/conf.php"</span><span class="p">);</span>
+<span class="k">require_once</span><span class="p">(</span><span class="s2">".ht-inc/utils.php"</span><span class="p">);</span>
+<span class="k">require_once</span><span class="p">(</span><span class="s2">".ht-inc/states.php"</span><span class="p">);</span>
+<span class="nx">dbConnect</span><span class="p">();</span>
+<span class="nx">initGlobals</span><span class="p">();</span>
+
+<span class="nv">$shibdata</span> <span class="o">=</span> <span class="nx">getShibauthData</span><span class="p">(</span><span class="nv">$shibauthed</span><span class="p">);</span>
+
+<span class="nx">setcookie</span><span class="p">(</span><span class="s2">"VCLAUTH"</span><span class="p">,</span> <span class="s2">""</span><span class="p">,</span> <span class="nb">time</span><span class="p">()</span> <span class="o">-</span> <span class="mi">10</span><span class="p">,</span> <span class="s2">"/"</span><span class="p">,</span> <span class="nx">COOKIEDOMAIN</span><span class="p">);</span>
+
+<span class="nx">doQuery</span><span class="p">(</span><span class="s2">"DELETE FROM shibauth WHERE id = </span><span class="si">$shibauthed</span><span class="s2">"</span><span class="p">,</span> <span class="mi">101</span><span class="p">);</span>
+<span class="nx">stopSession</span><span class="p">();</span>
+<span class="nx">dbDisconnect</span><span class="p">();</span>
+<span class="cp">?></span>
+<span class="cp"><!DOCTYPE html></span>
+<span class="nt"><html</span> <span class="na">lang=</span><span class="s">"en"</span><span class="nt">></span>
+<span class="nt"><head></span>
+ <span class="nt"><title></span>Virtual Computing Lab<span class="nt"></title></span>
+ <span class="nt"><style</span> <span class="na">type=</span><span class="s">"text/css"</span><span class="nt">></span>
+ iframe { display: none; }
+ article { text-align: center; }
+ <span class="nt"></style></span>
+<span class="nt"></head></span>
+<span class="nt"><body></span>
+ <span class="nt"><header></span>
+ <span class="nt"><h1><a</span> <span class="na">href=</span><span class="s">"https://vcl.MYINSTITUTION.edu"</span><span class="nt">></span>Virtual Computing Lab<span class="nt"></a></h1></span>
+ <span class="nt"></header></span>
+ <span class="nt"><article></span>
+ <span class="nt"><h2></span>Logging out of the VCL...<span class="nt"></h2></span>
+ <span class="nt"><p></span>In order to completely log out of this application, please quit your browser.<span class="nt"></p></span>
+ <span class="nt"></article></span>
+ <span class="nt"><iframe</span> <span class="na">src=</span><span class="s">"https://</span><span class="cp"><?php</span> <span class="k">print</span> <span class="nv">$_SERVER</span><span class="p">[</span><span class="s1">'SERVER_NAME'</span><span class="p">];</span> <span class="cp">?></span><span class="s">/Shibboleth.sso/Logout"</span><span class="nt">></span>
+ <span class="nt"></iframe></span>
+<span class="cp"><?php</span>
+<span class="k">if</span><span class="p">(</span><span class="nb">array_key_exists</span><span class="p">(</span><span class="s1">'Shib-IdP-Logout'</span><span class="p">,</span> <span class="nv">$shibdata</span><span class="p">)</span> <span class="o">&&</span>
+ <span class="o">!</span> <span class="k">empty</span><span class="p">(</span><span class="nv">$shibdata</span><span class="p">[</span><span class="s1">'Shib-IdP-Logout'</span><span class="p">]))</span> <span class="p">{</span>
+ <span class="k">print</span> <span class="s2">"<iframe src=</span><span class="se">\"</span><span class="si">{</span><span class="nv">$shibdata</span><span class="p">[</span><span class="s1">'Shib-IdP-Logout'</span><span class="p">]</span><span class="si">}</span><span class="se">\"</span><span class="s2">></span><span class="se">\n</span><span class="s2">"</span><span class="p">;</span>
+ <span class="k">print</span> <span class="s2">"</iframe></span><span class="se">\n</span><span class="s2">"</span><span class="p">;</span>
+<span class="p">}</span>
+<span class="cp">?></span>
+<span class="nt"></body></span>
+<span class="nt"></html></span>
+</pre></div>
</div>
<div id="footer">