Hallo mensen, Hierbij een eerste versie van het context security document zoals het in de cvs staat alleen dan vertaald naar het engels. Ik heb hier en daar geprobeerd wat verduidelijkingen toe te voegen. Laat maar horen wat er van klopt en waar ik nog meer uitleg moet gaan geven. Mijn idee is wel om nog een herstructuering toe te passen om de leesbaarheid te verhogen. Groeten,
Sjoerd de Heer Quote: 'Which quote? who's quote? Mine, you must be nuts!' ----
Context Security Configuration
Introduction
Security framework within MMBase.
Within MMBase is a security framework, in which different security implementations can be used. In this way it is possible to adapt MMBase to the needs of the environment in which it runs. Currently there are a few different implementations ready. The context security and the cloud security are the most advanced schemes available.
A security implementation with contexts.
The NOS ( a Dutch broadcasting company) choose an implementation with contexts. A context exists of a set of rights which describe what you can do within this context with an object of MMBase. For example you define read access to a the context which is used by anonymous visitors of your site and you can define a context with edit rights for registered users of your site. The main parts of the security framework are:
- Single users (users)
- Groups (users)
- Contexts
- Users
The users of MMBase can have different levels anonymous or registered users. The anonymous users are the normal page viewers. There rights are being served through the anonymous module of MMBase. Registered users are being served through the user/password module, this are the users that can alter data within MMBase.
For registered users there is also an extra level called rank. The default ranks are 'Basic user' and 'Administrator'. These ranks can denote extra rights within MMBase. The anonymous users can only have the rank 'Anonymous'.
Groups.
A Group can exist of users and/ or groups. In this way you can define a structure which inherits rights from lower levels. For example the office-sweeper group may read the newspaper. The office-clerk group is member of the office-sweeper group but may also use the toilet. So a member of the office-clerk may read the newspaper and go to the toilet, even at the same time. While a office-sweeper can only read the paper and work fast to get home in time to use the bathroom. As you probably noticed a stupid example which might help to understand the framework.
A user van be member of more than one group within MMBase.
Contexts.
Each object within MMBase has a context. Which context is associated with an object can be seen in the owner field of that object. The name found there is the name first used as context before fallback on the default context. In the context is defined which rights are granted to a user or group. The following rights are available.
- read, read the content of an object.
- write, write content to an object.
- link, making a relation between two objects.
- delete, remove an object.
- create, create a new object of the type typedef. The so called editors.
- change, changing of context.
Of each context is also know to which context it may change. An admin may change to a user but a user may not change to an admin.
Background information on XML.
XML
XML stands for "EXtensible Markup Language"
XML is a mark-up language
XML describes data
XML uses a DTD(Document Type Definition) for describing the data-structure within the document.
XML is with a DTD developed, so it should be self explaining.
XML Layout
A very simple XML could be the following:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE root SYSTEM "definition.dtd"> <root> </root>
This XML uses "utf-8" as encoding and uses definition.dtd to validate the XML file for correctness.
DTD Layout
Above is a simple XML document which could be described by such a DTD:
<!ELEMENT root #PCDATA)>
There should be more text here but it seems to be missing. The DTD needs some more work.
The first element allows only the use of <root> tags. In the tag itself is text also allowed to for example explain the use of the tag.
XPath
With the use of XPath is it possible to denote a certain location in a xml file. The location can be enclosed in an element or a field of an element. For XPath / counts as the root of the document. To separate elements you should use a '/' between those elements. In the case that you point to a field inside an element you should use 'element[@fieldname]'
More information
XML is a W3C standard, a beginners course can be found at: http://www.w3schools.com/xml/
An explanation of XPath can be found at the following point: http://www.zvon.org/xxl/XPathTutorial/General/examples.html
How to configure the security-framework
General.
The security framework makes it possible to use different implementations for security within MMBase. The implementation that will be used depends on the configuration file which can be found in youd configuration directory and then in the sub-dir called security. The file security.xml is the file you are looking for.
Example security.xml
The supplied %confgidir%/security/security.xml should look like this, approximately:
<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE security PUBLIC "//MMBase - security//" "http://www.mmbase.org/dtd/security.dtd"> <security active="true"> <authentication class="org.mmbase.security.implementation.context.ContextAuthentication" url="context/config.xml" /> <authorization class="org.mmbase.security.implementation.context.ContextAuthorization" url="context/config.xml" /> <sharedsecret>appelmoes</sharedsecret> </security>
(All comment lines have been left out.)
Within this document you can alter the following items:
/security[@active] : Valid values are 'true' and 'false'. If the value is set to true then the selected security shall be loaded. If the value is 'false' then there will be no security implementation loaded but the document will also not be checked for changes so no reloads will occur.
/security/authentication[@class] : This denotes which implementation will be loaded as security.
/security/authentication[@url] : In this element you can give parameter for the security implementation like a configuration file for that security type.
/security/authorization[@class] : The implementation that will check if the requested operation is valid for this user in MMBase.
/security/authorization[@url] : Same as with authentication, you can give additional parameters here. Like the location of a configuration file.
/security/sharedsecret : It is possible to run more than one MMBase on the same data source if that is true then they will use this password to communicate.
Framework XML for Context Security
The following XML will start the context security with an additional configuration found in the file named context/config.xml. It is not using a shared secret so it cannot cooperate with an other running MMBase on the same data source.:
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE security PUBLIC "//MMBase - security//" "http://www.mmbase.org/dtd/security.dtd">
<security active="true">
<authentication class="org.mmbase.security.implementation.context.ContextAuthentication" url="context/config.xml" />
<authorization class="org.mmbase.security.implementation.context.ContextAuthorization" url="context/config.xml" />
<sharedsecret></sharedsecret>
</security>
Some explanation of the different fields:
<security active="true"> /security[@active='true'] : The selected security systems shall be loaded.
<authentication class=" ......" /> /security/authentication[@class='org.mmbase.security.implementation.context.ContextAuthentication'] : This is used to select a security implementation for login in this case the context implantation.
url="context/config.xml" /security/authentication[@url='context/config.xml'] : This gives the location of the context security configuration file.
<authorization class=" " /> /security/authorization[@class='org.mmbase.security.implementation.context.ContextAuthorization'] : This is the selected implementation for checking which operations are allowed inside MMBase.
url="context/config.xml" /security/authorization[@url='context/config.xml'] : The location of the configuration file.
<sharedsecret></sharedsecret> /security/sharedsecret/ = "" : There is no need for a shared secret this is the only MMBase running on this data source.
Framework DTD for security XML
This is the DTD om which the previous XML is based:
<!ATTLIST security active (true|false) #REQUIRED > <!ELEMENT security ( authentication, authorization, sharedsecret ) > <!ELEMENT authentication EMPTY > <!ATTLIST authentication class NMTOKEN #REQUIRED > <!ATTLIST authentication url CDATA #REQUIRED > <!ELEMENT authorization EMPTY > <!ATTLIST authorization class NMTOKEN #REQUIRED > <!ATTLIST authorization url CDATA #REQUIRED > <!ELEMENT sharedsecret ( #PCDATA ) >
The working of Context Security
Reference field
Within MMBase has each object a field called 'owner'. The value of this field is used by the security system to select the rights of a user on this object. If the name of this context does not exist a warning will be issued in the logs and the default context will be selected.
Contexts
A context defines which rights a group has on a object. Also is defined within this context to which contexts you can change to assume there rights.
Groups
A group is a collection of users and groups. In this way you can represent your organisation in the security system. If used properly in combination with contexts for each group.
Users
Anonymous users
These users get there rights from the module called anonymous. They are considered the normal page viewers. There rank will always be 'ANONYMOUS'.
Logged in users.
These users are validated through the user/password module of the context security. They are the users which can change your data in MMBase. The rank of these users is normally 'Basic users' but can also be 'Administrator' which is a rank that grants more rights within MMBase.
Overview picture of the system.
In this picture is missing the element rank in the user box.
Operations on objects
Read, Write and Delete
To be able to read or write or delete an object in MMBase a user needs the right 'read' or 'write' or 'delete' for this object.
Making a reference to.
The right 'link' give a user the possibility to create relations between objects in MMBase. The user needs create rights on the relation builder for this to work!
Create
The right 'create' is only used for builders. It gives the specified user the right to create objects in this selected builder.
Change
The right 'change context' gives a users the right to alter the rights defined in the selected context.
How to..
Create a new object
To be able to create an object the user needs 'create' rights on the node that represents the node-type within MMBase, see the typedef table.
Creating a new relation
To create a new relation your users needs 'create' rights on the insrel table and 'link' rights between the objects where he or she wants to create a relation in-between.
Altering an object
To be able to change an object the user needs the 'change' right for that object.
Changing rights in contexts
When you want a user to be able to change the rights of a context then that user needs 'change context' rights for that selected context.
removal of objects
To remove an object the user needs 'delete' rights.
The XML
Example XML for context security.
With the following XML shall we provide some explanation on the set-up of the context security configuration.
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE contextconfig PUBLIC "//MMBase - contextconfig//" "http://www.mmbase.org/dtd/securitycontextconfig.dtd"> <contextconfig> <loginmodules> <module name="anonymous" class="org.mmbase.security.implementation.context.AnonymousLogin" /> <module name="name/password" class="org.mmbase.security.implementation.context.PasswordLogin" /> </loginmodules> <accounts> <user name="anonymous" context="default" /> <user name="admin" context="admin"> <identify type="name/password" rank="administrator">admin2k</identify> </user> <user name="foo" context="default" > <identify type="name/password" rank="basic user">bar</identify> </user> </accounts> <groups> <group name="everyone"> <contains type="group" named="users" /> <contains type="user" named="anonymous" /> </group> <group name="users"> <contains type="user" named="foo" /> <contains type="group" named="administrators" /> </group> <group name="administrators"> <contains type="user" named="admin" /> </group> </groups> <contexts default="default"> <context name="default"> <operation type="create"> <grant group="users" /> </operation> <operation type="read"> <grant group="everyone" /> </operation> <operation type="write"> <grant group="users" /> </operation> <operation type="link"> <grant group="users" /> </operation> <operation type="delete"> <grant group="users" /> </operation> <operation type="change context"> <grant group="administrators" /> </operation> <possible context="default" /> </context> </contexts> </contextconfig>
Explanation of the XML
/contextconfig/loginmodules : This is the module that takes care of the login process within MMBase. There are no changes needed to this field so it will not be described any further.
/contextconfig/accounts : This are the accounts of the users which are know to the system. It is advised to also create a user called anonymous since it does not exists any ware else.
<user name="%name%" context="%defaultcontext%" > <identify type="name/password" rank="%rank%">%password%</identify> </user>
The following values can be given to the elements.
user[@name] : The name of the user..
user[@context] : The context that object get when created through this user.
user/identify[type] : The login type refers to /contextconfig/loginmodules/module[@name] , this shall always be "name/password".
user/identify[rank] : This is the rank of the user after login. The default is 'basis user' unless a person is administrator then the rank will be 'administrator'. Anonymous users always get the rank 'anonymous'
user/identify : The password for this user.
/contextconfig/groups : This defines groups within the context security. The following structure applies: structure:
<group name="%name%"> <contains type="user" named="%username%" /> <contains type="user" named="%username%" /> <contains type="group" named="%groupname%" /> <contains type="group" named="%groupname%" /> </group>
The following values can be given to the elements:
group[@name] : The name of the group.
group/contains[@type] : The type of of the element 'named' valid values are 'user' and 'group'.
group/contains[@named] : The group or user that is member of this group. The element 'type' determines of this is a user or a group member. If you specify the wrong type then the correct entry cannot be found.
/contextconfig/contexts : This is a list of context that can be used within the context system.
/contextconfig/contexts[@default] : This field refers to a context that should be used when the owner field of an object refers to an context that cannot be found. So the value should be named in one of the /contextconfig/contexts/context[@name] elements.
Within these /contextconfig/contexts is it possible to create new contexts which use the following structure:
<context name="%contextname%"> <operation type="%operation%" /> <operation type="%operation%"> <grant group="%groupname%" /> <grant group="%groupname%" /> </operation> <possible context="%contextname%" /> <possible context="%contextname%" /> </context>
context[@name] : The name of the context.
context/operation[@type] : The type of operation where rights are granted to. Valid values are 'read', 'write', 'link', 'delete' and 'change context'
context/operation/grant[@group] : The group which receives the rights within this context. Off course the group should be found in a /contextconfig/groups/group[@name='%groupname%'] element.
context/possible[@context] : When the context of object van be changed, it can only be changed into the values specified in this element. Which should be found in an element called /contextconfig/contexts/context[@name=%contextname%].
The DTD of context.xml
For completeness this is the full DTD used for context.xml:
<!ELEMENT contextconfig ( loginmodules, accounts, groups, contexts ) > <!ELEMENT loginmodules ( module+ ) > <!ELEMENT module ( property* ) > <!ATTLIST module class NMTOKEN #REQUIRED > <!ATTLIST module name CDATA #REQUIRED > <!ELEMENT property ( #PCDATA ) > <!ATTLIST property name NMTOKEN #REQUIRED > <!ELEMENT accounts ( user+ ) > <!ELEMENT user ( identify* ) > <!ATTLIST user context NMTOKEN #REQUIRED > <!ATTLIST user name NMTOKEN #REQUIRED > <!ELEMENT identify ( #PCDATA ) > <!ATTLIST identify rank (administrator | basic user) #REQUIRED > <!ATTLIST identify type CDATA #REQUIRED > <!ELEMENT groups ( group+ ) > <!ELEMENT group ( contains+ ) > <!ATTLIST group name NMTOKEN #REQUIRED > <!ELEMENT contains EMPTY > <!ATTLIST contains named NMTOKEN #REQUIRED > <!ATTLIST contains type NMTOKEN #REQUIRED > <!ELEMENT contexts ( context+ ) > <!ATTLIST contexts default NMTOKEN #REQUIRED > <!ELEMENT context ( operation*, possible* ) > <!ATTLIST context name NMTOKEN #REQUIRED > <!ELEMENT operation ( grant* ) > <!ATTLIST operation type (read | write | link | delete | change context) #REQUIRED > <!ELEMENT grant EMPTY > <!ATTLIST grant group NMTOKEN #REQUIRED > <!ELEMENT possible EMPTY > <!ATTLIST possible context NMTOKEN #REQUIRED >
Extra information:
When you alter one of the xml files related to the security implementation the whole security implementation shall be reloaded within a minute. If there are errors within the configuration file a message shall be given and the old configuration will be kept active.
