ownCloud Repository

General

This repository enables Moodle users to have direct access to their private files from ownCloud in the Moodle file picker and the URL resource module, enabling to upload files into Moodle directly from their ownCloud, without having to download it to their local machine first.

Is your institution using multiple ownCloud servers? Don't worry, a Moodle administrator can connect multiple ownCloud servers that are then presented separately to the users. Tech-savvy users are not able to add their own ownCloud servers, though, so the Moodle admin is always in control which servers are connected.

Are you using Nextcloud? ownCloud and Nextcloud share the same history. As a consequence, they work quite similar. This repository was developed with ownCloud in mind, but it actually works with Nextcloud as well. Remaining limitations have been resolved with Nextcloud 13.0.1 (see Nextcloud Limitations for details).

Installation

This plugin requires configuration in ownCloud (add Moodle as an allowed client) as well as in Moodle (add ownCloud servers to which users will be able to connect). Fair warning: The configuration might become very technical. We collect a list of known problems and hints at their resolution below.

Add Moodle as a client to ownCloud

Prerequisites: Current ownCloud installation (recommended: version 10.0.1+) with enabled HTTPS and the ownCloud OAuth 2 app. Alternatively, a current Nextcloud installation (recommended: version 13.0.1+) on HTTPS.

Log in as an administrator. Go to Settings ► User authentication and add your Moodle installation as a client:

Name	Redirection URI
Your Moodle name	Your Moodle URL + /admin/oauth2callback.php

For example, if your users reach Moodle at https://moodle.example.com, your redirection URI would be https://moodle.example.com/admin/oauth2callback.php. The name can be chosen freely, but note that it will presented to ownCloud users, so the name should be self-explanatory to them.

After adding the client, the table displays a corresponding Client Identifier and a secret. Those will be required for the configuration in Moodle, so keep them at hand. For example, if your users reach Moodle at https://moodle.example.com, your redirection URI would be https://moodle.example.com/admin/oauth2callback.php. The name can be chosen freely, but note that it will presented to ownCloud users, so the name should be self-explanatory to them. After adding the client, the table displays a corresponding Client Identifier and a secret. Those will be required for the configuration in Moodle, so keep them at hand.

Install this plugin to Moodle

Copy the content of this repository to repository/owncloud. No additional settings are displayed to the admin when installing the plugin. However, when the repository is enabled, the admin has to select an issuer which defines the ownCloud server. The next steps describe how the necessary issuer is created in Moodle's central OAuth 2 services settings. Afterwards, an ownCloud repository instance is created using that issuer.

Create OAuth 2 Issuer

You need to configure Moodle so that it knows how to talk to your ownCloud server. For this, a so-called OAuth 2 issuer has to be registered in the admin menu Site administration ► Server ► OAuth 2 services. There, select Create custom service. Choose the name freely; it will only be shown to you. Enter ClientID and Secret from the ownCloud settings of Add Moodle as a client to ownCloud. Enable the "Authenticate token requests via HTTP headers" checkbox. As Service base URL, enter the full URL to your ownCloud installation, including a custom port (if any). For example, if the ownCloud installation is at https://owncloud.example.com:8000/oc/, then this is the base URL. Ignore the other settings and click Save changes. Afterwards, your issuer is listed in a table. There, click Configure endpoints to configure the services that we want to use, as ownCloud does not support auto discovery. For the ownCloud Repository plugin four endpoints have to be registered that are ownCloud-specific:

Endpoint name	Endpoint URL
token_endpoint	Base URL + /index.php/apps/oauth2/api/v1/token
authorization_endpoint	Base URL + /index.php/apps/oauth2/authorize
webdav_endpoint	Base URL + /remote.php/webdav/
ocs_endpoint	Base URL + /ocs/v1.php/apps/files_sharing/api/v1/shares
userinfo_endpoint	Base URL + /ocs/v2.php/cloud/user?format=json

