Difference between revisions of "CDO/Security Manager"

Latest revision as of 11:03, 14 November 2013

Getting CDO

As of September 2013, the security management feature is available in CDO 4.2 and in the master branch that will become CDO 4.3 with the release of Eclipse Luna. This tutorial applies to the master branch, that can be cloned with EGit from http://git.eclipse.org/gitroot/cdo/cdo.git (see CDO Source Installation).

An alternative is to download Eclipse 4.4 milestones from http://download.eclipse.org/eclipse/downloads and then to install CDO Model Repository SDK, Net4j Signalling Platform SDK and Net4j DB Framework H2 adapter from http://download.eclipse.org/modeling/emf/cdo/updates/integration. When the installation is finished import the org.eclipse.emf.cdo.server.product plugin into your workspace (open the Plug-ins view, select the plugin, right-click, select "Import As", select "Source Project").

Starting the Repository

Now the org.eclipse.emf.cdo.server.product plugin exists as a project in your workspace (either because you've checked it out from Git or you've imported it from your target platform):

To enable the security manager open the cdo-server.xml file and uncomment the <securityManager> element. Here's a stripped down version:

<?xml version="1.0" encoding="UTF-8"?>
<cdoServer>

  <acceptor type="tcp" listenAddr="0.0.0.0" port="2036"/>

  <repository name="repo1">
    <property name="overrideUUID" value=""/>
    <property name="supportingAudits" value="false"/>
    <property name="supportingBranches" value="false"/>

    <securityManager type="default" description="/security:annotation:home(/home)"/>

    <store type="db">
      <mappingStrategy type="horizontal">
        <property name="qualifiedNames" value="true"/>
      </mappingStrategy>

      <dbAdapter name="h2"/>
      <dataSource class="org.h2.jdbcx.JdbcDataSource" URL="jdbc:h2:database/repo1"/>
    </store>
  </repository>

</cdoServer>

The description attribute of the <securityManager> element has the following syntax (without extra whitespace):

  description := realmPath [ commitHandler* ]
  realmPath := a string literal that specifies the resource path in the repository where the security realm is placed.
  commitHandler := ":" commitHandlerType [ "(" commitHandlerDescription ")" ]
  commitHandlerType := a string literal that specifies the type of the IFactory that contributes the commit handler.
  commitHandlerDescription := a string literal that specifies the commit handler-specific configuration description.

For our example that means:

• A default implementation of the security manager will be used and the security realm will be stored in the resource /security.
• The "annotation" commit handler will consider EAnnotations on all committed EPackages and EClasses. These annotations have the source URI "http://www.eclipse.org/CDO/Security", the keys "read" and/or "write" and list the role names to be granted the specified access. Compare AnnotationHandler.java.
• The "home" commit handler automatically detects new users and creates user-specific home folders under the specified "/home" folder. Only the respective user will have WRITE access to this folder. Noone else will have READ access to it. Compare HomeFolderHandler.java.

Then run the CDOServer.launch that ships in the project. The console should display:

osgi> Time to load bundles: 3
Starting application: 1194

[INFO] CDO server starting
[INFO] CDO server starting
[INFO] Net4j extension starting
[INFO] Net4j extension started
[INFO] Security extension starting
[INFO] Security realm /security created
[INFO] Security extension started
[INFO] CDO server started

Application Started: 2783

The H2 database should have been created in a new "database" folder within the project.

For stopping the repository, use the following commands in the OSGi remote or local console:

osgi> close

[INFO] CDO server stopping
[INFO] Net4j extension stopping
[INFO] Net4j extension stopped
[INFO] Security extension stopping
[INFO] Security extension stopped
[INFO] CDO server stopped

Enabling the Security Manager on an Existing Repository

Initializing the security manager on an existing repository is not more complicated. You only have to stop the CDO server, modify its configuration by adding the <securityManager [...]> directive, and restart it. The default security realm will be added with the Administrator account. Beware that after this restart, nobody, even the Administrator, has the right to add models or modify anything else than the security realm: it will be needed to add access rights to the Administrator, or to add new roles and users.

Logging into the Repository

Start as usual a session in the CDO Sessions view by clicking on the green '+' button in the view toolbar. The Open Session dialog pops up:

Once you have clicked on OK, a special login dialog appears:

The CDO server has automatically added an administration account when the security realm has been created. The user name is Administrator and the password is 0000. If you succeed to log in the CDO Session view looks as follows:

You can then open a transaction (right-click on the new session) and edit the security realm (double-click on the security resource):

