Examples - ownCloud case study

ownCloud Server - the self-hosted cloud

This example is available as mdzip file for Magic Draw 18.0, using the UWE Profile v3.0.

General

OwnCloud is a set of software designed to permit end users to run their own file hosting services. It consists of ownCloud Server (OCS), the file hosting server residing on a network-accessible host, and clients for a number of different platforms, both mobile and desktop. The OCS, at its core, can be considered an alternative to the popular file hosting service Dropbox: it allows users to store, download and upload files to and from a server, but its functionality can be expanded by installing additional applications.

The back end is written in PHP and uses a SQL database to store internal data. The core logic of OCS is written by the ownCloud developers, but common functionalities like routing, dependency injection, database abstraction, etc, are handled by existing frameworks like Symfony and Zend. The web-accessible front end is written in HTML and JavaScript and makes use of the jQuery framework and a number of plugins relying on that.

We illustrate the inner workings of OCS by documenting it in UWE notation, as to provide an example of its way of documenting and modeling design decisions regarding security. The statements and graphs made in the following sections are the result of an extensive source code analysis. It is worth mentioning that due to its modular and extensible nature, it is impossible to model every possible instance of OCS. Instead we will model what can be considered its core functionalities, trying to depict what a typical instance could look like.

Note:At the beginning of the source code analysis the most recent version of ownCloud Server was 7.0.4. The following models therefore apply to the 7.0.4 version.

In the following, we are going to present some of the UWE views for a typical OCS instance. There are four sections:

Requirements View Content View Access Control View Navigation and Process View

Requirements View

A user interacting with an OCS can have a number of different roles:

• An unregistered visitor is a user interacting with an OCS that has not yet been authenticated, i.e. has not logged in.
• A registered visitor is a user that has been authenticated, i.e. did log in. Registered visitors can be organized into groups. More on groups can be found here.
• Group administrators are registered visitors that have been put in charge of one or more groups.
• System administrators are registered visitors that belong to the special group called admin and are in charge of maintaining and configuring the OCS instance.

It is possible to have more than one role at the same time, e.g. a system administrator can also be a registered visitor. More on roles can be read here.

Use Case Model for the OCS Core

Figure 1 Use Case Model for the OCS core

Figure 1 shows the Use Case Model for an ownCloud Server instance. It can be seen how all use cases are contained within two top level packages: Applications and Settings. This should represent the fact that all interaction a user can have with OCS are either provided by an application or by a setting module. Since OCS is extensible, meaning that it is possible to install or write additional applications, it makes sense to differentiate between use cases that derive from the core of OCS and those who are provided by the installed applications. Indeed this differentiation will be made for every UWE model presented in the following sections.
Note: More on applications and modules can be found here.

As shown in fig. 1 an unregistered visitor may only log in or request a password reset link, in case the old password is forgotten. It also shows how this role has a dependency (depicted by the dashed arrow) towards the Applications package. While it may appear counter-intuitive that a user who is not logged in may have access to the applications, this dependency is caused by the fact that ownCloud Server leaves it up to the application themselves to define what roles may have access. It is in fact possible to install or write applications that do not need user authentication in order to be used, which could be useful e.g. to provide public content, or to write applications that handle the authentication process themselves. In practice though, most applications do not allow access to an unregistered visitor, the dependency association serves just to model that some use cases might be defined within that package.

A registered visitor has access to the applications as well as to different settings and functionalities tied to his user profile, like changing password, logging out, editing his user details, etc.
Note: Fig. 1 models an OCS instance that has only the applications Files, Calendar, Pictures and Contacts installed. This of course can change from instance to instance and depends on the configuration defined by the system administrator.

  (a) Use Cases for the User Management


  (b) Use Cases for the System Settings Configuration

Figure 2 Further Use Cases

A group administrator can perform some of the actions described in the UserManagement Package, depicted in fig. 2.a, i.e. listing all groups visible to him, listing all users of these groups, deleting users belonging to his groups, changing their credentials or user quota. It cannot however create or delete new groups, as symbolized by the {guard} tag provided by UWE's «webUseCase» stereotype.

System administrators can access further functionalities: they can manage applications by adding, removing or restricting their availability to specific groups; they can create users and assign them to groups, and can create or delete groups, as shown in fig. 2.a. Additionally, they are able to change system settings, e.g. updating the system, setting maximum file storage per user, configuring which types of external storage are allowed to be mounted, etc., as modeled in fig. 2.

When a user has multiple roles, the use cases available to each roles are the sum of all use cases available for each role.

Use Case Model for Selected OCS Applications

Figure 3 Use cases for the Files application

The use cases in the previous section stem from the core of OCS, but as previously mentioned an ownCloud Server instance can be extended through applications. As a sample, we modeled the use cases for the Files application in fig. 3. We mentioned earlier, that the ownCloud Server core grants access to all user, even unregistered visitors. It is therefore an application's responsibility to explicitly check for an user's role. The Files application does not provide any functionality to an unregistered visitor, as can be seen by the fact that this role is missing from the use case model. Only registered visitor have access to its functionalities, like showing owned files, deleting them, uploading new ones, sharing them etc.