Note: Previously, an additional parameter in the ocs_endpoint URL was listed (?format=xml). This is no longer necessary, however, having the parameter set would not result in any problems either.

Given the Base URL example above, an exemplary token_endpoint URL is https://owncloud.example.com:8000/oc/index.php/apps/oauth2/api/v1/token . Return to the issuer overview and click on Configure user field mappings. Enter the following mappings:

External field name	Internal field name
ocs-data-email	email
ocs-data-id	username

This is sufficient to use basic functionality of the ownCloud repository!

Optional: If you want to use access controlled links, you also need to connect a system account. This must be an ownCloud account that does not belong to a particular person. Instead, it should be owned by Moodle. First, create such an account in ownCloud or ask your ownCloud administrator to do so. Choose a strong, ideally random password and do not give it to someone else who is not an administrator of your Moodle. Afterwards, in the issuer overview, click on Connect to a system account. Make sure that you are logged in to ownCloud with that account and Authorize Moodle. You should then be back in the issuer overview, where you can verify that you connected the right account by checking its username. (In your browser, log out of ownCloud now to avoid using the system account by accident.) Also, do not change the system account after the plugin has been used. This will break all access controlled links that were created prior to a change.

For further information on configuring OAuth 2 clients visit the Moodle documentation on OAuth 2 and the Developer documentation on OAuth 2.

Create a repository instance

Now that the ownCloud issuer is configured, it can be associated with an instance of the repository. Go to the repository settings Site administration ► Plugins ► Repositories ► Manage repositories and enable the ownCloud respository (Enabled and visible). When asked for special user permissions, do not check any boxes. As they may not configure OAuth 2 issuers, these permissions are not that useful. Then, open the Settings of the ownCloud repository and click Create a repository instance. Enter a name that will be displayed to Moodle users and select the configured issuer. A text underneath the select box tells you which issuers are suited for use with this repository. If your issuer does not show up, double-check the issuer settings; particularly all URLs (base URL and endpoints) and the names of the endpoints.

Issuer instance configuration

You can also define the Name of folder that will show up in users' private file storage once they open access controlled links: A share in ownCloud will always result in a file showing up at the user, so this is where that file will go in order to avoid cluttering their document root. The dropdowns allow you to define how the repository may interact with files: Supported files allows you to restrict usage of the repository, i.e., to allow linking ("external") only or upload ("internal") only, but you can also allow unrestricted usage. If Internal and external is selected, you can define the default type presented to users.

Afterwards, everything is configured and ready to go! Let's see what this looks like for your users:

Usage

The repository is available in all activities where the file picker is used. However, course admins can disable it in the Course Administration ► Repositories menu. In the file picker a login button is displayed (assuming that the user is not authenticated yet):

File Picker Login

When the button is clicked a pop-up window or a new tab is opened and the user will be requested to login at the ownCloud instance and authorise access from Moodle. If authorisation is granted, the user sees a tabular listing of the files available:

File Picker Listing

Here the user can select files, reload the content and logout. The settings button opens the ownCloud web interface in a new window so that you can manage your files easily

Access controlled links

Students may submit files from ownCloud/Nextcloud as 'access controlled links' in assignments. Once submitted, the student may no longer change them, but the teacher is allowed to edit them.

Teachers may display files from ownCloud/Nextcloud as 'access controlled links'. The teacher can then continue updating the files, but students can only view them.

To enable this feature, ensure that:

1. A system account has been connected in OAuth 2 services in Site administration. This account will own and control access to files submitted by students and teachers. Teachers will be able to edit the files but students will not. This should be a dedicated account for this purpose.
2. "Supported files" is set to "Internal and External".
3. Optional: "Default return type" is set to "External (only links stored in Moodle)".

Nextcloud Limitations