By default, the Administrator can read and modify the security realm, as well as his own home folder, but nothing else (including other users' home folders). However, the Administrator can give herself permission to write anything at all.

New in Luna M3 and later integration builds: a new, simplified form-based editor streamlines the common security configuration use cases of creating users and assigning groups and roles. To open this editor in a session logged in as the Administrator, simply invoke the context menu action:

This opens an editor that presents users, groups, and roles in a convenient layout with the most commonly used properties editable right in the editor. Intuitive drag-and-drop gestures associate users, groups, and roles as you would expect:

An action button (circled above) lets the Administrator reset a user's password in case it has been forgotten. On successful reset, the editor shows the new randomly-generated password to the Administrator with a button to copy it to the clipboard to easily share it with the user, who then should change it at the next opportunity. This reset function is also available in the context menu for User items in the tree editor.

One of the simplifications implemented in this editor is in the definition of roles. The editor makes it easy to define access rules with resource filters, including browsing the repository to choose paths, but only resource filters are supported.

In the case that more complex filtering is required, the toolbar button in the top corner of the editor (circled above) opens the tree editor in the same transaction and with the same undo/redo history, offering the full editing capability. Where the security realm has content not supported by the form editor, this is indicated with yellow warning annotations and a banner message in the header.

Changing Your Password

As of Luna M3 and later integration builds, users can change their passwords at any time, in repositories that have the security manager installed. Simply invoke the context menu action in your session:

This opens an unsurprising dialog that requires authentication using the current password (which is blank by default for new users) and the new password, with a repeat for confirmation:

This should also be used to change the password generated automatically by CDO in case the Administrator had to reset your password. However, currently CDO does not provide for:

• automatic expiry of passwords
• temporary (already expired) passwords on password reset

These would, naturally, constitute welcome contributions.

Understanding the Security Model

Since mid 2012, CDO includes a default security model that allows to specify the access rights to the objects of repositories (see bug 380629).

An alternative model exists: the annotation model. It is incompletely covered by this tutorial.

This tutorial is the result of a short period of evaluation of this feature. It doesn't pretend to cover the topic exhaustively. Please feel free to complete it, to update it and to fix it when required.

The default CDO security model is implemented on the server side as an Ecore model, as shown below.

The root element of the security model is the realm, which contains the following elements:

• Directories, gathering any number of these 4 elements. They are not used during permission checking, but may be helpful to organize the Realm items.
• Users, describing the people accessing the repository. Users may have several roles and may belong to several groups.
• Groups, gathering people sharing the same needs in term of access. Groups may have several roles. Groups may inherit Roles from other Groups.
• Roles, describing operational functions and their access rights. Roles contain a list of Permissions.

Permissions grant NONE, READ or WRITE (includes READ) access to sets of objects. Permissions form a bridge between the declarative part of the security model and the programmatic approach to determining sets of objects (implemented via the isApplicable() predicate method). The security model ships with the following Permission implementations:

• FilterPermission: specify the access right for a set of objects declaratively with a tree of PermissionFilters (see below). If you specifiy multiple PermissionFilters they must all match (AND).
• ResourcePermission: deprecated (see ResourceFilter), specify the access right for any resource or resource folder (including all contained objects) with a path matching the given pattern.
• PackagePermission: deprecated (see PackageFilter), specify the access right for all the EClasses included in applicablePackage.
• ClassPermission: deprecated (see ClassFilter), specify the access right for the EClass applicableClass.
• ObjectPermission: deprecated (see ObjectFilter), specify the access right for any object based on your own implementation of the isApplicable() method. You need to generate your own EPackage.

PermissionFilters are used to declaratively specify sets of objects. The following PermissionFilters ship:

• ResourceFilter: resources or resource folders with a path matching the given path and pattern style. The special token ${user} in the path attribute is substituted with the autheticated user ID at runtime.
• PackageFilter: objects of any of the EClasses included in applicablePackage.
• ClassFilter: objects of the EClass applicableClass. Whether subtypes are included can be specified.
• (Abstract) ObjectFilter: objects for that your own implementation of the isApplicable() method returns true. You need to generate your own EPackage.
• ExpressionFilter: objects for that the specified expression evaluates to true. Expressions come from the expressions model (or your custom extension to that).
• LinkedFilter: objects that matched by a filter thats specified elsewhere.
• NotFilter: objects that are not matched by the first contained filter.
• AndFilter: objects that are matched by all contained filters.
• OrFilter: objects that are matched by any contained filter.

Notes

• The Apache Derby adapter seems to be broken in CDO 4.x. Prefer using H2, which is now the default embedded database of CDO.
• Some CDO features, like workspace and CDO projects management, are not yet compatible with the security manager.
• Be aware that you can do severe damage in the security realm by excluding users from content that they need to be able to edit or giving them access to content they should not have. However, certain basic integrity constraints are checked by the server on every commit of changes to the security realm, including that at least some user (hopefully the Administrator) is able to edit the security realm, itself. See bug 399487 for details.
• Default access rights of User shall be understood as Minimum rights. A user with READ default access right has at least READ access to all objects of the repository. See bug 399486.
• WRITE access are checked at commit time on the server side. It means that if you are using the CDO UI, you can create and modify objects in the editor. Your commit will be entirely rejected when saving. See bug 399485.
• Modifications in the security realm done with the CDO editor are not taken into account at commit time by the server. See bug 399480.
• All related Bugs