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

[raeburn]

raeburn		Thu Mar 26 16:05:28 2015 EDT

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

  Modified files:              
    /doc/help	domain.manual.texxml 
  Log:
  - Document SSO Authentication for a central authentication service (CAS).  
  
  
Index: doc/help/domain.manual.texxml
diff -u doc/help/domain.manual.texxml:1.16 doc/help/domain.manual.texxml:1.17
--- doc/help/domain.manual.texxml:1.16	Sun Sep  7 13:12:05 2014
+++ doc/help/domain.manual.texxml	Thu Mar 26 16:05:28 2015
@@ -93,6 +93,9 @@
     <subsection name="Shibboleth Authentication (SSO)">
         <file name="Institutional_Integration_Shibboleth.tex">
     </subsection>
+    <subsection name="CAS Authentication (SSO)">
+        <file name="Institutional_Integration_CAS.tex">
+    </subsection>
     <subsection name="Institutional User Categories/Affiliations">
         <file name="Institutional_Integration_User_Categories.tex">
     </subsection>

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

The procedure for enabling institutional Single Sign On (SSO) via a central authentication 
service (CAS) that is not Shibboleth involves building or installing an Apache module provided 
by you institution, and then modifying an Apache configuration file on your LON-CAPA server to
(a) load the module, and (b) configure LON-CAPA to use it, by default, when unauthenticated users 
access /adm/roles.

If your server will be part of the cluster of collaborating institutions, it is possible
that users from other LON-CAPA domains might visit your server to log-in to LON-CAPA.
To support that possibility, it is recommended that the CAS log-in page includes a link to point 
back at /adm/login on your LON-CAPA server, and the link is identified as one to be followed by 
users from other domains.  See: https://loncapa.msu.edu/adm/roles for an example.

In order for Apache to use your CAS system you need to set the PerlVar lonOtherAuthen to yes,
and provide the default domain for SSO users and the authentication type (i.e., the name of
your CAS).

\begin{itemize}

\item Add a custom Apache config file to include some required PerlVars and load the CAS shared object.

\begin{verbatim}
PerlSetVar lonOtherAuthen yes
PerlSetVar lonOtherAuthenType MyCAS
PerlSetVar lonSSOUserDomain <dom>

LoadModule mod_sentinel modules/mod_mycas.so
\end{verbatim}

where $<$dom$>$ is your domain, and mod\_mycas.so is ths name of the CAS shared object. 
You might put the config file (mycas.conf) in: /etc/httpd/conf.d/ 
(CentOS/Red Hat/Scientific Linux), or in /etc/apache2/conf.d/ (SuSE/SLES) or 
/etc/apache2/conf-available (Ubuntu, and enabled with: sudo a2enconf). 

\item Add a custom Apache config file to include some optional 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_frag
PerlSetVar lonSSOUserLogoutMessageFile_<dom> /home/httpd/html/adm/sso_logout_body_frag
PerlSetVar lonSSOUserUnknownRedirect /adm/sso_failed_login.html
PerlSetVar lonSSOReloginServer https://somehost.somewhere.edu
\end{verbatim}

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

\end{itemize}

Notes:
\begin{enumerate}
\item
All files will contain HTML mark-up, but the sso\_logout\_head\_frag item is a fragment
inserted into the head block of the standard LON-CAPA logout page, and similarly,
the sso\_logout\_body\_frag 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
If you enable self-creation of SSO-authenticated users, then the sso\_failed\_login.html
document need not be created.

\item
If you would like the log-in again link on the logout page to point to a specific URL 
just for SSO users, then you would set the PerlVar for lonSSOReloginServer. However, if 
you would like the log-in link for all users from your domain (both SSO and non-SSO 
authenticated) to point at a particular URL, then you would log-in to LON-CAPA, select
a Domain Coordinator role, and use Main Menu -$>$ Set domain configuration -$>$ 
Display (``Default authentication/language/timezone/portal/types'' checked) an set the URL
in ``Portal/Default URL''.

\end{enumerate}