[LON-CAPA-cvs] cvs: doc /help domain.manual.texxml loncom/html/adm/help/tex Institutional_Integration_Shibboleth.tex

raeburn raeburn at source.lon-capa.org
Sun Sep 7 09:12:05 EDT 2014


raeburn		Sun Sep  7 13:12:05 2014 EDT

  Added files:                 
    /loncom/html/adm/help/tex	Institutional_Integration_Shibboleth.tex 

  Modified files:              
    /doc/help	domain.manual.texxml 
  Log:
  - Bug 6733
  Documentation for Shibboleth Authentication 
  
  
-------------- next part --------------
Index: doc/help/domain.manual.texxml
diff -u doc/help/domain.manual.texxml:1.15 doc/help/domain.manual.texxml:1.16
--- doc/help/domain.manual.texxml:1.15	Thu Jun 26 21:09:13 2014
+++ doc/help/domain.manual.texxml	Sun Sep  7 13:12:05 2014
@@ -87,9 +87,12 @@
         </subsection>
 </section>
 <section name="Integration with Institutional Systems">
-    <subsection name="Institutional Authentication">
+    <subsection name="Institutional Authentication (non-SSO)">
         <file name="Institutional_Integration_Authentication.tex">
     </subsection>
+    <subsection name="Shibboleth Authentication (SSO)">
+        <file name="Institutional_Integration_Shibboleth.tex">
+    </subsection>
     <subsection name="Institutional User Categories/Affiliations">
         <file name="Institutional_Integration_User_Categories.tex">
     </subsection>

Index: loncom/html/adm/help/tex/Institutional_Integration_Shibboleth.tex
+++ loncom/html/adm/help/tex/Institutional_Integration_Shibboleth.tex
\label{Institutional_Integration_Shibboleth}

If your institution operates a Shibboleth Identity Provider (IdP) for your
users, then you can configure a LON-CAPA server to authenticate users by
running your server as a Shibboleth Service Provider (SP). 

To configure a LON-CAPA server as a Shibboleth SP you will need to:

\begin{itemize}
\item Install Shibboleth packages for your Linux distro, or build/install from source
\item Modify your Apache configuration to include shib.conf (which will load mod\_shib)
\item Set shibd to start on boot
\item Install mod\_ssl and Apache/SSL certificates
\item Configure your SP to work with your institution's IdP
\item Add a custom Apache config file to include some PerlVars (for logout etc.)
\end{itemize}

Although Shibboleth can be built on any 32 or 64 bit Linux distro on which LON-CAPA is supported,
official packages are available from http://shibboleth.net for: Red Hat/CentOS 5, 6 and 7,
SLES 10 & 11, and openSuSE 12.1, 12.2, and 12.3.
In addition, http://www.switch.ch provides a repository from which shibboleth packages
may be obtained for Ubuntu 12.04 LTS and 14.04 LTS.


\begin{enumerate}

\item Install Shibboleth

See:
https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxInstall

Shibboleth repos for RPM-based Linux distros can be found at:

http://download.opensuse.org/repositories/security:/shibboleth/

Red Hat/CentOS -- add shibboleth.repo to /etc/yum.repos.d

e.g., CentOS 5

\begin{verbatim}

[security_shibboleth]
name=Shibboleth (CentOS_5)
type=rpm-md
baseurl=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_5/
gpgcheck=1
gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_5/
repodata/repomd.xml.key
enabled=1
\end{verbatim}

e.g., CentOS 6

\begin{verbatim}

[security_shibboleth]
name=Shibboleth (CentOS_6)
type=rpm-md
baseurl=http://download.opensuse.org/repositories/security:/shibboleth/
CentOS_CentOS-6/
gpgcheck=1
gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/
CentOS_CentOS-6/repodata/repomd.xml.key
enabled=1
\end{verbatim}

Then do:
\begin{verbatim}
yum install shibboleth
\end{verbatim}

SLES/openSuSE:

e.g. SLES 11 SP3:

\begin{verbatim}
zypper addrepo http://download.opensuse.org/repositories/security:shibboleth/
SLE_11_SP3/security:shibboleth.repo
zypper refresh
zypper install shibboleth
\end{verbatim}

e.g. SuSE 12.3
\begin{verbatim}
zypper addrepo http://download.opensuse.org/repositories/security:shibboleth/
openSUSE_12.3/security:shibboleth.repo
zypper refresh
zypper install shibboleth
\end{verbatim}

e.g., Ubuntu 12.04LTS

See: https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.5/sp/deployment/?os=ubuntu