Figure 4 Activity diagram for the use case ShareFile defined in fig. 3

When designing an application, a system architect might want to specify use cases with more precision. Since UWE is an extension of UML, we can use activity diagrams to do so. Furthermore, UWE specifies a process model, that extends activity diagrams and introduces some useful stereotypes in order to describe processes occurring in a web application. Fig. 4 shows how the use case ShareFile from 3 works in OCS:

A user that wants to share a file from his OCS instance with another user can do so by performing a series of steps. UWE has a special «userAction» stereotype that represents actions executed by a user of an application. The action Click Share Link is an instance of such stereotype. After clicking on the create new share link, the system checks if a password is mandatory to do so. To specify actions performed by the system, a modeler can user the «systemAction» stereotype. This setting is controlled by system administrators, and would fall under the ConfigureShareOptions use case defined in fig. 2.b. If a password is required, the user must type this in, before the system can create a share link. After the share link is created, the first user can send it to the second user, e.g. over email or instant messaging.
Note: In fig. 4 all actions that are not «userActions» are assumed to be «systemActions». This stereotype is showed only once exemplary for the Create Link action, but is omitted otherwise as to keep the figure as terse as possible.

Once the second user navigates to that link to access the shared file, the OCS instance of the first user prompts for a PW in case the share is protected by one and in case of a correct password shows the content of the share. Receiving users have now multiple available options. They could download the shared files, close the browser, or add the share to their own ownCloud Server instance. To do so, they must enter the URL to their own OCS instance, log in if necessary, type the password of the share again if one is set, at which point their OCS instance connects to the first user's OCS instance to check that the password is correct and then saves the share (i.e. link and password) locally.

Content View

After having introduced some of the main functionalities offered by OCS in the previous sections, we present its abstract content view in this section in order to better describe its architecture. With abstract we mean that we will show the conceptual components of OCS, because the purpose of this section is to give a reader an understanding of the logical architecture of the ownClooud Server web application, and not to describe the actual implementation itself. If we were to actually model the classes defined in the source code, the resulting graphs would highly depend on the used programming language and/or framework, which would contradict whole purpose and goal of showing only relevant system features through proper information hiding.

Content Model for the OCS Core

Figure 5 Content Model for the OCS core

Figure 5 shows the abstract content model of the ownCloud Server core. The entirety of OCS is represented by the UML component OwnCloud. This is the encapsulating element, that contains all the content classes. The UWE profile extends the UML stereotype «component» with a number of security-related tags. As OCS does indeed implement a series of security measures, we can see that the OwnCloud component has a number of tags assigned to it:

• csrfPrevention describes how cross site request forgery (CSRF) attacks should be prevented. In CSRF attacks, a malicious party tries to send an unauthorized HTTP request originating from the victim's browser to a web service for which the victim might currently be authenticated. If the targeted web service does not implement specific countermeasures, the unauthorized request could perform some actions without the knowledge of the victim. It is therefore in the interest of web service providers and their users to build measures to avoid this scenario. OCS uses a number of different techniques to repel CSRF attacks:
  • Synchronizer Token Pattern The synchronizer token pattern is an approach that adds an additional challenge for the execution of critical actions of actions on a web service. The web service generates a random token and embeds it in the website in such manner, that it is sent with each request from the client to the browser. It is the web service's duty to then check whether the received token corresponds to the token generated previously. In order to make it impossible for an attacker to guess the token, this has to be changed frequently. Usually this happens at the beginning of a new session.
  • Checking Referer Header The referer header is a HTTP header that contains the address of the webpage that referred to the requested resource. Hence, a web service might decide to block all requests generated from external addresses in order to avoid unauthorized actions being performed. As there are some issues with this approach, it should not be used as the sole CSRF prevention method.
  • X-Frame-Options X-frame-options are HTTP headers that specify whether or not a client is allowed to render a web page inside an iframe HTML tag. A malicious attacker could load a web service inside a hidden iframe, and then induce the victim to interact with elements inside the iframe without his knowledge. By setting the x-frame-options header to -Sameorigin-, the browser knows not to load a web-page inside an iframe if the address of the requested resource differs from the requesting source. It should be noted, that such an attack is technically a click-jacking attack and not a CSRF. Ignoring this protection method would allow for unauthorized requests to be sent, therefore potentially achieving similar effects.
