Current development on JAMWiki is primarily focused on maintenance rather than new features due to a lack of developer availability. If you are interested in working on JAMWiki please join the jamwiki-devel mailing list.

Help:Permissions

ktip.png Please contribute to the JAMWiki project by helping to improve this article. Add to or expand some of the existing information, fix an error, or share your own knowledge to improve this subject! Don't worry about making mistakes - there will always be someone who can correct any errors later.

This topic provides a detailed overview of JAMWiki's capabilities for managing user rights, integrating with third-party authentication tools such as LDAP, and advanced configuration for installations with more specific security requirements.

Contents

Overview[edit]

There are three ways in which permissions are handled in JAMWiki:

  • Special:Roles. This JAMWiki administrative interface allows sysadmins to specify what user rights are required to perform specific actions, such as editing, uploading, etc.
  • Special:Manage. For every topic, and admin can limit the topic to be editable only by admins, or by no one at all.
  • Spring Security. This authentication and authorization framework is used for controlling specific topic permissions, user authentication, and other basic capabilities.

Special:Roles[edit]

Security within JAMWiki is handled using Spring Security and through the Special:Roles interface.

JAMWiki installs with a default Spring Security configuration that creates roles and permissions for users and groups in the JAMWiki database. By default the security code works by allowing specific users or groups the permission to perform certain tasks, while forbidding them from performing other tasks. For example, by default all logged-in users can upload files, but anonymous users cannot.

The two default JAMWiki groups are GROUP_ANONYMOUS and GROUP_REGISTERED_USER. Any user who is not logged in is automatically a member of GROUP_ANONYMOUS, while logged in users are automatically assigned to GROUP_REGISTERED_USER. Each of these groups can be assigned roles, which allow the members of the groups to perform wiki tasks. The default roles are:

ROLE_ADMIN
All users assigned ROLE_ADMIN will have permission to delete topics as well as to edit those topics that are marked admin-only (which can be done from the "Manage" tab for each topic).
ROLE_EDIT_EXISTING
This role provides the ability to edit existing wiki topics.
ROLE_EDIT_NEW
This role provides the ability to create new wiki topics.
ROLE_DELETE
This role is unused and will be removed in JAMWiki 0.6.1. To allow a user to delete topics they must be assigned ROLE_ADMIN.
ROLE_MOVE
Only those users with ROLE_MOVE will see the "Move" tab, which allows topics to be renamed.
ROLE_SYSADMIN
This role allows a user to access Special:Admin, Special:Roles, and Special:Maintenance.
ROLE_TRANSLATE
This role allows a user to access Special:Translation and update translation files.
ROLE_UPLOAD
In order to upload files to the wiki from Special:Upload a user must have this role.
ROLE_VIEW
ROLE_VIEW is the default role that is required for viewing any other wiki page not covered by the other roles. Without this role a user would be able to do little more than view the login screen.

In addition to group roles, individual users may also be assigned roles. This functionality is useful for roles such as ROLE_SYSADMIN; it is unlikely that a wiki would allow all logged-in users to modify system settings, so it makes sense to assign this role to only a handful of individual users. Note that when roles are assigned to individual users they will have both the roles assigned to them as an individual and those roles that are assigned to GROUP_REGISTERED_USER.

Special:Maintenance[edit]

Administrators will see a "Manage" tab for every topic that provides options for performing administrative tasks. This tab provides two checkboxes that offer the ability to control user rights for the topic:

  • Read-Only. Checking this box indicates that no one will be able to edit the topic, including administrators. The only way to again make the topic editable is by unchecking this box.
  • Admin-Only. Checking this box indicates that only users with ROLE_ADMIN will be able to edit the topic, including administrators. The only way to again make the topic editable is by unchecking this box. A list of current read-only topics can be found using the Special:TopicsAdmin tool.

Spring Security[edit]

Spring Security is a security framework that provides authentication and authorization management. As of version 0.9.0, JAMWiki uses Spring Security 3.0. Full documentation of Spring Security can be found in their reference guide, but most users will not need to make customizations or will require only minor modifications to the default JAMWiki configuration.

Roles & Permissions[edit]