\begin{verbatim}
sudo apt-get install curl
sudo curl -k -O http://pkg.switch.ch/switchaai/SWITCHaai-swdistrib.asc
sudo apt-key add SWITCHaai-swdistrib.asc
echo 'deb http://pkg.switch.ch/switchaai/ubuntu precise main' | 
sudo tee /etc/apt/sources.list.d/SWITCHaai-swdistrib.list $>$ /dev/null
sudo apt-get update
sudo apt-get install shibboleth
\end{verbatim}

The following directories will have now been created:

/etc/shibboleth

/var/log/shibboleth

/var/run/shibboleth

/var/cache/shibboleth



\item Apache configuration

Red Hat/CentOS -- httpd.conf should be modified to contain:
\begin{quotation} 
\texttt{UseCanonicalName On}

\texttt{Include conf/shib.conf}
\end{quotation}

The Include should precede the line: Include conf/loncapa\_apache.conf

SLES/SuSE -- modify /etc/apache2/default-server.conf and /etc/sysconfig/apache2

Modify /etc/sysconfig/apache2 to include:
\begin{quotation}
\texttt{APACHE\_USE\_CANONICAL\_NAME=``on''}
\end{quotation}

Modify /etc/apache2/default-server.conf to contain:
\begin{quotation}
\texttt{Include conf/shib.conf}
\end{quotation}

The Include should precede the line: Include conf/loncapa\_apache.conf

Note: the shib.conf file should include: ShibUseHeaders Off
so that environment variables can be used to access user attributes, if needed.

\item Set shibd to start on boot
\begin{quotation}
\texttt{/sbin/chkconfig shibd on}
\end{quotation}


\item Install mod\_ssl and Apache/SSL certificates
\begin{enumerate}
\item Red Hat/CentOS
\begin{quotation}
\texttt{yum install mod\_ssl}
\end{quotation}


\item SuSE/SLES

Use yast -$>$ Network Services -$>$ HTTP Server -$>$ Server Modules to set ssl to enabled, and rewrite to enabled


\item Ubuntu

\begin{quotation}
\texttt{sudo a2enmod ssl}

\texttt{sudo a2enmod rewrite}

\texttt{sudo a2ensite default-ssl.conf}
\end{quotation}

Edit default-ssl.conf
replace ``DocumentRoot /var/www/html'' with ``DocumentRoot /home/httpd/html''
\end{enumerate}

You also need to create an SSL certificate signing request and have it signed by a certificate authority,
before installing the signed certificate and the corresponding key. Also you will need to open port 443
in the firewall, and enable rewrites of http to https (see ``Encrypting server traffic with SSL'' 
\ref{Domain_Configuration_SSL} section for more information).

\item Configure your SP to work with your institution's IdP

Before customizing your Shibboleth SP to work with your IdP it is recommended to test the default configuration.

/usr/sbin/shibd -t should report:

overall configuration is loadable, check console for non-fatal problems

After restarting your Apache server, the result of accessing the URL:
 
https://$<$yourserver.edu$>$/Shibboleth.sso/Session

should be: ``A valid session was not found.''

A Shibboleth SP can also be tested with http://testshib.org/

Once preliminary testing is complete you will need to edit /etc/shibboleth/shibboleth2.xml 
based on information provided by your institution, for your SP to work with the appropriate IdP. 
At a minimum the shibboleth2.xml file will need to contain the service hostname of your LON-CAPA server, 
and the SP entityID.  You should also set an e-mail address, for users to contact in case of errors.

e.g.,

\begin{verbatim}

<SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    
    xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
    logger="syslog.logger" clockSkew="180">

    <InProcess logger="native.logger"> 
        <ISAPI normalizeRequest="true" safeHeaderNames="true">
            <Site id="1" name="yourserver.someplace.edu"/>
        </ISAPI>
    </InProcess>

    <Host name="yourserver.someplace.edu">
        <Path name="secure" authType="shibboleth" requireSession="true"/>
    </Host>

    <ApplicationDefaults id="default" policyId="default"
        entityID="https://yourserver.someplace.edu/shibboleth"
        REMOTE_USER="eppn persistent-id targeted-id"
        signing="false" encryption="false">

        <Sessions lifetime="28800" timeout="3600" checkAddress="false"
            handlerURL="/Shibboleth.sso" handlerSSL="true"

        </Sessions>
 
        <Errors supportContact="helpdesk at someplace.edu"
            logoLocation="/shibboleth-sp/logo.jpg"
            styleSheet="/shibboleth-sp/main.css"/>
    </ApplicationDefaults>
</SPConfig>

\end{verbatim}

