Security Module

The Security Module provides an API for access authorization (the only one currently implemented), user authentication and contextual security (supported by the old core). In order to expose the old RightService APIs, the Security Module provides a bridge.

Access Authorization API

The Access Authorization module uses caching techniques to store both access rules and resulting access decisions made by the authorization settler. The general API interface is provided by the Role AuthorizationManager.

The bridged version of the old XWikiRightServiceImpl is called XWikiCachingRightService and it should only be used when the new API does not fit your needs. An example would be the need to use  public void dropPermissions() which is only supported by the bridged XWikiCachingRightService because the Access Authorization Module does not provide contextual answers. 

The authorization system is based on 2 principles:

In conclusion, the task of settling access decisions is delegated to customizable components that don't require a platform rebuild in order to be configured. The component hint of the AuthorizationSettler may be configured from the "WEB-INF/xwiki.properties" file using the key security.authorization.settler. The default hint default is implemented by the DefaultAuthorizationSettler.

Contextual Security API

The security context is provided by the Role ContextualAuthorizationManager and contains information about the authenticated user, the current macro being executed, the rendering context restriction, the dropping of rights by the macro.

Security References

A SecurityReference is a variant of EntityReference used internally in the security-authorization module for the purpose of conveniently maintaining a hierarchy where all entities are rooted by the main wiki. This form of hierarchical view is required when deciding which access levels should be enforced. There is always a one-to-one correspondence between a SecurityReference and a Wiki-, Space-, or DocumentReference. Moreover, a security reference built with a null EntityReference is equivalent to the main wiki reference but with a null original reference.

The SecurityReferenceFactory component is used to create a new instance of SecurityReference, UserSecurityReference and GroupSecurityReference. This factory currently uses an internal XWikiBridge interface to retrieve the main wiki reference. Most interfaces are public and are defined in org.xwiki.security.authorization or in org.xwiki.security.authorization.cache.

org.xwiki.security.authorization Interfaces:

  • SecurityRule defines a security rule by linking a set of Right (i.e. VIEW), a set of UserSecurityReference, a set of GroupSecurityReference and a RuleState (i.e. Allow).
  • SecurityRuleEntry links a list of SecurityRules with a SecurityReference. When it is empty it means that no rules are defined for that entity.
  • SecurityEntryReader reads rules attached to a given entity.

org.xwiki.security.authorization.cache Interfaces:

  • SecurityCache allows direct access to the SecurityCache to remove outdated entries. This should only be done by a component implementing the SecurityCacheRulesInvalidator interface to avoid conflict with the security cache loader.
  • SecurityCacheRulesInvalidator informs the SecurityCache of changes in security rules to properly invalidate outdated cache entries. If the security invalidator does not properly invalidate entries, CacheConflictingException may occur.

The authentication part of the security module which should be in charge of user and group management is currently missing. Therefore, an internal UserBridge interface is used to get groups information. Also, another internal XWikiBridge interface is used to check if the wiki is in read-only mode and to retrieve the main wiki reference.

Scripting API

The Scripting API provides access to the general and contextual security APIs using script services. The syntax is $services.security.authorization.*.

Examples

1. #set($discard = $services.security.authorization.hasAccess("edit")) 

2. #set($discard = $services.security.authorization.hasAccess("admin", "xwiki:XWiki.XWikiPreferences")) 

3. #set($discard = $services.security.authorization.hasAccess("admin", $context.getUser(), 
"xwiki:XWiki.XWikiPreferences"))
 

4. $services.security.authorization.checkAccess("edit")

Use hasAcess() or checkAccess()?

Signatures

public boolean hasAccess(Right right){}
public boolean hasAccess(Right right, EntityReference entity){}
private boolean hasAccess(Right right, DocumentReference user, EntityReference entity){}

public void checkAccess(Right right) throws AccessDeniedException {}
public void checkAccess(Right right, EntityReference entity) throws AccessDeniedException {}
private void checkAccess(Right right, DocumentReference user, EntityReference entity) throws AccessDeniedException {}

In the old XWiki Rights implementation, there was no distinction between the access check for UI purposes and the access check before executing an action. Thus, only the hasAccess() method was provided. 

In the new Security Module, both hasAcess() and checkAccess() do an access check, the only difference being the way the result is reported, more specifically:

  • hasAccess() provides a true or false answer
  • checkAccess() throws an AccessDeniedException exception when the access is denied which is why it is recommended to use it whenever you need to check an access before executing an action. Also all access violations done during checkAccess() are logged.

XWiki Rights Overview

View Right

The view right gives the user the ability to view a document or load it using the API.

  • Availability: Page, Space and Wiki level.
  • Default status: ALLOWED
  • Priority order: deny > allow > no setting
  • Checking order: page > space > wiki

Comment Right

The comment gives the user the ability to add a comment, but not to edit or delete it.

  • Availability: Page, Space and Wiki level.
  • Default status: ALLOWED
  • Priority order: deny > allow > no setting
  • Checking order: page > space > wiki
In order to be able to edit or delete your own comments, you need to have edit rights on the space or page. Also, you won't be able to edit or delete the comments of other users, unless you have administration rights.

Edit Right

The edit allows you to edit the page and all of its objects.

  • Availability: Page, Space and Wiki level.
  • Default status: ALLOWED
  • Priority order: deny > allow > no setting
  • Checking order: page > space > wiki

Delete Right