• sqlInjPrevention SQL Injections are a type of attack, in which a malicious user attempts to execute SQL queries by entering appositely prepared data inside of forms or urls of a web application. In OCS this type of attack is prevented by the use of prepared statements, as indicated by the sqlInjPrevention tag. This is a technique, in which sql statements are prepared beforehand with placeholders for certain values. These placeholders are then filled with user-submitted data in a second step, before being executed. In these manner it is avoided that uncorrectly escaped input modifies the statement and executes unauthorized code.
• xssPrevention Another typical attack on web applications is Cross Site Scripting (XSS). In this type of attacks, a malicious user injects content or client-side scripts into a trusted web page which can have unwanted effects like stealing cookies or session tokens. To mitigate some of these impacts, some countermeasure can be taken: the HTTPOnly flag for cookies can be set, to tell the browser to deny client-side scripts access to the cookie. Furthermore, the x-xss-protection header can be set as well, which re-activates cross-site scripting prevention filter built into modern browsers.
• outputSanitation Correct sanitation of output, especially when output may contain user-provided input, is a technique to mitigate various security issues, like XSS. Some special characters may break the page layout, e.g. by prematurely closing an HTML tag. OCS sanitizes input by automatically encoding (as suggested by the {outputSanitation = Encode output} tag) all output passed to its template engine. This guarantees that special characters are encoded to HTML entities, so that they are interpreted as output and not as part of the markup.

The core of OCS is composed by a few logical elements, as depicted in fig 5. We are now going to explain their functions in detail:

• The class user represents the OCS Users allowed to use the application. There are a number of attributes associated with a user, like user ID (uid), display name, the path to his personal root folder, the date of the last login, and more.
• The UserManager is the object responsible of managing all users and user backends in OCS. While it is not shown in 5, user objects can be retrieved from a number of different backends.The standard installation of OCS uses only the database backend, meaning that user credentials and information are stored on the SQL database.

  

  Figure 6 User Management classes with more detail

  Fig 6 shows a more detailed version of the user management in OCS. It is possible to set up additional backends, for example the HTTP or LDAP backend, in order to retrieve user information from another webservice like for example a corporate directory service. OCS can be configured to use multiple user backends at the same time. The UserManager serves as an abstraction layer, meaning that applications and OCS components can perform user-related operations (adding, modifying and deleting users) without having to worry about actually installed backends simply by querying the UserManager who then delegates the right backend to carry on the requested operation.
• A group is a logical set of users. System administrators can create, modify and delete groups, as well as assign users to them. It is then possible to perform some operations on whole groups instead of on every single user. For example, the Files application allows for an user to share files with whole groups. It is worth mentioning, that the OCS core does not have a very complex group-based permission policy. It merely offers grouping as a convenience for applications that might need the concept of groups. The only exception is the special group admin which is used to determine which users have administrative roles in OCS, i.e. are system administators. A group can have a number of attributes, like a group name, a list of users that are in the group, a list of users that are the administrators of the group (i.e. are group administrators).
• Similarly as for the UserManager, the GroupManager represents an abstraction layer for applications that need access groups and the information associated with them. There are different group backends (similar to fig. 6) available, like LDAP or Database. Similarly to the UserManager class, when a system or group administrator performs a group-related action, e.g. creating or deleting a group, the GroupManager iterates over all registered group backends and tries to perform the requested action. If one of the backends reports that the action has been performed successfully, the GroupManager stops iterating through the backends. Therefore it is important for a system administrator to configure the backends in the preferred order, as a granular control is not possible afterwards.
• Modules are an abstract class that should represent a component that the user can interact with. They can be either an applications or a setting page. While the concept of module does not exist in the OCS source code it makes sense to model one. For one, it makes fig. 5 more terse, as we need to display the relationship between modules and other components only once instead of twice (once for the application class and once for the setting class). For another, applications and settings do indeed posses some technical and logical similarities in the way they are structured. Modules access other components through provided interfaces. This is shown as an example only for the association between a module and the GroupManager in order to keep fig. 5 concise, but in reality every component has an interface and is accessed by other components exclusively through that interface.
• At the heart of OCS are the applications. These are components that add functionalities to an ownCloud Server instance. OCS comes with some core applications already installed (e.g. Files, Calendar, Contacts, etc.) but is designed to be extensible, meaning that additional applications can be installed or written, using the documentation and tutorials available on the ownCloud documentation website. Applications can define their own content classes, as shown by the examples of the Files and Contacts applications in fig. 7 and fig. 8 respectively. In OCS Single applications are not encapsulated, meaning that one application can access the content defined and/or created by a second application or the OCS core itself. It is important to keep this fact in mind, while installing or creating new modules. This design decision has its advantages: for example, a module can extend the functionalities of a second module. This is the case for the File Encryption and File Versioning apps, both of which extend the base Files application, adding as the names suggest encryption and versioning capabilities. At the same time this architecture comports some risks an end user should be aware of: every single application can put the integrity of the whole system at risk. For example, a malicious application could read, modify or delete all the content stored in OCS. Or a single application that has some exploitable vulnerabilities can potentially jeopardize the safety of the whole ownCloud Server instance. It is therefore of the utmost importance, that a system administrator knows exactly what he is installing on his OCS instance. An application is nothing more that a collection of files and folders that follow some specific naming and structural conventions. If these conventions are met, the app is loaded correctly into OCS and can communicate with it through a number of defined interfaces. Through these interfaces, applications can define routes they listen to, content structure to save in the database, the view templates to show to the user, etc.
  Note: The interested reader can learn more about app development and structure on the official ownCloud documentation.