Using role-based permissions[edit]

All Spring Security configuration is done through the /WEB-INF/applicationContext-security.xml file. The section of this file that will be of most interest to the majority of users is the <http> section, which establishes the overall security strategy and defines what roles are required to access various portions of the wiki. For example:


	<http auto-config="false" entry-point-ref="authenticationEntryPoint">
		<intercept-url pattern="/**/Special:Admin" access="ROLE_SYSADMIN" />
		<intercept-url pattern="/**/Special:Edit" access="ROLE_EDIT_EXISTING,ROLE_EDIT_NEW" />
		<intercept-url pattern="/**/Special:Upload" access="ROLE_UPLOAD" />
		<intercept-url pattern="/**" access="ROLE_VIEW" />
		<remember-me key="jam35Wiki" />
		<anonymous key="jam35Wiki" />
		<!-- note that the JAMWiki LoginServlet will add the appropriate logout success URL to the request during logout -->
		<logout />
	</http>

While greatly simplified, the above example illustrates important concepts. In this case, the <intercept-url> elements define the roles required to access various portions of the wiki. Anyone accessing the Special:Admin page must have a user account with ROLE_SYSADMIN. Similarly, anyone trying to upload a file must have ROLE_UPLOAD. Finally, all pages that are not restricted by a previous pattern are limited by the /** pattern to users with ROLE_VIEW. The Special:Roles page allows roles to be assigned to users and groups; by default JAMWiki assigns ROLE_VIEW to all logged-in AND anonymous users.

Protecting specific topics[edit]

Many wikis will want to protect portions of their site, and this can be done by adding a pattern to /WEB-INF/applicationContext-security.xml. For example, if an IT department wanted to protect its security information it might create those documents only under a "Secure" sub-directory, and then create a role called ROLE_IT_MEMBER that would be assigned to all IT users. Updating the <http> section of /WEB-INF/applicationContext-security.xml file as follows would then restrict all pages such as http://example.com/wiki/en/Secure/Secure_IT_Page to those users:


	<http auto-config="false" entry-point-ref="authenticationEntryPoint">
		<intercept-url pattern="/**/Secure/**" access="ROLE_IT_MEMBER" />
		<intercept-url pattern="/**/Special:Admin" access="ROLE_SYSADMIN" />
		<intercept-url pattern="/**/Special:Edit" access="ROLE_EDIT_EXISTING,ROLE_EDIT_NEW" />
		<intercept-url pattern="/**/Special:Upload" access="ROLE_UPLOAD" />
		<intercept-url pattern="/**" access="ROLE_VIEW" />
		<remember-me key="jam35Wiki" />
		<anonymous key="jam35Wiki" />
		<!-- note that the JAMWiki LoginServlet will add the appropriate logout success URL to the request during logout -->
		<logout />
	</http>

IMPORTANT: Patterns are applied sequentially, so the first pattern that matches will be used. Administrators MUST place the most specific patterns first in the list, otherwise they will be superseded by less-specific patterns.

Note that the example above does NOT completely protect topic data from being viewed by any user - an enterprising user might still be able to view the wiki syntax by using the history or edit page functionality. For sites need greater protection, see below.

Advanced topic protection[edit]

For sites that need to more fully protect topic content from being viewed the edit and history pages will also need to be protected. To do so requires changing the Spring intercept-url patterns from ANT-based patterns to regular expression-based patterns. A detailed overview of regular expressions is beyond the scope of this wiki, but the following example should provide enough information for most site administrators:


	<http auto-config="false" entry-point-ref="authenticationEntryPoint" path-type="regex">
		<intercept-url pattern="/(.)+/Secure/(.)+" access="ROLE_IT_MEMBER" />
		<intercept-url pattern="/(.)+/Special\:[^\?]+\?topic\=Secure/(.)+" access="ROLE_IT_MEMBER" />
		<intercept-url pattern="/(.)+/Special\:Admin(.)*" access="ROLE_SYSADMIN" />
		<intercept-url pattern="/(.)+/Special\:Edit(.)*" access="ROLE_EDIT_EXISTING,ROLE_EDIT_NEW" />
		...
		<intercept-url pattern="/(.)+" access="ROLE_VIEW" />
	</http>

