View source for Protege Client Server Tutorial Configuration

<div class="orangeBox">
<span class="orangeBoxTitle">Protege Server Configuration</span><br /><br />
'''This page describes the configuration of the Protege server including: the metaproject, creating users and policies. This page is part of the [[Protege_Client-Server_Tutorial|Protege client-server tutorial]].'''

</div><br /><br />

__TOC__


This section describes how to configure the projects that are available from the Protege server. (Read this section only if you have succeeded in performing the steps from the section [[Protege_Client_Server_Tutorial_Setup|Protege Server Setup]].


= The Metaproject =

'''The metaproject''', located by default in the <code>examples/server</code> subdirectory of the Protege installation directory, contains information about which Protege projects are exported, i.e. available to Protege clients, and which users have access to these projects. It also stores policy configurations. Note that the built-in security concerning which users can access which projects is on top of whatever other security your system provides, e.g. a firewall.

Use Protege to open the metaproject and spend some time browsing the class hierarchy. You will find a very simple ontology of users, security, and projects:


= How do policies work =

The Protege server supports the following policies: '''project policies''', '''group policies''', and '''server policies'''. The '''project policies''' refer to the permissions set for a particular project. For example, for the Collaborative Pizza project, a policy may say that only people from the group ''Pizza Makers'' are allowed to open this project (other users will not even see it in the project list after login). The '''group policies''' apply to groups. For example, one policy may state that only a certain group of people are able to add users in this group. The '''server policies''' apply to the server itself and has associated to it more "administrative" types of permission. For example, one policy might say that only users from the ''Admin group'' are allowed to shut down the server.

The policy model represented by the metaproject ontology is very simple and flexible. The idea is that you can attach to a policy controlled object (a project or a server) a set of allowed operations for a certain group. The examples from the previous paragraph are quite clear. You may define your own operations, groups, users, etc. There are some predefined operations that the Protege server enforces in the UI (e.g., the read permission), and we'll talk about them in the Policies section.


'''IMPORTANT NOTE.''' '''If an operation is not defined in the metaproject, then it is permitted by default'''. This means, that if a Protege-based software (e.g., a plugin) asks from the policy manager API whether a certain operation is permitted, and that permission is not in the metaproject, then that operation will be permitted.

For example, if you delete from the metaproject the predefined operation, ''ShutdownServer'' (which is otherwise enforced in the UI), this means that any user will be able to shut down the server from the [[Protege_Client_Server_Tutorial_Administration|Server Admin UI]]. The lesson is not to delete from the metaproject the predefined operations, especially if they are enforced (see policy table from below). Instead you can remove the policies attached to projects or the server.


== Project policies ==


Project policies refer to the policies that apply for a particular project. For example, you may restrict the permission of reading and opening a project to a certain group. The project policies are attached to instances of the ''Project class'' as show below:


[[Image:ClientServerTutorial_metaproject.png|center]]


Instances of the '''Project class''' will be made available to people identified with instances of the '''User class'''. 

If you examine instances of the User class, you will find the default ''Guest'' user. For the security conscious, your first task should be to delete the ''Guest'' user, and any other default users. (Before doing this, you may want to try creating some new users and ensure that they can successfully connect).

If you examine instances of the Project class, you will encounter among others the Newspaper and Collaborative Pizza projects. Note that these are just references to projects that exist on your disk as part of the default Protege installation. Also note that the specified file locations are relative to the Protege installation directory (actually the current working directory) rather than to the location of the metaproject. If you find this confusing, you can always specify the file locations as absolute paths. On a Window machine, for example, you can specify the absolute path as <code>C:\\MyProjectDiretory\\kbs\\MyProtegeKB.pprj</code> or <code>C:/MyProject/kbs/MyProtegeKB.pprj</code>. If you have other projects that you have created and you want to make them available in the client-server version, you should create instances of these projects in the metaproject. (We recommend making a copy of the metaproject first, just in case!). Remember to configure the policies of the projects (see Policies section below).


== Server policies ==

Server policies refer to policies that apply to the server itself. Usually the operations in the server policies are more of administrative nature:e.g., shut down the server, shut down a project, etc. 

Instances of the '''Server class''' represent different server configurations to which you may attach server policies (e.g., who has permission to shut down the server, or which user is allowed to kill other users' sessions). The current implementation only works with one instance of Server, which refers to the current Protege server. So there is no need to create more than one instance of Server. The default metaproject comes with the predefined instance "MyServer" that has some default policies attached to it. You may delete the existing policies or add new ones. It's not a good idea to give to all the users administrative rights on the server. Instead only an Admin group should have these privileges.


[[Image:ClientServerTutorial_metaproject_server.png|center]]


== Group policies ==

Group policies refer to operations that apply to groups, for example, adding a user to a group. One policy could state that only users from group ''Manager'' are allowed to add users to the group ''Editor''. The current metaproject comes with a predefined group operation called ''EditGroup'' that is currently not enforced.


= Metaproject classes =

The main classes of the metaproject ontology are explained briefly below:

* '''User''' - instances of this class will be the actual users who can login into the Protege server. A user has a user name, a password, a description, and can belong to one or more groups (or none). The last login time and the last access time is also stored in specific slots. To create a new user, select the class ''User'' and create a new instance and fill in the slots (property) values.

* '''Group''' - instances of this class are the groups available in the Protege server. A group has a name, a description and members of type ''User''. Policies can also be attached to groups (see information in Projects on how to do it). If you add a user to a group, the inverse relationship is create automatically (e.g., John is in the Editors group, then the Editors group will have as a member John).

*'''Operation''' - instances of this class and of its subclasses represent the operations available in the Protege editor (or in your own application that accesses the Protege server). An operation has a name and a description. The metaproject comes with some predefined operations: e.g., ''Read'', ''Write'', ''DisplayInProjectList''. The subclasses of ''Operation'' are used to group the different types of operations (e.g., into project, group or server operations).

*'''GroupOperation''' - instances of this class associate one or more groups of users with a set of operations. A predefined ''GroupOperation'' instance in the metaproject is the <code>World can Read and Write</code>. The group operations are not useful as stand alone instances, but they are associated to projects. For example, to the Collaborative Pizza project, we associate the group operation <code>World can Read and Write</code>, meaning that all the users who open the Collaborative Pizza project from a Protege client, will be able to read and write this project.

*'''PolicyControlledObject''' - it is just a super class for all the classes that can have policies attached to them, such as ''Project'', ''Group'' or ''Server''. No need to do anything with this class.

*'''Project''' - the most important class. This is where you will start by creating project instances and for navigation. The ''Project'' instances represent actual projects stored on the server side. These projects will be available to Protege clients that connect to this server. A project has:
**''a name'' - it may contain spaces, this is what is displayed in the available projects list on the client
**''a description'' - some text or documentation about the project
**''a location'' - can be relative to the Protege server installation directory, or absolute
**''policies'' - are associated to the project as instances of ''GroupOperation''
**''an annotation project'' - is optional. If you want to use [[Collaborative_Protege|Collaborative Protege]] or the [[Changes_Tab|Change Tab]] on the server, you need to configure this project. Step-by-step instructions are available [[Collaborative_Protege|here]]. For example, the Collaborative Pizza has an associated annotation project called Collaborative Pizza Annotations (also a "normal" project; an instance of ''Project'' class)

*'''Server''' - the second most important class. An instance of ''Server'' represents an actual Protege server to which you can attach policies. The current implementation does not support multiple instances of the ''Server'' class, so if you want to add policies to the server, make sure they are all attached to one (and the only one) instance of the Server class (the name of the instance is not important). A server has similar properties to a project:
**''a name'' - it may contain spaces
**''a description'' - some text or documentation about the server
**''a host name'' - the hostname of the server (e.g., smi-protege:stanford.edu:5200). In current implementation, this field is ignored, so you can leave it blank.
**''policies'' - are associated to the server as instances of ''GroupOperation''

Several of the classes have a ''properties'' slot that can be used to defined additional (property, value) pairs for different objects. An API is available for retrieving and storing these pairs.


= Modifying the metaproject =

If you have a '''running Protege server''', then the preferred way of changing the metaproject is to use the [[Protege_Client_Server_Tutorial_Administration#The_Metaproject_tab_-_live_changes_of_the_server_configuration|Metaproject Tab]] available in the [[Protege_Client_Server_Tutorial_Administration|Server Admin Panel]]. This allows you to modify the content of the metaproject without the need to restart the Protege server. Some of the operations that can be performed in the Metaproject Tab are: create new users, change passwords, change policies, add and delete projects, etc. If the metaproject is stored in a file (pprj, pont, pins files) and you change it, then it is a good idea to save the metaproject by going to the [[Protege_Client_Server_Tutorial_Administration#The_Server_Control_Tab|Server Control Tab]] in the Server Admin Panel, and click on the ''Save metaproject'' button, which ensures that your changes are saved to the metaproject file right away.

If the '''server is not running''', then you can edit the metaproject in the standalone Protege, and next time you start the Protege server, the changes will take effect.

'''NOTE''': If you have a running server, and modify the metaproject in standalone Protege by loading the metaproject file, your changes will not take effect until you restart the server. For a running server, use the Server Admin Panel.

= Add your own project in the metaproject = 

To open the metaproject, follow the instructions in "Modifying the metaproject", then create a new instance of the Project class, and fill in the property values as described above. (name, location, access policies, etc.)


= Predefined and enforced policies =

The Protege server comes with a predefined set of operations that can be used in policies. The list of operations together with a description, type and enforcements in the UI and API are shown in the table below.
It is not recommended that you delete any of the default operations in your customized metaproject. Instead you may remove the default policies attached to the server and project instances.

Remember that, if the name of an operation is not found in the metaproject, then when the code asks about it, it will always return that the operation is allowed. So, for example, if you remove the operation ''ShutdownServer'' from the metaproject, then any user will be allowed to shut down the server.


{| border="2" class="wikitable"
|-
! Permission
! Description
! Enforced
! Type
|-
| '''DisplayInProjectList'''
| If a project does not have this operation associated to it, then the project will not be displayed in the available project list when a user logs into the server. This operation is useful, if you want to hide certain projects from the available projects list for the users, but you still want to be able to read them. A good example is the changes and annotations project that is used by collaborative Protege. You would not want the users to see the annotations project and open it directly in the client.
| Yes
|Project
|-
|'''Read'''
|The read operation on an ontology. A user who does not have write access to an ontology, will not be able to view the ontology and will not see the ontology in the available project list.
|'''YES'''
|Project
|-
|'''Write'''
|The write operation on an ontology. A user who does not have write access to an ontology, will not be able to perform any edits. The user interface will not show all edit icons as disabled, but once the write operation is attempted, the user will get a dialog that the operation is not permitted. This policy is enforced starting with Protege 3.4 RC2.  
|'''YES'''
|Project
|-
|'''EditGroup'''
|The operation of adding or removing users to a group.
|No
|Group
|-
|'''CreateUsers'''
|The operation of creating users. *It is enforced only in WebProtege. Users with this access right can create user accounts.
|Yes*
|Server
|-
|'''AdministerServer'''
|A super-permission: a user who has this right can kill other users' sessions, stop and start server projects without having these rights set for each ptoject individually. He may also shut down the server without having the shut down permission explicitly set. 
|Yes
|Server
|-
|'''Delegate'''
|A super-permission:This  operation allows a user to make alterations to his credentials.  This privilege should probably only be  used by fake users representing server processes.
|Yes
|Server
|-
|'''KillOtherUserSession'''
|The operation of killing another users' sessions. This is allowed
|Yes
|Server
|-
|'''ShutdownServer'''
|The operation of shutting down the Protege server.
|Yes
|Server
|-
|'''StartRemoteProject'''
|The operation of starting a (previously stopped) server project.
|Yes
|Server and Project
|-
|'''StopRemoteProject'''
|The operation of stopping/closing a running server project.
|Yes
|Server and Project
|-
|'''PropertyTabRead'''
|The operation of reading/enabling the property tab.
|No
|Project
|-
|'''PropertyTabWrite'''
|Any edit operation made in the OWL Properties Tab. If a user does not have this permission for a project, then she will not be able to edit the properties using the buttons in the OWL Properties Tab.
|Yes
|Project
|-
|'''OntologyTabRead'''
|The operation of reading/enabling the Metadata tab for OWL ontologies.
|No
|Project
|-
|'''OntologyTabWrite'''
|Any edit operation made in the OWL Metadata Tab. If the user does not have this permission for a project, then she will not be able to so ant edits using the buttons in the OWL Metadata Tab.
|Yes
|Project
|}


= Create new users from the client =

By default, the server will disallow the creation of new users in the "Login to Server" panel when clicking on the "New user" button. To allow the creation of new users by clicking on the "New user" button on the client, add to the <code>protege.properties</code> file the following line:

 server.allow.create.users=true

After editing the protege.properties, you need to restart the Protege server, for the changes to take effect.

'''NOTE'''. This check will be deprecated in future versions of Protege server, and instead we will use a server policy to control the creation of new users.


= Checking the permissions using the API =

The [http://protege.stanford.edu/protege/3.4/docs/api/core/edu/stanford/smi/protege/server/RemoteServer.html <nowiki>RemoteServer</nowiki> interface] provides methods for checking the permissions of a user session for a specific operation. The methods:

* [http://protege.stanford.edu/protege/3.4/docs/api/core/edu/stanford/smi/protege/server/RemoteServer.html#isOperationAllowed(edu.stanford.smi.protege.server.RemoteSession,%20edu.stanford.smi.protege.server.metaproject.Operation,%20java.lang.String) isOperationAllowed(RemoteSession session, Operation op, String prjName)] - checks whether the ''session'' has the permission to execute the operation ''op'' on the server project ''project''. So this is a way to '''check a project permission'''.
* [http://protege.stanford.edu/protege/3.4/docs/api/core/edu/stanford/smi/protege/server/RemoteServer.html#isServerOperationAllowed(edu.stanford.smi.protege.server.RemoteSession,%20edu.stanford.smi.protege.server.metaproject.Operation) isServerOperationAllowed(RemoteSession session, Operation op)] - checks whether the user session ''session'' has the right to perform the server operation ''op''. This method works with the policies attached to the first found instance of the ''Server'' class. This method provides a way to '''check a server permission'''.

The predefined operations can be found in the class [http://protege.stanford.edu/protege/3.4/docs/api/core/edu/stanford/smi/protege/server/metaproject/MetaProjectConstants.html MetaProjectConstants].

If in your application, you have already logged in and have a reference to a remote [http://protege.stanford.edu/protege/3.4/docs/api/core/edu/stanford/smi/protege/model/KnowledgeBase.html KnowledgeBase] object, then to check a permission, you can use the call:

 RemoteClientFrameStore.isOperationAllowed(kb, MetaProjectConstants.OPERATION_WRITE)


To create your own operation objects, you may call:

 Operation mySpecialOperation = new UnbackedOperationImpl("MySpecialOperation", null)

If you have policies in the metaproject that involve the ''MySpecialOperation'', then make sure that the name of the ''Operation'' instance in the ontology corresponds exactly to the argument passed to the method from above.

How to open a remote project using the API is described on the [[Protege_Client_Server_Tutorial_Advanced#Accessing_the_Server_Programatically| Advanced Server topics website]].


'''Read more about the Protege multi-user support in the [[Protege_Client-Server_Tutorial|Protege client-server tutorial]].'''