• Settings are those predefined modules in OCS where users can modify the base content and settings of OCS if they have the correct roles. They are structured similarly to applications but with less overhead, as most of their configurations is tightly integrated in OCS and does not need to be specified explicitly. There are four main instances of this conceptual setting class:
  • Personal: This is the setting page, where each user can view and edit their own profile information. Some of the available actions are described in the UserSelfManagement package of fig. 1.
  • Users: System and group administrators have access to this settings module. Here, new groups and users can be created, existing users and groups displayed, modified or deleted. A list of available actions is defined in fig. 2.a. Depending on a user's role, the available actions may vary.
  • Admin: In this setting module, system administrators can set some system wide configurations. Some available use cases are shown in fig. 2.b. Further system-wide settings can be set by modifying a config file located within the OCS directory. This happens outside of the scope of the web interface, and can only be performed by an administrator of the machine running the OCS instance.
  • Applications: System administrators can manage applications in this setting module. They can see installed apps, disable them, install new ones or allow their access only for specific groups. The standard installation of OCS comes with a number of applications installed by default. These can all be disabled, with the exception of the Files app, meaning that the smallest possible instance of OCS will still have at least one application installed.
  Fig 5 shows a directed association between the Application and the Setting class. This is due to the fact, that applications are allowed to inject some content in some setting modules through specific interfaces. For example, the app external storage, an application that allows the integration of external storage providers like Dropbox or Google Drive directly into the OCS Files application, injects a form in the Users settings module, in which the user can enter the credentials to his accounts on these platforms. At the same time it injects a second form in the Admin module, in which system administrators can specify which external services are allowed.
• Lastly, fig. 5 shows a Session class. This is an extension of the PHP session class, and can hold arbitrary data. The core OCS saves, among other things, user information for the logged in user. Therefore applications can get this data from the session, if/when needed, and are free to add, modify or delete data. We included the session in this content model, as it is a pivotal element in the communication between OCS core and applications.

Content Model for Selected OCS Applications

In the previous section we described the content model for the OCS core. As previously stated, each ownCloud application is free to define its own content classes. We are going to show the models for a couple of applications included in the standard installation of OCS.

Figure 7 Content Model for the Files application

Fig. 7 shows the content model for the Files application of OCS. In reality, Files, External Storage, Shared Storage and Encryption are all separate applications that interact with each other. For the sake of convenience we model them all together, as they access each other's content classes.

On the left we see the class User. This is the same class of fig. 5. It means that the Files application accesses the user class provided by the OCS core. The application assigns a fileSystem to each user. A fileSystem can hold a number of mounts, managed by the mountManager. Mounts are providers of storage, that can be of several different types, some of which are shown in fig. 7 as an example. The default installation comes with only the local storage, this is storage on the computer on which OCS is installed. It is however possible to add other types of storage, like FTP or DAV content through the External Storage application, that extends the File application.
There are a number of additional storage providers not included in fig 7 as to avoid cluttering, like e.g. Dropbox, Google Drive or other OCS instances. A user can configure multiple storages providers, and the mountManager will add them to the filesystem as a mount. When the optional module files encryption is installed and configured, the storage of all the configured mounts are automatically encrypted on the storage provider itself, as symbolized by the comment with «storage» stereotype. This means, that by adding an FTP storage and enabling the file encryption app, the files on the FTP server will be encrypted.
Note: The «storage» stereotype is defined by the UWE profile and it allows to describe characteristics of a storage medium through the use of tags. It has nothing to do with the Storage class defined by OCS, they are only coincidentally named the same.

Once the user configured his mounts, they will be available to him through the View class. This is a class that abstracts from all configurations issues, and presents a user all his files from different storage providers as a single, uniform virtual file system. A view has a Root folder, this is a parent folder that contains every other Nodes. A node is either a Folder, which can contain further nodes or a File. Nodes have a FileInfo class associated to them, a class that provides information such as type (file or folder), permissions, mime-type, size, full path, the storage type it is provided by, etc. The configured mounts will appear as a folder, somewhere in his root, according the path given when setting up said mount. Lastly, there are two further classes in the model, SharedFile and SharedFolder. These classes are introduced by the Shared Storage application and represent nodes that a user has shared or that have been shared with him.

Figure 8 Content Model for the Contacts application

Another example of an application defining its own content classes can be seen in fig. 8. The Contacts application provides functionality similar to an address book. A User can create Address Books, and save Contacts in them. The classes used by this application actually depend on how it is accessed, as illustrated by the two sub-components Local and Remote. If accessed locally, this is through the browser, the Contacts application provides a User his configured address books. The application allows for different types of address books, which differ in their backends. The user's default address book uses the OCS's database to store all associated contacts. It is however possible to create further address books that use a LDAP backend. Each backend has a number of contacts associated with it. The contact information stored inside backends is encapsulated in a vCard, a common format for electronic business cards.

