Return to Institutional_Integration_Shibboleth.tex CVS log

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

- Maintain alignment of text in PDF version of domain coordination 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 via http://shibboleth.net for: Red Hat/CentOS 5, 6, 7, and 8,
and SLES 11, and 12. For SLES 12 and 15 shibboleth is available from suse.com, and for Ubuntu, 
Shibboleth packages are available from standard repos for Ubuntu 14.04, 16.04, 18.04 and 20.04.

\begin{enumerate}

\item Install Shibboleth

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

For Red Hat/CentOS the text to include in a shibboleth.repo file to be placed in
/etc/yum.repos.d can be generated at:

https://shibboleth.net/downloads/service-provider/RPMS/

e.g., CentOS 6

\begin{verbatim}
[shibboleth]
name=Shibboleth (CentOS_CentOS-6)
type=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_CentOS-6
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
        https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1
\end{verbatim}

e.g., CentOS 7

\begin{verbatim}
[shibboleth]
name=Shibboleth (CentOS_7)
type=rpm-md
mirrorlist=https://shibboleth.net/cgi-bin/mirrorlist.cgi/CentOS_7
gpgcheck=1
gpgkey=https://shibboleth.net/downloads/service-provider/RPMS/repomd.xml.key
        https://shibboleth.net/downloads/service-provider/RPMS/cantor.repomd.xml.key
enabled=1
\end{verbatim}

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

SLES:

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. SLES 12 SP5

\begin{verbatim}
SUSEConnect -p SLES/12.5/x86_64 -r <registration-code>
zypper install shibboleth-sp-2.5.5-6.6.1
\end{verbatim}

e.g., SLES 15 SP4
\begin{verbatim}
SUSEConnect -p sle-module-server-applications/15.4/x86_64
zypper install shibboleth-sp-3.1.0-3.3.1
\end{verbatim}

e.g., Ubuntu 20.04LTS

\begin{verbatim}
sudo apt install --install-recommends 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, unless the value of the PerlVar lonSSOEmailOK is 1. 

By default, with mod\_shib installed and configured, and shibd running, then entries in LON-CAPA's
Apache config file: loncapa\_apache.conf will result in display of an authentication 
prompt when a user without a current LON-CAPA session accesses /adm/roles.  If it is preferred
to display /adm/login configured to offer dual SSO log-in (Shibboleth), and non-SSO login
(LON-CAPA), set this using the Domain Configuration available to a Domain Coordinator via the web GUI:
Main Menu $>$ Set domain configuration $>$ Display (``Log-in page options'' checked).
For any of the LON-CAPA domain's servers which will offer dual login check ``Yes'' and then set:

\begin{itemize}
\item SSO: Text, Image, Alt Text, URL, Tool Tip
\item non-SSO: Text
\end{itemize}

The value in the URL field should be /adm/sso, and the image will be for a button to be clicked
to load /adm/sso to prompt for Shibboleth authentication. The alt and title attributes for the
button can also be set. Above the button there will be the text: ``Log-in type: '' followed by
the text entered in the SSO configuration for ``Text''. Below that will be a ``Change'' link
used to toggle between SSO and non-SSO log-in panels. 

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