Return to Institutional_Integration_Shibboleth.tex CVS log

Up to [LON-CAPA] / loncom / html / adm / help / tex

- Shorter names for example files containing custom markup for inclusion in
  logout page fit within the width of a page in the PDF manual.

\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 and 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@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@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 lonSSOUserLogoutHeadFile_<dom>/home/httpd/html/adm/sso_logout_head
PerlSetVar lonSSOUserLogoutMessageFile_<dom> /home/httpd/html/adm/sso_logout_body
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
All files will contain HTML mark-up, but the sso\_logout\_head item is a fragment 
inserted into the head block of the standard LON-CAPA logout page, and similarly,
the sso\_logout\_body is a fragment inserted into the body of the page, 
whereas the sso\_failed\_login.html file should be a complete HTML document.

If the name of the PerlVar ends \_$<$dom$>$ then the HTML fragment is only displayed
to SSO users from that particular domain.  It is possible that a LON-CAPA user from another
domain might have used SSO authentication on a server in his/her home domain, and then switched
session to your server, (e.g., for co-author access to an Authoring Space in your domain).
In that particular case, if you wanted to display custom HTML, you should add a PerlVar with a 
name ending in \_$<$otherdom$>$. If you include PerlVars for lonSSOUserLogoutHeadFile
and/or lonSSOUserLogoutMessageFile they will be included for SSO users who use the Logout link
on your LON-CAPA regardless of the user's domain.

\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\_body. 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\_body

\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}