However, the Contacts application can also be accessed remotely through the CardDAV protocol, i.e. a popular address book protocol based on WebDAV. In this case, different content classes are used. This is mainly due to the fact, that OCS uses a third-party framework to handle CardDAV requests, namely the Sabre CardDAV. Each of the llasses shown in the Remote component of fig. 8 actually inherits from a corresponding class defined by the Sabre CardDAV framework. Those classes are not depicted in the model, as to keep it uncluttered. The basic structure of the classes defined for remote usage is similar to the one defined for local usage. The only difference is the class RemoteAddressBookRoot, which, as the name suggests, represents a common root which contains all remote address books associated with a User. A remote address book has a remote backend which is simply a wrapper for a local backend. This wrapper is necessary as to comply to the Sabre CardDAV framework. The contacts provided by the backend are then wrapped in a remote card class.

Access Control View

Previous sections introduced the basic functionality as well as the main content classes defined by OCS and some of its applications. In this section we take a closer look at UWE's user role and basic rights models for ownCloud Server, i.e. to describe the access control rules for OCS.

User Role Model

Figure 9 User Roles derived by OCS's internal logic

As mentioned previously, there are four basic roles users can have in OCS, depending on which he is permitted or denied access to certain functionalities. However, these roles are not explicitly defined in the source code, meaning that there is no class or enumeration that models roles, and there is no attribute associated with a user, that stores his roles. Instead a user's role are to be seen as possible states depending of a number of factors.

Fig. 9 shows how roles are determined by ownCloud Server. A user's roles is the set of all the states that are reachable by following the transitions while respecting eventual guards on them. Therefore a user can have multiple roles at the same time, for example a system administrator can be group administrator as well. Only the unregistered visitor has one role at a time, as once that state is reached in fig. 9 there is no outgoing transition. Depending on whether the user is logged in or not, the role registered visitor or unregistered visitor are set. If a user is in the special group admin it gains the additional role of system administrator. Finally, if the user is the administrator of a group as defined in fig. 5, he has the additional role of group administrator.

Since ownCloud Server does not explicitly define roles, whenever an action is executed that is restricted to specific roles, OCS (or the application defining the action) has to check whether the user meets the necessary criteria to perform it. For example, the setting module Users allows to be accessed only by a logged in system or group administrator. This means that when it is accessed, the module checks if the requesting user is logged in, i.e. there are user information in the Session class of fig. 5. If there aren't any information set, the requesting user is not logged in, therefore he is an unregistered visitor and the access to the Users module is denied. If the user is logged in however, the module checks whether he is in the special group admin and it queries the groupManager to see if he is the administrator of at least one group. If any of those two conditions is true, the user must be either a system or a group administrator (or both) and consequentially grants him access.

In summary, OCS and its applications cannot simply request the roles associated to a user, as they aren't explicitly modeled but have to check for each role specifically every time, by performing a number of tests.

Basic Rights Model for the OCS Core

Figure 10 User Roles as classes

UWE's Basic Right Model describes the relationships between content and roles in a class diagram. However, since our role model is defined in a state diagram and it is impossible to insert states in a class diagram, we have to create classes for our roles. Fig. 10 shows such a diagram. Note that is is only for the purpose of using the Basic Right Model diagram defined in UWE, it does not mean that user roles are actually modeled as classes associated with a user, as the figure might imply. Additionally, in this picture the constraint of registered visitor being the only role that does not allow additional roles is not modeled.

Figure 11 Basic Rights Model for OCS Core

In fig. 11 the Basic Right Model for the OCS core is shown. It describes what kind of permissions roles have over content elements already introduced in the Content View. Attributes and methods that were previously not displayed are now shown as to allow a granular description of the rights. UWE models permissions as relationships between content classes and roles classes, adding custom stereotypes to describe the type of permissions.

For example, fig. 11 shows how a system administrator can create a new user, as modeled by the association with the «create» stereotype between these two classes. He can also read all attributes, as implied by the «readAll» association. UWE's Basic Right Model stereotypes define some helpful tags in order to facilitate the modeling of rights. As an example, a system administrator can update all attribute of a user besides the profile picture. Instead of adding two «update» associations (one towards the displayName and the other towards the password attribute) we can add a single «updateAll» association to the class itself, adding an {except} tag and setting it to the attribute that can't be updated by that specific role, in this case the picture attribute.

UWE allows to set constraints on the specified permissions as well. A system administrator can delete any user but himself. This is modeled by the «delete» association between user and system administrator and adding an «authorizationConstraint» on this association that specifies that the action can only be performed if the currentUser (i.e. the user performing the delete action) is not the same as the target of that operation (represented by the value this).
Note: Constraints in «authorizationConstraint» stereotypes can be written in the Object Constraint Language. Some recurring special variables are this, which refers to the target of the constrained action, as well as currentUser the caller of the constrained action.

It is also possible to describe what methods of a class a role has access to. Fig. 11 shows how system administrators are allowed to set the disk quota for the Users, as modeled by the «execute» association that goes from the system administrator role class to the setDiskQuota() method of the user class.