Note that in the above example, ALL intercept-url patterns currently in the /WEB-INF/applicationContext-security.xml file must be converted to regular expressions. See the Spring Security reference guide for further details.

LDAP / CAS / OpenID[edit]

To enable LDAP or another authentication provider, remove or comment out the following section of the /WEB-INF/applicationContext-security.xml file:

  • Note: comment out the whole section only if you intend to use LDAP for authentication and the retrieval of roles. If you plan to leave user roles in the wiki database the two lines that begin with <b:bean must not be commented out.

<authentication-provider user-service-ref="jamWikiAuthenticationDao">
	<password-encoder ref="jamwikiPasswordEncoder" />
</authentication-provider>
<b:bean id="jamWikiAuthenticationDao" class="org.jamwiki.authentication.JAMWikiDaoImpl" />
<b:bean id="jamwikiPasswordEncoder" class="org.jamwiki.authentication.JAMWikiPasswordEncoder" />

This section should then be replaced with the Spring Security configuration elements appropriate for the authentication system that is being integrated with. Use the following section only if you intend to store/retrieve your wiki roles in LDAP.
For example, a basic LDAP integration can be set up using:


<ldap-server id="ldapServer" url="ldap://192.168.1.100/dc=mycompany,dc=com" port="389" manager-dn="cn=admin,dc=mycompany,dc=de" manager-password="mypasswd"/>
<ldap-authentication-provider server-ref="ldapServer" group-search-filter="member={0}" group-search-base="ou=groups" user-dn-pattern="uid={0},ou=people" />
<authentication-provider>
	<ldap-user-service server-ref="ldapServer" group-search-filter="member={0}" group-search-base="ou=groups" user-search-filter="uid={0}" user-search-base="ou=people" />
</authentication-provider>

Full configuration details for LDAP, CAS authentication, Open ID or other systems can be found in the Spring Security reference guide. Note that the custom jamwikiPostAuthenticationFilter SHOULD NOT be disabled when integrating with these systems as it is required to ensure that users authenticated via LDAP or another system will still have the proper JAMWiki database user records created. Without this filter JAMWiki will not create the required wiki user records and various database foreign key constraints will fail, resulting in errors.

By default JAMWiki will limit patterns that can be used for logins to letters, numbers, and the underscore character. If an LDAP system contains logins that utilize other characters then JAMWiki can be modified to allow these logins by modifying the pattern-login-valid in the /WEB-INF/classes/jamwiki.properties file. This property is not modifiable via Special:Admin due to the fact that entering an invalid pattern can cause wiki errors.

LDAP authentication with database roles[edit]

In order to get Spring Security to authenticate via LDAP, you have to setup the LDAP authenticator similar to the provided example in the config file. However, using this method, all the roles for a user are pulled from their LDAP group membership. This causes lots of issues with authorization in JamWiki due to hard-coded role strings in the JamWiki code (see org.jamwiki.servlets.ServletUtil...specifically the "isEditable" method).

It is possible to authenticate the user using LDAP bind authentication, but pull roles from the JamWiki database but it requires a little tweaking to the Spring Security configuration:

<authentication-manager alias="authenticationManager">
	<authentication-provider ref="ldapAuthProvider" user-service-ref="jamWikiAuthenticationDao" />
</authentication-manager>

<b:bean id="ldapAuthProvider" class="org.springframework.security.ldap.authentication.LdapAuthenticationProvider">
	<b:constructor-arg><b:ref bean="ldapAuthenticator"/></b:constructor-arg>
	<b:constructor-arg><b:ref bean="ldapAuthoritiesPopulator"/></b:constructor-arg>
</b:bean>
<b:bean id="ldapAuthenticator" class="org.springframework.security.ldap.authentication.BindAuthenticator">
	<b:constructor-arg><b:ref bean="ldapContextSource"/></b:constructor-arg>
	<b:property name="userSearch" ref="ldapUserSearch" />
</b:bean>
<b:bean id="ldapAuthoritiesPopulator" class="org.springframework.security.ldap.authentication.UserDetailsServiceLdapAuthoritiesPopulator">
	<b:constructor-arg><b:ref bean="jamWikiAuthenticationDao"/></b:constructor-arg>
