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 from http://shibboleth.net for: Red Hat/CentOS 5, 6 and 7, SLES 10 and 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.

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

    
    [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
    
    

    e.g., CentOS 6

    
    [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
    
    

    Then do:

    yum install shibboleth
    
    

    SLES/openSuSE:

    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. SuSE 12.3

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

    e.g., Ubuntu 12.04LTS

    See: https://www.switch.ch/aai/docs/shibboleth/SWITCH/2.5/sp/deployment/?os=ubuntu

    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
    
    

    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.

  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>