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

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       lon-capa-cvs
Subject:    [LON-CAPA-cvs] cvs: doc /help domain.manual.texxml loncom/html/adm/help/tex Institutional_Integratio
From:       raeburn <raeburn () source ! lon-capa ! org>
Date:       2014-09-07 13:12:05
Message-ID: cvsraeburn1410095525 () cvsserver
[Download RAW message or body]

This is a MIME encoded message


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 
  
  
["raeburn-20140907131205.txt" (text/plain)]

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



_______________________________________________
LON-CAPA-cvs mailing list
LON-CAPA-cvs@mail.lon-capa.org
http://mail.lon-capa.org/mailman/listinfo/lon-capa-cvs


[prev in list] [next in list] [prev in thread] [next in thread] 