In 2018, Nextcloud created and published a set of fixes that resolve all known limitations. Before that, Nextcloud (up to and including version 12) had a limitation that prevented the use of file links. That means, files could only be uploaded from Nextcloud into Moodle, but you could not use the alternative, i.e. creating a file link, because the Nextcloud server would block you from doing so. Should you run into this issue, make sure that you are working with the latest version of Nextcloud (definitely not older than 13.0.1!). If that does not help, please check the #Troubleshooting section below.

With the introduction of Access Controlled Links (similar to the functionality of the Google Drive repository and OneDrive repository plugins) in v3.5-r2 of this plugin, Nextcloud poses a new limitation. Whenever you authorise Moodle to access your Nextcloud, you log out at the browser at the same time. To access an access controlled link file you first have to authorise Moodle, then re-login in to Nextcloud in the browser. Then you can access the file from Moodle.

Troubleshooting

Installing and configuring this plugin is a rather technical endeavour, given that making two machines speak to each other is a very technical topic. If something goes wrong, it may be hard to find out the root cause. Nevertheless, so far we have been able to resolve all issues and, once the plugin is installed and configured correctly, it runs smoothly and very stable. The following is a list of issues that were encountered during configuration, and hints at how to proceed.

I cannot connect a system account.

Make sure the system account is different from all personal accounts. It has to be an account that belongs to Moodle, not to a person. Look at the issuer settings. The checkbox Authenticate token requests via HTTP headers must be enabled!

Authentication seems to have succeeded, but the filepicker shows "There are no files".

The Apache server that hosts your ownCloud may be misconfigured. Its Apache logs may show a 401 error as well if you try to see the files in Moodle. Please have a look at the comments following https://github.com/learnweb/moodle-repository_owncloud/issues/26#issuecomment-343521986 to get ideas on how to solve this. Alternatively, it is possible that HTTPS is not configured correctly on the Nextcloud end. You need a valid and trusted certificate for your Nextcloud server. It is not possible to manually define exceptions, unlike in the browser.

I can only upload files, not link to files.

Are you using Nextcloud? In that case, upgrade Nextcloud to version 13.0.1 or later. Prior to that, Nextcloud suffered from technical limitations that prevented file linking.

If I link to files in Nextcloud I get "A request to ownCloud has failed: Invalid response".

Please double-check the URL that you entered for ocs_endpoint. Until repository_owncloud v3.5-r1 it was essential that ?format=xml was specified at the end of the URL.

After signing in with ownCloud I get an error that says "This request is not valid. Please contact the administrator of [your Moodle Name] if this error persists.".

You might have entered the wrong Redirect URI in ownCloud. It is important that it has /admin/oauth2callback.php at the end, and that it corresponds exactly with what Moodle is going to send to ownCloud when attempting to authenticate!

When I access an access controlled link I authorise Moodle but then cannot see the file.

In Nextcloud before 14.0.1, when you authorise Moodle, your Nextcloud browser session ends. This is a special limitation of Nextcloud. You have to re-login in the browser to access the file. Starting with Nextcloud 14.0.1, this issue is resolved.

Since I installed the plugin and connected a system account, Moodle is very slow

Nextcloud has a brute-force protection that is somewhat naïve. When enabled, it slows down some Moodle requests in some cases (even though the Moodle plugin is definitely not going to brute-force your Nextcloud!), but you can change this. First, update to the newest version of the repository plugin, as it reduces the number of requests to Nextcloud. Second, download the "Brute-force settings" app in Nextcloud. After installation, add the IP of your Moodle server to the whitelist.

Please add to this list if you were able to solve another issue, this will help others greatly! Thanks!

Acknowledgement

This plugin was originally created by Information Systems students in the project seminar sciebo@Learnweb at the University of Münster in 2016/17. See their github page for an archive(!) of their great work. They also created the OAuth 2 interface for ownCloud (featured on heise Security (German)); otherwise all this wouldn't have been possible. Learnweb (University of Münster) is maintaining the Moodle plugins since 2017.