Using single sign-on¶

docendo can be configured to use external authentication schemes to realize single sign-on. The supported authentication schemes currently are CAS and Shibboleth. When using either of these schemes, users will authenticate by means of the respective protocol, so that docendo will not store or ask for login credentials. On successful authentication, both protocols, CAS and Shibboleth, notify docendo about certain attributes of the respective user (user ID, Name, Email) so that docendo can update or create the user account in its local database.

The authentication schemes can be configured in the "Administration > Settings" menu on the "General" tab.

Caution: When switching authentication schemes, it is very likely that your user ID will change, since it will be provided by a different system. You as an administrator have to ensure that your (single sign-on) user ID will be assigned administrative rights in docendo. There are two ways to do this:

1. Set the "default user role" on the General tab to admin. When logging out and back in to docendo (using single sign-on this time), your new user account will be an administrator account. Now you can switch back to default user role author.
2. If you know your single sign-on user ID beforehand, you can create a new user account within docendo with that ID and assign it the admin role.

Single sign-on with CAS¶

Configure docendo¶

• Activate authentication scheme CAS in menu Administration > Settings > General (Tab). Please heed the "Caution" notice on the top of this page before doing so.
• Enter the CAS URL on the General tab, e.g. https://www.example.com:8443/cas
• File [tomcat-dir]/webapps/[docendo-webapp]/WEB-INF/conf/external-auth-config.xml should have the following contents:
  

  <?xml version="1.0" encoding="UTF-8"?>
  <attributeMapping>
          <user>
                  <attribute name="USERID" value="cas:user" />
                  <attribute name="FIRSTNAME" value="cas:givenName" />
                  <attribute name="FAMILYNAME" value="cas:surname" />
                  <attribute name="EMAIL" value="cas:mail" />
          </user>
  </attributeMapping>
  

Single sign-on with Shibboleth¶

Shibboleth works as an Apache Webserver module, so it is required to have Apache Webserver serve HTTP requests to the Tomcat application server hosting docendo (preferably using the AJP protocol). The following steps are required to get Shibboleth running in conjunction with docendo.

Install Shibboleth¶

Follow deployment guide for Shibboleth SP 2.4 on http://www.switch.ch/aai/support/serviceproviders/.

Configure Shibboleth¶

• In file /etc/shibboleth/shibboleth2.xml: add new attribute attributePrefix="AJP_" to element ApplicationDefaults.
• In file /etc/shibboleth/attribute-map.xml, add the following lines:
  

  <!-- Member Of -->
  <Attribute name="urn:mace:dir:attribute-def:isMemberOf" id="Shib-eduMember-isMemberOf" aliases="isMemberOf"/>
  <Attribute name="urn:oid:1.3.6.1.4.1.5923.1.5.1.1" id="Shib-eduMember-isMemberOf" aliases="isMemberOf Shib-IsMemberOf"/>
  

Apache site configuration for Shibboleth-protected docendo¶

The following sample site configuration assumes, that you deploy docendo in Tomcat as [tomcat-dir]/webapp/ROOT.war, so that docendo is in the root namespace of Tomcat.

<VirtualHost [your-host-name.example.org]:443>
        SSLEngine on
        SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
        SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
        BrowserMatch "MSIE [2-6]" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
        BrowserMatch "MSIE [17-9]" ssl-unclean-shutdown

        <Location ~ "/authenticate(;jsessionid.*)?">
                AuthType shibboleth
                ShibRequireSession On
                ShibRequestSetting encoding URL # IMPORTANT!
                require valid-user
        </Location>

        <Location /Shibboleth.sso>
                AuthType shibboleth
                require shibboleth
        </Location>
        <Location /shibboleth>
                Redirect seeother /shibboleth https://[your-host-name.example.org]/Shibboleth.sso/Metadata
        </Location>

        ProxyRequests Off
        <Proxy *>
                Order deny,allow
                Allow from all
        </Proxy>
        ProxyPass         /  ajp://localhost:[your-tomcat-port]/
        ProxyPassReverse  /  ajp://localhost:[your-tomcat-port]/

        ErrorLog /var/log/apache2/tomcat_error.log
        # Possible values include: debug, info, notice, warn, error, crit, alert, emerg.
        LogLevel info
        CustomLog /var/log/apache2/tomcat.log combined
</VirtualHost>

Configure docendo¶

• Activate authentication scheme SHIBBOLETH in menu Administration > Settings > General (Tab). Please heed the "Caution" notice on the top of this page before doing so.
• File [tomcat-dir]/webapps/[docendo-webapp]/WEB-INF/conf/external-auth-config.xml should have the following contents:
  

  <?xml version="1.0" encoding="UTF-8"?>
  <attributeMapping>
          <user>
                  <attribute name="USERID" value="uniqueID" />
                  <attribute name="FIRSTNAME" value="givenName" />
                  <attribute name="FAMILYNAME" value="surname" />
                  <attribute name="EMAIL" value="mail" />
          </user>
          <groups value="isMemberOf" />
  </attributeMapping>
  

Troubleshooting¶

• When switching authentication to CAS or Shibboleth and something goes wrong (e.g. when CAS or Shibboleth is not configured correctly), it might be impossible to log-in to docendo in order to change the authentication scheme back to "DATABASE", i.e. to transfer authentication handling back to docendo. In that case, the only way out is to delete the settings of docendo in its database. When using Hypersonic SQL as database backend (which is the default), this is how to do it:
1. Shutdown Tomcat
2. Open up the file [tomcat-dir]/docendo-files/database/docendo.log in a text editor and delete the line starting with "INSERT INTO CONFIGURATION VALUES('DEFAULT', ..."
3. Save the file
4. Start Tomcat
   After that, docendo re-creates a default configuration and you can log-in with the default administrator account "admin", password "admin".