The delete right allows you to move a page to the recycle bin.

  • Availability: Page, Space and Wiki level.
  • Default status: DENIED (unless you're the document creator)
  • Priority order: deny > allow > no setting
  • Checking order: page > space > wiki

Administration Rights

The administration right can only be granted at space or wiki level. A very important detail is that the wiki administrator cannot have his/her administration rights denied for a space. Also, having administration rights imply the view, comment, edit and delete permissions with the added ability to permanently delete a page from the recycle bin.

  • Availability:
    • Space (Automatically includes the view, comment, edit, delete rights)
    • Wiki (Automatically includes the view, comment, edit, delete, register)
  • Default status: DENIED
  • Priority order: allow > deny > no setting
  • Checking order: wiki > space

Programming Rights

A programmer is allowed to execute arbitrary Java code in the wiki, so any page which was last saved by an user with programmer rights can run dangerous scripts. Because it affects the entire wiki (or wiki farm), programming rights can only be granted from the wiki preferences page in a single wiki environment or from the main wiki in a multi-wiki environment.

  • Availability: Main wiki level
  • Default status: DENIED
  • Priority order: allow > deny > no setting
  • Checking order: wiki

Register Rights

The register right is usually granted or revoked for the non-registered pseudo-user "XWiki.XWikiGuest". This permission can only be set from the wiki preferences page.

  • Availability: Wiki level
  • Default status: ALLOWED
  • Priority order: allow > deny > no setting
  • Checking order: wiki

Create Wikis Rights

The "createwiki" right can only be granted via the main wiki, just like programming rights. For detailed information, check this "Create a Sub-Wiki" documentation page.

  • Availability: Main wiki level
  • Default status: DENIED
  • Priority order: allow > deny > no setting
  • Checking order: wiki

Default Values for Rights

Default Values for Rights at Main Wiki Level

When a right has been allowed at a given level, it gets explicitly denied to anyone else at the same level.
 Wiki Right Default Value Comments
VIEWALLOWED
EDITALLOWEDEDIT rights at wiki level also imply VIEW rights
COMMENTALLOWED
DELETEDENIED
REGISTERALLOWED
ADMINDENIED
  • ADMIN rights at wiki level also imply the VIEW, EDIT, COMMENT, DELETE and REGISTER rights.
  • If ADMIN rights are granted at wiki level, they cannot be denied at a lower level (space or page).
  • The rights implied by ADMIN rights will not be overridden by a denial at a lower level.
PROGRAMDENIED
  • Programming rights can only be set in the main wiki.
  • PROGRAMMING rights at wiki level also imply VIEW, EDIT, COMMENT, DELETE, REGISTER and ADMIN rights.
  • If PROGRAMMING rights are granted at wiki level, they cannot be denied at a lower level (space or page)    
CREATE WIKIDENIEDThe rights to create wiki can only be granted via the main wiki.

Default Values for Rights at Sub-wiki Level

When a right has been allowed at a given level, it gets explicitly denied to anyone else at the same level.
 Wiki Right Default Value Comments
VIEWALLOWED
EDITALLOWEDEDIT rights at wiki level also imply VIEW rights
COMMENTALLOWED
DELETEDENIED
ADMINDENIED
  • ADMIN rights at wiki level also imply the VIEW, EDIT, COMMENT and DELETE rights.
  • If ADMIN rights are granted at wiki level, they cannot be denied at a lower level (space or page).
  • The rights implied by ADMIN rights will not be overridden by a denial at a lower level.

Default Values for Rights at Space Level

When a right has been allowed at a given level, it gets explicitly denied to anyone else at the same level.
 Wiki Right Default Value Comments
VIEWALLOWED
EDITALLOWEDEDIT rights at space level also imply VIEW rights
COMMENTALLOWED
DELETEDENIED
ADMINDENIED
  • ADMIN rights at space level also imply the VIEW, EDIT, COMMENT and DELETE rights.
  • The rights implied by ADMIN rights will not be overridden by a denial at a lower level.

Default Values for Rights at Page Level

When a right has been allowed at a given level, it gets explicitly denied to anyone else at the same level.
 Wiki Right Default Value Comments
VIEWALLOWED
EDITALLOWEDEDIT rights at page level also imply VIEW rights
COMMENTALLOWED
DELETEDENIED

Users and Groups

A right allowed to the user cannot be denied by another rule at the same level for a group having that user as a member. For instance, on the same document, a rule allowing edit rights to an user "XWiki.UserA" from "XWikiEditorsGroup" and a rule denying edit rights for the group "XWikiEditorsGroup" enter in conflict. Therefore edit rights will be denied to every member of the group "XWikiEditorsGroup" except for the user "XWiki.UserA".

Rights implied by an administration right cannot be overridden by denial at a lower level. Supposing "XWiki.UserA" has administration rights at wiki level and denied edit rights on the space "Main", he/she will still have edit rights on the space "Main" because they are implied by the administration rights at wiki level.

When a right has been allowed at a given level, it gets explicitly denied to everyone else at the same level. So, if "XWiki.UserA" has edit rights on "Main.WebHome", user "XWiki.UserB" will have denied edit rights in the same document unless user "XWiki.UserB" gets an implied edit right with a different inheritance policy at a higher level (like he is an administrator on the space "Main" or on the entire wiki).

Finally, an implied right does not imply other rights and it not recursively applied. 

 

   

Search this space