It is important to explicitly state what happens when a role tries to perform some actions that are not specified by the Basic Right Model of UWE. For example, in our model, it is not specified what happens when a system administrator tries to call the editNotificationSettings() method of an user, as there is no «execute» association to that method, and no «executeAll» to the containing class. UWE's default is to support the least privilege principle, according to which a not modeled relationship means a denied permission. As OCS allows the notification settings to be changed by the user itself (and not the system administrator), we do not need to specify a different behavior. However, we want to specify that an «update» association means that «read» is also set as to avoid having to draw additional associations, and do so by explicitly stating so, e.g. in a comment inside our model.

System administrators can also «create» and «delete» groups, as long as the group ID (gid) of said group is not admin. This is a special group in OCS and is vital for its correct functioning, so the system has to make sure that this group cannot be removed. Furthermore, this role is allowed to «executeAll» methods provided by the GroupManager and the UserManager. Finally, this role is allowed to add and remove applications, as well as set the default application and limit which groups have access to what applications. However these privileges are restricted to all, but the Files application, as noted by the condition specified inside the «authorizationConstraint» set on the association between system administrator and application.
Note: More on what a default application is, can be found in the Navigation View section.

Group managers are allowed to «delete» a group, but only when both constraints of the group's gid not being admin and the group having that group administrator in its groupAdmins attribute (which as the type suggests is an array of users) are fulfilled. They are also allowed to «updateAll» attributes {except} for the picture of a user, provided that the group administrator (symbolized by currentUser in the condition) and the user (represented by the this reference) in question have at least one group in common, for which the group administrator is in the groupAdmins field and the user is in the users field of said group. Finally, fig. 11 shows that this role is also allowed to remove users from a group, as long as he actually is an administrator for that group. Due to clarity issues, some of the permissions of a group administrator are not modeled in fig. 11. For example, this role can «execute» the setDiskQuota() method of a user, as well as «readAll» its attributes.

Lastly, registered visitors can «updateAll» of the attributes of a user and «executeAll» of its methods {except} for setDiskQuota(), under the condition that they are the user they are accessing.

Basic Rights Model for Selected OCS Applications

Unregistered visitors have no permissions in the OCS core, as can be deduced by the fact that this role is not shown in fig. 11. However, every application is free to specify its own rules, and decide what roles have access to what content classes, even those declared by the OCS core or other applications. This means, that is possible to write an application that changes the permissions depicted in fig. 11 simply by adding new ones. For example, an application could theoretically allow an unregistered visitor to «create» or «delete» users and/or groups or «updateAll» and «executeAll» of their methods and attributes. Therefore, it is of extreme importance to thoroughly understand what an application does before installing it on an OCS instance, as it might pose security risks.

It should be noted, that an application can only add privileges, or remove them in the context of the application itself. By this we mean that an application can never revoke a system administrator's right to e.g. «create» a new user, as this permission is set by the OCS core. An application might deny this permission in its own context, but the administrator can still access the setting module that allows him to create new users.

To properly model the rights of a OCS instance, it is therefore necessary to model the rights of the installed applications as well. As this is not the main concern of this model example, we will only present the basic rights model for the Files application, as depicted in fig. 12.

Figure 12 Basic Rights Model for the Files application

We only depict some of the classes that users can actually interact with, in order to keep it simple. System administrators can configure the MountManager by configuring the encryption, setting the share options, and the allowed storage types. A registered visitor can «create» mounts, but only when the mount type is amongst those defined in MountManager.allowedStorageTypes or «delete» them, provided he is the owner of the mount.
Note: owner is just a logical attribute, meaning that the mount class does not have a owner field. In reality, whether or not a user owns a mount is determined by checking if the MountPoint of the mount is inside a user's Root folder (see fig. 7). But since the goal of the Basic Right Model is to document the conceptual rights and not the actual implementation, such simplifications are allowed. Similarly, the Node.owner attribute is a shortcut for Node.root.view.filesystem.user.

Additionally, registered visitors have a number of permissions on a node. A user can «create» nodes in the form of files or folders. He is also allowed to «delete» them, modify it or perform actions on it, but only when the condition specified in the «authorizationConstraint» is fulfilled. This is the case if any of the following is true:

• He is the owner of the node
• the currentUser is in the array of users the node has been shared with
• the node in question has been shared publicly

Finally, we have an example of how applications can add rights to roles, as is the case for unregistered visitors, whom the Files application allows to access the data of nodes, if these have been shared publicly.

Navigation View and Process View

Now that we have successfully modeled what use cases OCS supports, the content classes and roles it defines, as well as the rights that roles have on the content, it is time to model how the web application presents itself to its users. UWE offers the Navigation Model exactly for this purpose. With it, it is possible to describe how a user is supposed to navigate the application, what choices he has at each step, what restrictions the application enforces, etc. Process Models are activity diagrams, that can be used to describe with more detail the activities going on behind the scenes where necessary.

Navigation Model for the OCS Core

Figure 13 Navigation States Model of ownCloud

Fig. 13 shows the Navigation States Model for an OCS instance. It is meant to display the navigation options a user has within each state of the web application. This particular instance has only three applications installed, as modeled by the three states Files, Calendar and Contacts.