REMOTE\_USER is used to pass on the primary identifier of the authenticated user.  It should be set
to match an attribute or alias defined in the attribute-map.xml file.  LON-CAPA uses this value
(\$r-$>$user in the mod\_perl environment) as the username of the user. The user's domain will be
either the value of the PerlVar lonSSOUserDomain, or if that is undefined, the PerlVar lonDefDomain.
If the attribute used for REMOTE\_USER is in the form: username at somewhere.edu, and somewhere.edu is
the ``internet domain'' (i.e., the last item in the colon separated list of entries for your server
in /home/httpd/lonTabs/hosts.tab), then LON-CAPA will automatically remove the @somewhere.edu, such
that \$r-$>$user will be just username.

\item Add a custom Apache config file to include some PerlVars (for logout etc.)

Add a file to your Apache conf directory named loncapa\_apache\_local$<$dom$>$.conf, where $<$dom$>$ 
is domain, to include items such as:

\begin{verbatim}
PerlSetVar lonSSOUserLogoutMessageFile 
/home/httpd/html/adm/sso_logout_link_html_frag
PerlSetVar lonSSOUserUnknownRedirect /adm/sso_failed_login.html
PerlSetVar lonSSOUserDomain <dom>
\end{verbatim}

and add the corresponding files owned by www:www in /home/httpd/html/adm/

Notes:
\begin{enumerate}
\item
Both files contain HTML mark-up, but the logout link is just a fragment which will
be inserted into the standard LON-CAPA logout page, whereas the sso\_failed\_login.html file
should be a complete HTML document.

\item
SAML 2 Single Logout (SLO) has limited support starting with IdP's running Shibboleth 2.4.
The $<$Logout$>$ element is used to enable and configure support for Logout protocols and behavior 
within the SP, e.g., 
\begin{verbatim}
<Logout>SAML2 Local</Logout>
\end{verbatim}
to support both local, i.e., for the SP itself (Local), and also in a limited way for the IdP (SAML2).  
In pre-2.4 Shibboleth2 /etc/shibboleth2.xml LogoutInitiators enable SP-initiated local logout
e.g.,  https://yourserver/Shibboleth.sso/Logout.

Depending on the availability of SLO support from your institution's IdP you should craft an appropriate 
message to include in sso\_logout\_link\_html\_frag. If you include a link to the URL for a local logout,
you should indicate that access to other web applications using SSO may continue to be available, even
after logout from the specific SP.  If no local logout is provided, then after logout from LON-CAPA,
the web browser needs to be quit, to ensure access to LON-CAPA requires re-authentication.

\item
If you enable self-creation of SSO-authenticated users, then the sso\_failed\_login.html
document need not be created.

Attributes provided to the SP by the IdP are available to LON-CAPA as Environment variables.
For Shibboleth SSO users, mapping of Shibboleth environment variable names to user data fields 
can be set so that the appropriate user information is available at account creation time. The
mapping of variable name to LON-CAPA data name will be set by a domain cordinator using the 
domain configuration screen for ``Users self-creating accounts''.

Note: user data for a new user need not come from Environment variables populated by Shibboeth;
instead it can come from a customized get\_userinfo() routine in /home/httpd/lib/perl/localenroll.pm
(see Directory Information \ref{Institutional_Integration_Identity_Management} section).

\end{enumerate}

e.g., sso\_logout\_link\_html\_frag

\begin{verbatim}

<p>
As your original log-in to LON-CAPA was authenticated by a central Shibboleth 
Single Sign On service, your Shibboleth credentials are still valid.<br />
Until you close your web browser, web applications which support Shibboleth 
Single Sign-on (including LON-CAPA) will not require you to re-enter your 
username and password</p> 
<p>
To expire your active Shibboleth authentication token you must quit your web 
browser.
</p>

\end{verbatim}

e.g., sso\_failed\_login.html

\begin{verbatim}

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">

<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
<title>No LON-CAPA Account</title>
</head>
<body bgcolor="#ffffff">
<p>
You have authentication using Shibboleth Single Sign On service was 
successful.<br />
However, you do not currently have a LON-CAPA account with the username 
with which you authenticated.<br />
Policies at your institution do not allow you to create a LON-CAPA account 
yourself, after successful authentication. 
Please contact the <a href="/adm/helpdesk">LON-CAPA Helpdesk</a> for your 
domain.
</p>
<p>
Your Shibboleth credentials are still valid.<br />
Until you close your web browser, web applications which support Shibboleth 
Single Sign-on will not require you to re-enter your username and password
</p>
<p>
To expire your active Shibboleth authentication token you must quit your web 
browser.
</p>
</body>
</html>

\end{verbatim}

\end{enumerate}


More information about the LON-CAPA-cvs mailing list