Shibboleth Integration (Enterprise only)

Introduction

The ownCloud Shibboleth user backend application integrates ownCloud with a Shibboleth Service Provider (SP) and allows operations in federated and single-sign-on infrastructures. Setting up Shibboleth has three steps:

  1. Create the appropriate Apache configuration
  2. Enable the Shibboleth app
  3. Enable Shibboleth on your ownCloud admin page

Currently supported installations are based on the native Apache integration . The individual configuration of the service provider is highly dependent on the operating system, as well as on the integration with the Identity Providers (IdP), and require case-by-case analysis and installation.

The ownCloud Desktop Client and mobile clients can interact with an ownCloud instance running inside a Shibboleth Service Provider by using built-in browser components for authentication against the IdP.

The ownCloud desktop sync client and mobile apps store users’ logins, so your users only need to enter their logins the first time they set up their accounts.

Note

The ownCloud clients may use only a single Shibboleth login per ownCloud server; multi-account is not supported with Shibboleth.

These screenshots show what the user sees at account setup. Figure 1 shows a test Shibboleth login screen from Testshib.org on the ownCloud desktop sync client.

../_images/shib-gui1.png

figure 1: First login screen

Then after going through the setup wizard, the desktop sync client displays the server and login information just like it does for any other ownCloud server connections.

../_images/shib-gui4.png

figure 2: ownCloud client displays server information

To your users, it doesn’t look or behave differently on the desktop sync client, Android app, or iOS app from an ordinary ownCloud account setup. The only difference is the initial setup screen where they enter their account login.

Apache Configuration

This is an example configuration as installed and operated on a Linux server running the Apache Web server. These configurations are highly operating system specific and require a high degree of customization.

See the documentation Wiki for more configuration examples.

The ownCloud instance itself is installed in /var/www/owncloud/. The following aliases are defined in an Apache virtual host directive:

# non-Shibboleth access
Alias /owncloud /var/www/owncloud/
# for Shibboleth access
Alias /oc-shib /var/www/owncloud/

Further Shibboleth specific configuration as defined in /etc/apache2/conf.d/shib.conf:

#
# Load the Shibboleth module.
#
LoadModule mod_shib /usr/lib64/shibboleth/mod_shib_22.so

#
# Ensures handler will be accessible.
#
<Location /Shibboleth.sso>
  Satisfy Any
  Allow from all
</Location>

#
# Configure the module for content.
#
# Shibboleth is disabled for the following location to allow non
  shibboleth webdav access
<Location ~ "/oc-shib/remote.php/nonshib-webdav">
  Satisfy Any
  Allow from all
  AuthType None
  Require all granted
</Location>

# Shibboleth is disabled for the following location to allow public link
  sharing
<Location ~
  "/oc-shib/(status.php$
  |public.php$
  |cron.php$
  |core/img/
  |index.php/apps/files_sharing/publicpreview.png$
  |index.php/apps/files/ajax/upload.php$
  |index.php/core/ajax/translations.php$
  |apps/files/templates/fileexists.html$
  |index.php/apps/files/ajax/mimeicon.php$)">
  Satisfy Any
  Allow from all
  AuthType None
  Require all granted
</Location>

# Shibboleth is disabled for the following location to allow public gallery
  sharing
<Location ~
 "/oc-shib/(apps/gallery/templates/slideshow.html$
 |index.php/apps/gallery/ajax/getimages.php
 |index.php/apps/gallery/ajax/thumbnail.php
 |index.php/apps/gallery/ajax/image.php)">
  Satisfy Any
  Allow from all
  AuthType None
  Require all granted
</Location>

# Shibboleth is disabled for the following location to allow public link
  sharing
<Location ~ "/oc-shib/.*\.css">
  Satisfy Any
  Allow from all
  AuthType None
  Require all granted
</Location>

# Shibboleth is disabled for the following location to allow public link
  sharing
<Location ~ "/oc-shib/.*\.js">
  Satisfy Any
  Allow from all
  AuthType None
  Require all granted
</Location>

# Besides the exceptions above this location is now under control of
  Shibboleth
<Location /oc-shib>
  AuthType shibboleth
  ShibRequireSession On
  ShibUseHeaders Off
  ShibExportAssertion On
  require valid-user
</Location>

Application Configuration

After installing and enabling the Shibboleth application there are three configuration variables to set up, depending on the data sent back by the IdP. The configuration is stored in apps/user_shibboleth.

namespace OCA\user_shibboleth {
        const SHIB_SESSION_ID = 'Shib-Session-ID';
        const SHIB_EPPN = 'eppn';
        const SHIB_EMAIL = 'eppn';
        const SHIB_DISPLAY_NAME = 'eppn';
}
Parameter Description
SHIB_SESSION_ID This constant defines the name of the environment variable holding the Shibboleth session id.
SHIB_EPPN This constant defines the name of the environment variable which holds the EPPN (eduPersonPrincipalName). This is the unique user identifier.
SHIB_EMAIL The environment variable with this given name holds the email address of the logged-in user.
SHIB_DISPLAY_NAME This constant defines the name of the environment variable holding the user’s display name.

Enabling the Shibboleth App

You must enable the Shibboleth app on your Apps page, and then check Activate Shibboleth and click the Save button on your ownCloud Admin page. The system information displayed on your Admin page may be useful for troubleshooting; for example you can copy and include it on a support ticket.

../_images/shib-gui5.png

figure 3: Enabling Shibboleth on the Admin page

WebDAV Support

Users of standard WebDAV clients can use an alternative WebDAV Url, for example https://cloud.example.com/remote.php/nonshib-webdav/ to log in with their username and password. The password is generated on the Personal settings page.

../_images/shibboleth-personal.png

Note

In pure SSO mode the WebDAV password feature will not work, as we have no way to store the WebDAV password. It does work in auto-provision mode.

For provisioning purpose an OCS API has been added to revoke a generated password for a user:

Syntax: /v1/cloud/users/{userid}/non_shib_password

  • HTTP method: DELETE

Status codes:

  • 100 - successful
  • 998 - user unknown

Known Limitations

Encryption

File encryption can not be used together with Shibboleth because the encryption requires the user’s password to unlock the private encryption key. Due to the nature of Shibboleth the user’s password is not known to the service provider. Currently, we have no solution to this limitation.

Other Login Mechanisms

Shibboleth is not compatible with any other ownCloud user backend because the login process is handled outside of ownCloud.

You can allow other login mechanisms (e.g. LDAP or ownCloud native) by creating a second Apache virtual host configuration. This second location is not protected by Shibboleth, and you can use your other ownCloud login mechanisms.

Session Timeout

Session timeout on Shibboleth is controlled by the IdP. It is not possible to have a session length longer than the length controlled by the IdP. In extreme cases this could result in re-login on mobile clients and desktop clients every hour.

The session timeout can be overridden in the service provider, but this requires a source code change of the Apache Shibboleth module. A patch can be provided by the ownCloud support team.

All documentation licensed under the Creative Commons Attribution 3.0 Unported license.