The entirety of the OCS instance is represented by the outermost state OCS. The UWE «session» stereotypes comes with some tags, that allow to describe some useful features of web applications. For example, the {csrfPrevention} tag can specify some techniques used to prevent Cross Site Request Forgery. More on that can be found in subsection \ref{subsec:corecontent}. It is also possible to specify advanced web security policy mechanisms like HTTP Strict Transport Security (HSTS) with the use of the {transmissionType} tag. This is especially important in web applications that offer authentication, as it reminds the programmers to ensure that a secure, encrypted HTTPS connection is used, in order to protect authentication information. Finally, the tag {noAccessInAppMode} set to Maintenance models the fact that OCS is not accessible when in maintenance mode. This is a mode that OCS switches in under certain circumstances, e.g. when updating. In such cases, users are denied access to ownCloud Server.

The entry point of the application is set by the {isHome} tag. In the case of OCS this is the Files application.
Note: System administrators can change what the default application is, by modifying the config/config.php file, and setting the entry point to be one of the installed applications. In case of misconfiguration or missing permissions, the entry point will fall back to the Files application. More on that in fig. 14.

UWE's Navigation State Model allows to insert submachine states, that contain a state machine by themselves as to allow a modeler to add more details in a second model, without cluttering the first. In our example, the entry point state Files is modeled with more detail in fig. 16.

Navigation to «session» states can be restricted, for example some states could be reached only by certain roles and not by others. In OCS this is the case for the Files application, which can be accessed only by users with the registered visitor role. This restriction is indicated by the {roles = Registered Visitor} tag. In fact, this restriction is valid for all applications that come installed by default with OCS, raising the question of why this tag is not set once globally in the Apps state, instead of setting it individually for every application. The answer to this lies in the fact that as previously mentioned, ownCloud Server allows the single applications to set rights and permissions. Therefore, an application could be written so that it grants access to somebody that does not have the registered user role. In order to reflect this flexibility, we have to model the restriction for every application individually.

It would also be possible to limit the access to a state by setting a guard on a transition that checks for user roles, instead of using the {roles} tag. In our modeling of OCS we opted against this for two reasons:

• The modeling element of a transition translates to the web application element url-path. In OCS menu entries are simply links with the href attribute set to the appropriate location. This means, that it is possible to trigger a transition not only by selecting a menu entry in the web application, but also by entering the corresponding url directly in the browser, thus circumventing any web application logic that might be tied to the selection of a menu entry.
• The core of OCS does not explicitly check who is allowed to access a module before accessing it. Instead, if it receives the request to access a module, it forwards that request to the module in question. It will be that module's concern to check whether the user has the proper rights.

Figure 14 Process Model for the module access logic in OCS

This behavior can be illustrated with more clarity with the use of a Process Model Diagram in fig. 14. This diagram shows the logic of OCS when a user tries to access a module. The activity diagram starts with an «userAction» called access OCS or module. This means the user either clicked on a menu entry to access a module, or entered an url in the browser. The OCS core then parses the request in order to forward it to the proper module. If no module is specified in the request, e.g. when the user enters the base url of the OCS instance, the user is forwarded to the default application.

The activity flow is now in the hands of the selected module, or the default module, depending on the previous step. Most modules check if the requesting user has the necessary rights, by controlling whatever attributes are deemed necessary, like roles and groups. If the requesting user has the proper permissions, he can use the module as he likes, and the activity ends there.

If however the user does not satisfy the module's requirements, the activity flow is handed back to the OCS core, which checks if the user is logged in or not. If the user is logged in, the assumption is that he does not satisfy the requirements set by the module, and is therefore forwarded to the default application.
Note: There is a sort of hierarchy of default applications: the system administrator is free to set any installed application as the default, meaning that it will be the entry point of the OCS instance. If however the default application denies the access to a registered visitor, OCS forwards him to the Files application. This is a special module, as it is the only application that cannot be removed and whose access cannot be restricted to certain groups only. Therefore, as long as a user is logged in, he will be always able to at least load the Files module, no matter his roles and groups.

On the other hand, if the user is not logged in the assumption is that the user could still have the necessary roles once logged in. In this case, the route to the requested module is saved, then the user is asked to perform the login. Once successfully logged in, he is then forwarded to the previously saved module. Note that at this point, the module could reject the user again, for instance if he originally tried to access the Admin module while being logged out and not having the system administrator role.

Part of this logic can also be modeled in the navigation states diagram. The «session» state named InternalArea in fig. 13 has an {unauthorizedAccess} tag set to Unauthorized. This means, that when this state or one of his sub-states is being accessed while not having the proper authorization (in our case, without having the proper roles) it is automatically redirected to the state Unauthorized. Before leaving the state InternalArea, the last state reached is saved to a variable named location. From there, the OCS web application checks if the user is logged in or not. If he is, the location variable is overwritten with the name of the default application, in our case Files. It is important to note, that the location variable has a special function. When this variable is set, upon entering a state, if a substate with the same name as the variable exists, the navigation is redirected to that state.

(a) Simplified

(b) Expanded

Figure 15 The effects of the location variable

