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.

    1: \label{Institutional_Integration_Shibboleth}
    2: 
    3: If your institution operates a Shibboleth Identity Provider (IdP) for your
    4: users, then you can configure a LON-CAPA server to authenticate users by
    5: running your server as a Shibboleth Service Provider (SP). 
    6: 
    7: To configure a LON-CAPA server as a Shibboleth SP you will need to:
    8: 
    9: \begin{itemize}
   10: \item Install Shibboleth packages for your Linux distro, or build/install from source
   11: \item Modify your Apache configuration to include shib.conf (which will load mod\_shib)
   12: \item Set shibd to start on boot
   13: \item Install mod\_ssl and Apache/SSL certificates
   14: \item Configure your SP to work with your institution's IdP
   15: \item Add a custom Apache config file to include some PerlVars (for logout etc.)
   16: \end{itemize}
   17: 
   18: Although Shibboleth can be built on any 32 or 64 bit Linux distro on which LON-CAPA is supported,
   19: official packages are available from http://shibboleth.net for: Red Hat/CentOS 5, 6 and 7,
   20: SLES 10 and 11, and openSuSE 12.1, 12.2, and 12.3.
   21: In addition, http://www.switch.ch provides a repository from which shibboleth packages
   22: may be obtained for Ubuntu 12.04 LTS and 14.04 LTS.
   23: 
   24: 
   25: \begin{enumerate}
   26: 
   27: \item Install Shibboleth
   28: 
   29: See:
   30: https://wiki.shibboleth.net/confluence/display/SHIB2/NativeSPLinuxInstall
   31: 
   32: Shibboleth repos for RPM-based Linux distros can be found at:
   33: 
   34: http://download.opensuse.org/repositories/security:/shibboleth/
   35: 
   36: Red Hat/CentOS -- add shibboleth.repo to /etc/yum.repos.d
   37: 
   38: e.g., CentOS 5
   39: 
   40: \begin{verbatim}
   41: 
   42: [security_shibboleth]
   43: name=Shibboleth (CentOS_5)
   44: type=rpm-md
   45: baseurl=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_5/
   46: gpgcheck=1
   47: gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/CentOS_5/
   48: repodata/repomd.xml.key
   49: enabled=1
   50: \end{verbatim}
   51: 
   52: e.g., CentOS 6
   53: 
   54: \begin{verbatim}
   55: 
   56: [security_shibboleth]
   57: name=Shibboleth (CentOS_6)
   58: type=rpm-md
   59: baseurl=http://download.opensuse.org/repositories/security:/shibboleth/
   60: CentOS_CentOS-6/
   61: gpgcheck=1
   62: gpgkey=http://download.opensuse.org/repositories/security:/shibboleth/
   63: CentOS_CentOS-6/repodata/repomd.xml.key
   64: enabled=1
   65: \end{verbatim}
   66: 
   67: Then do:
   68: \begin{verbatim}
   69: yum install shibboleth
   70: \end{verbatim}
   71: 
   72: SLES/openSuSE:
   73: 
   74: e.g. SLES 11 SP3:
   75: 
   76: \begin{verbatim}
   77: zypper addrepo http://download.opensuse.org/repositories/security:shibboleth/
   78: SLE_11_SP3/security:shibboleth.repo
   79: zypper refresh
   80: zypper install shibboleth
   81: \end{verbatim}
   82: 
   83: e.g. SuSE 12.3
   84: \begin{verbatim}
   85: zypper addrepo http://download.opensuse.org/repositories/security:shibboleth/
   86: openSUSE_12.3/security:shibboleth.repo
   87: zypper refresh
   88: zypper install shibboleth
   89: \end{verbatim}
   90: 
   91: e.g., Ubuntu 12.04LTS
   92: 
   93: See: https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.5/sp/deployment/?os=ubuntu
   94: 
   95: \begin{verbatim}
   96: sudo apt-get install curl
   97: sudo curl -k -O http://pkg.switch.ch/switchaai/SWITCHaai-swdistrib.asc
   98: sudo apt-key add SWITCHaai-swdistrib.asc
   99: echo 'deb http://pkg.switch.ch/switchaai/ubuntu precise main' | 
  100: sudo tee /etc/apt/sources.list.d/SWITCHaai-swdistrib.list $>$ /dev/null
  101: sudo apt-get update
  102: sudo apt-get install shibboleth
  103: \end{verbatim}
  104: 
  105: The following directories will have now been created:
  106: 
  107: /etc/shibboleth
  108: 
  109: /var/log/shibboleth
  110: 
  111: /var/run/shibboleth
  112: 
  113: /var/cache/shibboleth
  114: 
  115: 
  116: 
  117: \item Apache configuration
  118: 
  119: Red Hat/CentOS -- httpd.conf should be modified to contain:
  120: \begin{quotation} 
  121: \texttt{UseCanonicalName On}
  122: 
  123: \texttt{Include conf/shib.conf}
  124: \end{quotation}
  125: 
  126: The Include should precede the line: Include conf/loncapa\_apache.conf
  127: 
  128: SLES/SuSE -- modify /etc/apache2/default-server.conf and /etc/sysconfig/apache2
  129: 
  130: Modify /etc/sysconfig/apache2 to include:
  131: \begin{quotation}
  132: \texttt{APACHE\_USE\_CANONICAL\_NAME=``on''}
  133: \end{quotation}
  134: 
  135: Modify /etc/apache2/default-server.conf to contain:
  136: \begin{quotation}
  137: \texttt{Include conf/shib.conf}
  138: \end{quotation}
  139: 
  140: The Include should precede the line: Include conf/loncapa\_apache.conf
  141: 
  142: Note: the shib.conf file should include: ShibUseHeaders Off
  143: so that environment variables can be used to access user attributes, if needed.
  144: 
  145: \item Set shibd to start on boot
  146: \begin{quotation}
  147: \texttt{/sbin/chkconfig shibd on}
  148: \end{quotation}
  149: 
  150: 
  151: \item Install mod\_ssl and Apache/SSL certificates
  152: \begin{enumerate}
  153: \item Red Hat/CentOS
  154: \begin{quotation}
  155: \texttt{yum install mod\_ssl}
  156: \end{quotation}
  157: 
  158: 
  159: \item SuSE/SLES
  160: 
  161: Use yast -$>$ Network Services -$>$ HTTP Server -$>$ Server Modules to set ssl to enabled, and rewrite to enabled
  162: 
  163: 
  164: \item Ubuntu
  165: 
  166: \begin{quotation}
  167: \texttt{sudo a2enmod ssl}
  168: 
  169: \texttt{sudo a2enmod rewrite}
  170: 
  171: \texttt{sudo a2ensite default-ssl.conf}
  172: \end{quotation}
  173: 
  174: Edit default-ssl.conf
  175: replace ``DocumentRoot /var/www/html'' with ``DocumentRoot /home/httpd/html''
  176: \end{enumerate}
  177: 
  178: You also need to create an SSL certificate signing request and have it signed by a certificate authority,
  179: before installing the signed certificate and the corresponding key. Also you will need to open port 443
  180: in the firewall, and enable rewrites of http to https (see ``Encrypting server traffic with SSL'' 
  181: \ref{Domain_Configuration_SSL} section for more information).
  182: 
  183: \item Configure your SP to work with your institution's IdP
  184: 
  185: Before customizing your Shibboleth SP to work with your IdP it is recommended to test the default configuration.
  186: 
  187: /usr/sbin/shibd -t should report:
  188: 
  189: overall configuration is loadable, check console for non-fatal problems
  190: 
  191: After restarting your Apache server, the result of accessing the URL:
  192:  
  193: https://$<$yourserver.edu$>$/Shibboleth.sso/Session
  194: 
  195: should be: ``A valid session was not found.''
  196: 
  197: A Shibboleth SP can also be tested with http://testshib.org/
  198: 
  199: Once preliminary testing is complete you will need to edit /etc/shibboleth/shibboleth2.xml 
  200: based on information provided by your institution, for your SP to work with the appropriate IdP. 
  201: At a minimum the shibboleth2.xml file will need to contain the service hostname of your LON-CAPA server, 
  202: and the SP entityID.  You should also set an e-mail address, for users to contact in case of errors.
  203: 
  204: e.g.,
  205: 
  206: \begin{verbatim}
  207: 
  208: <SPConfig xmlns="urn:mace:shibboleth:2.0:native:sp:config"
  209:     xmlns:conf="urn:mace:shibboleth:2.0:native:sp:config"
  210:     xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  211:     xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"    
  212:     xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
  213:     logger="syslog.logger" clockSkew="180">
  214: 
  215:     <InProcess logger="native.logger"> 
  216:         <ISAPI normalizeRequest="true" safeHeaderNames="true">
  217:             <Site id="1" name="yourserver.someplace.edu"/>
  218:         </ISAPI>
  219:     </InProcess>
  220: 
  221:     <Host name="yourserver.someplace.edu">
  222:         <Path name="secure" authType="shibboleth" requireSession="true"/>
  223:     </Host>
  224: 
  225:     <ApplicationDefaults id="default" policyId="default"
  226:         entityID="https://yourserver.someplace.edu/shibboleth"
  227:         REMOTE_USER="eppn persistent-id targeted-id"
  228:         signing="false" encryption="false">
  229: 
  230:         <Sessions lifetime="28800" timeout="3600" checkAddress="false"
  231:             handlerURL="/Shibboleth.sso" handlerSSL="true"
  232: 
  233:         </Sessions>
  234:  
  235:         <Errors supportContact="helpdesk@someplace.edu"
  236:             logoLocation="/shibboleth-sp/logo.jpg"
  237:             styleSheet="/shibboleth-sp/main.css"/>
  238:     </ApplicationDefaults>
  239: </SPConfig>
  240: 
  241: \end{verbatim}
  242: 
  243: REMOTE\_USER is used to pass on the primary identifier of the authenticated user.  It should be set
  244: to match an attribute or alias defined in the attribute-map.xml file.  LON-CAPA uses this value
  245: (\$r-$>$user in the mod\_perl environment) as the username of the user. The user's domain will be
  246: either the value of the PerlVar lonSSOUserDomain, or if that is undefined, the PerlVar lonDefDomain.
  247: If the attribute used for REMOTE\_USER is in the form: username@somewhere.edu, and somewhere.edu is
  248: the ``internet domain'' (i.e., the last item in the colon separated list of entries for your server
  249: in /home/httpd/lonTabs/hosts.tab), then LON-CAPA will automatically remove the @somewhere.edu, such
  250: that \$r-$>$user will be just username.
  251: 
  252: \item Add a custom Apache config file to include some PerlVars (for logout etc.)
  253: 
  254: Add a file to your Apache conf directory named loncapa\_apache\_local$<$dom$>$.conf, where $<$dom$>$ 
  255: is domain, to include items such as:
  256: 
  257: \begin{verbatim}
  258: PerlSetVar lonSSOUserLogoutHeadFile_<dom>/home/httpd/html/adm/sso_logout_head
  259: PerlSetVar lonSSOUserLogoutMessageFile_<dom> /home/httpd/html/adm/sso_logout_body
  260: PerlSetVar lonSSOUserUnknownRedirect /adm/sso_failed_login.html
  261: PerlSetVar lonSSOUserDomain <dom>
  262: \end{verbatim}
  263: 
  264: and add the corresponding files owned by www:www in /home/httpd/html/adm/
  265: 
  266: Notes:
  267: \begin{enumerate}
  268: \item
  269: All files will contain HTML mark-up, but the sso\_logout\_head item is a fragment 
  270: inserted into the head block of the standard LON-CAPA logout page, and similarly,
  271: the sso\_logout\_body is a fragment inserted into the body of the page, 
  272: whereas the sso\_failed\_login.html file should be a complete HTML document.
  273: 
  274: If the name of the PerlVar ends \_$<$dom$>$ then the HTML fragment is only displayed
  275: to SSO users from that particular domain.  It is possible that a LON-CAPA user from another
  276: domain might have used SSO authentication on a server in his/her home domain, and then switched
  277: session to your server, (e.g., for co-author access to an Authoring Space in your domain).
  278: In that particular case, if you wanted to display custom HTML, you should add a PerlVar with a 
  279: name ending in \_$<$otherdom$>$. If you include PerlVars for lonSSOUserLogoutHeadFile
  280: and/or lonSSOUserLogoutMessageFile they will be included for SSO users who use the Logout link
  281: on your LON-CAPA regardless of the user's domain.
  282: 
  283: \item
  284: SAML 2 Single Logout (SLO) has limited support starting with IdP's running Shibboleth 2.4.
  285: The $<$Logout$>$ element is used to enable and configure support for Logout protocols and behavior 
  286: within the SP, e.g., 
  287: \begin{verbatim}
  288: <Logout>SAML2 Local</Logout>
  289: \end{verbatim}
  290: to support both local, i.e., for the SP itself (Local), and also in a limited way for the IdP (SAML2).  
  291: In pre-2.4 Shibboleth2 /etc/shibboleth2.xml LogoutInitiators enable SP-initiated local logout
  292: e.g.,  https://yourserver/Shibboleth.sso/Logout.
  293: 
  294: Depending on the availability of SLO support from your institution's IdP you should craft an appropriate 
  295: message to include in sso\_logout\_body. If you include a link to the URL for a local logout,
  296: you should indicate that access to other web applications using SSO may continue to be available, even
  297: after logout from the specific SP.  If no local logout is provided, then after logout from LON-CAPA,
  298: the web browser needs to be quit, to ensure access to LON-CAPA requires re-authentication.
  299: 
  300: \item
  301: If you enable self-creation of SSO-authenticated users, then the sso\_failed\_login.html
  302: document need not be created.
  303: 
  304: Attributes provided to the SP by the IdP are available to LON-CAPA as Environment variables.
  305: For Shibboleth SSO users, mapping of Shibboleth environment variable names to user data fields 
  306: can be set so that the appropriate user information is available at account creation time. The
  307: mapping of variable name to LON-CAPA data name will be set by a domain cordinator using the 
  308: domain configuration screen for ``Users self-creating accounts''.
  309: 
  310: Note: user data for a new user need not come from Environment variables populated by Shibboeth;
  311: instead it can come from a customized get\_userinfo() routine in /home/httpd/lib/perl/localenroll.pm
  312: (see Directory Information \ref{Institutional_Integration_Identity_Management} section).
  313: 
  314: \end{enumerate}
  315: 
  316: e.g., sso\_logout\_body
  317: 
  318: \begin{verbatim}
  319: 
  320: <p>
  321: As your original log-in to LON-CAPA was authenticated by a central Shibboleth 
  322: Single Sign On service, your Shibboleth credentials are still valid.<br />
  323: Until you close your web browser, web applications which support Shibboleth 
  324: Single Sign-on (including LON-CAPA) will not require you to re-enter your 
  325: username and password</p> 
  326: <p>
  327: To expire your active Shibboleth authentication token you must quit your web 
  328: browser.
  329: </p>
  330: 
  331: \end{verbatim}
  332: 
  333: e.g., sso\_failed\_login.html
  334: 
  335: \begin{verbatim}
  336: 
  337: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" 
  338: "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  339: <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  340: 
  341: <head>
  342: <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />
  343: <title>No LON-CAPA Account</title>
  344: </head>
  345: <body bgcolor="#ffffff">
  346: <p>
  347: You have authentication using Shibboleth Single Sign On service was 
  348: successful.<br />
  349: However, you do not currently have a LON-CAPA account with the username 
  350: with which you authenticated.<br />
  351: Policies at your institution do not allow you to create a LON-CAPA account 
  352: yourself, after successful authentication. 
  353: Please contact the <a href="/adm/helpdesk">LON-CAPA Helpdesk</a> for your 
  354: domain.
  355: </p>
  356: <p>
  357: Your Shibboleth credentials are still valid.<br />
  358: Until you close your web browser, web applications which support Shibboleth 
  359: Single Sign-on will not require you to re-enter your username and password
  360: </p>
  361: <p>
  362: To expire your active Shibboleth authentication token you must quit your web 
  363: browser.
  364: </p>
  365: </body>
  366: </html>
  367: 
  368: \end{verbatim}
  369: 
  370: \end{enumerate}