</b:bean>
<b:bean id="ldapContextSource" class="org.springframework.ldap.core.support.LdapContextSource">
	<b:property name="url" value="ldap://192.168.1.100:389" />
	<b:property name="userDn" value="cn=admin,ou=groups,dc=mycompany,dc=de" />
	<b:property name="password" value="mypasswd" />
	<b:property name="referral" value="follow" />
</b:bean>
<b:bean id="ldapUserSearch" class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
	<b:constructor-arg><b:value>dc=mycompany,dc=de</b:value></b:constructor-arg>
	<b:constructor-arg><b:value>samAccountName={0}</b:value></b:constructor-arg>
	<b:constructor-arg><b:ref bean="ldapContextSource"/></b:constructor-arg>
</b:bean>

If the above raises exception like "Caused by: org.springframework.beans.factory.parsing.BeanDefinitionParsingException: Configuration problem: authentication-provider element cannot be used with other attributes when using 'ref' attribute" (on Glassfish server), try to use another code (example for ldap on ActiveDirectory server)

	<authentication-manager alias="authenticationManager">
		<authentication-provider ref="ldapAuthProvider" />
		<authentication-provider user-service-ref="jamWikiAuthenticationDao">
			<password-encoder ref="jamwikiPasswordEncoder" />
		</authentication-provider>
	</authentication-manager>
	<b:bean id="ldapAuthProvider" class="org.springframework.security.ldap.authentication.LdapAuthenticationProvider">
		<b:constructor-arg><b:ref bean="ldapAuthenticator"/></b:constructor-arg>
		<b:constructor-arg><b:ref bean="ldapAuthoritiesPopulator"/></b:constructor-arg>
	</b:bean>
	<b:bean id="ldapAuthenticator" class="org.springframework.security.ldap.authentication.BindAuthenticator">
		<b:constructor-arg><b:ref bean="ldapContextSource"/></b:constructor-arg>
		<b:property name="userSearch" ref="ldapUserSearch" />
	</b:bean>
	<b:bean id="ldapAuthoritiesPopulator" class="org.springframework.security.ldap.authentication.UserDetailsServiceLdapAuthoritiesPopulator">
		<b:constructor-arg><b:ref bean="jamWikiAuthenticationDao"/></b:constructor-arg>
	</b:bean>
	<b:bean id="ldapContextSource" class="org.springframework.ldap.core.support.LdapContextSource">
		<b:property name="url" value="ldap://servername:port" />
		<b:property name="base" value="dc=google,dc=com" />
		<b:property name="userDn" value="cn=ldapAdmin,ou=Users,ou=WikiUsers,dc=google,dc=com" />
		<b:property name="password" value="ldapAdminPass" />
		<b:property name="referral" value="follow" />
	</b:bean>
	<b:bean id="ldapUserSearch" class="org.springframework.security.ldap.search.FilterBasedLdapUserSearch">
		<b:constructor-arg><b:value>ou=Users,ou=WikiUsers</b:value></b:constructor-arg>
		<b:constructor-arg><b:value>(&(SAMAccountName={0})(objectClass=user))</b:value></b:constructor-arg>
		<b:constructor-arg><b:ref bean="ldapContextSource"/></b:constructor-arg>
	</b:bean>
	<b:bean id="jamWikiAuthenticationDao" class="org.jamwiki.authentication.JAMWikiDaoImpl" />
	<b:bean id="jamwikiPasswordEncoder" class="org.jamwiki.authentication.JAMWikiPasswordEncoder" />
	<b:bean id="authenticationFailureHandler" class="org.jamwiki.authentication.JAMWikiAuthenticationFailureHandler">
		<b:property name="authenticationFailureUrl" value="/Special:Login?message=error.login" />
	</b:bean>

Importanat moment: you have to register via registration form before login via ldap. Another important moment is that you'll have 2 password logins: as ldap user and as jamwiki user. So if you want to use only ldap password you can update table [jam_users] mannualy for example:

 update [jam_users] set password = '' where username = 'login'

See Also[edit]