help logoLON-CAPA Help

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:

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.

  1. 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 

    [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

    e.g., CentOS 7 

    [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

    Then do: 

    yum install shibboleth

    SLES:

    e.g. SLES 11 SP3: 

    zypper addrepo http://download.opensuse.org/repositories/security:shibboleth/
SLE_11_SP3/security:shibboleth.repo
zypper refresh
zypper install shibboleth

    e.g. SLES 12 SP5 

    SUSEConnect -p SLES/12.5/x86_64 -r <registration-code>
zypper install shibboleth-sp-2.5.5-6.6.1

    e.g., SLES 15 SP4 

    SUSEConnect -p sle-module-server-applications/15.4/x86_64
zypper install shibboleth-sp-3.1.0-3.3.1

    e.g., Ubuntu 20.04LTS 

    sudo apt install --install-recommends shibboleth

    The following directories will have now been created:

    /etc/shibboleth

    /var/log/shibboleth

    /var/run/shibboleth

    /var/cache/shibboleth

  2. Apache configuration

    Red Hat/CentOS - httpd.conf should be modified to contain:

    UseCanonicalName On

    Include conf/shib.conf

    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:

    APACHE_USE_CANONICAL_NAME="on"

    Modify /etc/apache2/default-server.conf to contain:

    Include conf/shib.conf

    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.

  3. Set shibd to start on boot
    /sbin/chkconfig shibd on

  4. Install mod_ssl and Apache/SSL certificates
    1. Red Hat/CentOS
      yum install mod_ssl

    2. SuSE/SLES

      Use yast - > Network Services - > HTTP Server - > Server Modules to set ssl to enabled, and rewrite to enabled

    3. Ubuntu

      sudo a2enmod ssl

      sudo a2enmod rewrite

      sudo a2ensite default-ssl.conf

      Edit default-ssl.conf replace "DocumentRoot /var/www/html" with "DocumentRoot /home/httpd/html"

    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" Help section for more information).

  5. 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., 

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

    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:

    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.

  6. 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: 

    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>

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

    Notes:

    1. 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.

    2. 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., 
      <Logout>SAML2 Local</Logout>
      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.

    3. 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 Help section).

    e.g., sso_logout_body 

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

    e.g., sso_failed_login.html 

    
<!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>