Figure 15 explains this concept: on the left, we have the scenario where a state is accessed, while the location variable is set. By convention, this scenario expands to the diagram depicted on the right: a new initial state is inserted, with outgoing transitions guarded by expressions that check for the location variable. When entering Outer', if the variable location is set to B' then the navigation will jump directly to state B', even though the entry point is set to A'.

In our case it means that by simply overwriting the location variable, we access directly the Files state inside the InternalArea state. If the Unauthorized state is reached and the user is not logged it, he is redirected to a login page, represented by the LoginViaPasswordForm state. This state is a UWE pattern: the UWE profile defines a number of standard patterns in order to simplify the modeling process. LoginViaPasswordForm and CredentialRecoveryViaEmail are only two of many patterns. The interested reader is referred directly to the UWE profile available for a full list of pre-modeled patterns.

Upon successfully authenticating, the user is redirected to the InternalArea access, where the location variable (set when exiting this state) navigates to the previously selected navigational node. From the ExternalArea there is an outgoing transition leading to an «externalLink» stereotype. This is a special UWE stereotype that represents a link to an external location, effectively terminating the navigation of the OCS web application.

Navigation Model for Selected OCS Applications

Figure 16 Navigation States Model for the Files module

With UWE it is possible to model the navigation with greater detail by using submachine states. As an example we model the Files application in fig. 16. When the Files application is entered, the user is shown a «collection» of nodes. This is a UWE stereotypes that represents a list of elements. The type of these elements can be specified with the {itemType} tag, by referencing a class from the Content Model. In the case of the Files application of OCS, this equals to nodes.
The user can then perform a number of actions with elements from that collection. Some of these will lead to the same state, for example when downloading a node or opening a folder. Note that the parameter _ (underscore) represents an item from that collection. In our example it stands for n : Node. There are a few transitions that are not explicitly shown in fig. 16 in order to avoid unnecessary cluttering. These are transitions that don't change the navigational state, for example when deleting, moving or creating a node. They perform some actions but leave the navigation unaltered.

Figure 17 Navigation States for the ImageSlideShow submachine state

Some navigation options will lead the user to a different navigational state. For example, when opening a file, depending on the file type, the user is lead to a navigational node that can handle that file type. In the case of a picture file, he is lead to the ImageSlideShow state, depicted in fig. 17. This is a modal state, as implied by the {isModal} tag, meaning that the user can only follow navigational transitions defined within this state. The available actions in this case are to show the next/previous picture, to toggle the automatic picture advancement and to exit the modal slide show. Since UWE models extend existing UML models, we can use exit points. When the exitSlideShow() transition is selected, the navigation returns to the ShowNodes «navigationalNode». The «navigationalNodes» ShowFile and EditDocument can be modeled in a similar way, but as it is outside of the scope of this thesis, we won't go into further detail.

Transitions that start from an enclosing state can be accessed at any time (unless the user is in a state marked by the {isModal} tag). This means that at any point, the user can select the transitions that depart from the Files state, i.e. showDocumentRootFolder(), deletedNodes(), sharedByLink() and externalStorage(). The last three transitions are stereotyped as «search». Usually the «search» stereotype denotes that the transition in question performs a search, a common functionality in web applications. In this case however, the «search» transitions represent a filtering. Since a filtering can be seen as a search with a pre-filled search expression, this seems like a logical fit. The {expression} tag can be used to specify a search expression, in a formal or informal way. In the context of the Files application, these searches represents a filtering of the available nodes by some pre-existing criteria. For example, the externalStorage() transition shows only the nodes deriving from configured external storage, while deletedNodes() shows only nodes previously deleted by the user, similar to a trashbin functionality.

Since the whole Files «navigationalNode» is inside the OCS state of fig. 13, it means that every transition starting from the OCS state, as well as every transition starting from the InternalArea is reachable while in the Files state. As a consequence of this the user can always call the files, calender, pictures, etc transitions. This is equivalent to simply selecting a different module in OCS, be it by changing the url in the browser or selecting a menu entry.

Another navigational option available from within each module is the search transition depicted on the top of the InternalArea «session» state. This is a transition with a «search» stereotype. The user can type some input string, and depending on the search result is then forwarded to a different module. In OCS, applications are allowed to register themselves as so called search providers. Through a series of api calls, they can define content that is indexable by the global search function provided by OCS, as well as declare themselves able to handle that content. In figure 13 we see the applications that declared themselves as being able to handle search results. When performing a search, depending on the type of the selected search result, the navigation is forwarded to one of the applications. In fig. 13 this is represented by the choice element after the «search». If the type of the selected search result is a node, the navigation is forwarded to the Files «nagivationalNode». If the result type is a contact, then the navigation jumps to the Contacts state.

By using entry points and effects on transitions, it is possible to specify some detailed behavior. In fig. 16 we can see, that upon entering the Files «session» state through the entry point searchResult, the search result is selected, as suggested by the name of the activity leading from the entry point to the ShowNodes substate. Appropriate behavior can be modeled for the other applications as well, but won't be shown here.