xdocs/services/security-service.xml - turbine-core - Git at Google

 <?xml version="1.0"?>
 <!--
 /*
  * Copyright 2001-2004 The Apache Software Foundation.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
  -->

 <document>

  <properties>
   <title>Turbine Services - Security Service</title>
  </properties>

 <body>

 <section name="Security Service">

 <p>
 The Security Service is for authenticating users and assigning them roles
 and permissions in groups.
 </p>
 <p>
 In Turbine 2.3 a replacement for the default DBSecurityService is
 provided that makes it possible to map the security service onto an
 pre existing user structure and much easier to extend the TurbineUser
 table to include additional columns - see <a
 href="torque-Security-service.html"> Torque Security Service</a> for
 configuration details.
 </p>

 </section>

 <section name="Configuration">

 <source><![CDATA[
 # -------------------------------------------------------------------
 #
 #  S E R V I C E S
 #
 # -------------------------------------------------------------------
 # Classes for Turbine Services should be defined here.
 # Format: services.[name].classname=[implementing class]
 #
 # To specify properties of a service use the following syntax:
 # service.[name].[property]=[value]

 #
 # Here you specify, which Security Service is used. This example
 # uses the Database (DB) Security Service. There is no default.

 services.SecurityService.classname=org.apache.turbine.services.security.db.DBSecurityService
 .
 .
 .

 # -------------------------------------------------------------------
 #
 #  S E C U R I T Y  S E R V I C E
 #
 # -------------------------------------------------------------------

 #
 # This is the class that implements the UserManager interface to
 # manage User objects. Default is the UserManager from the
 # DBSecurityService.
 # Override this setting if you want your User information stored
 # on a different medium (LDAP directory is a good example).
 #
 # Adjust this setting if you change the Setting of the SecurityService class (see above).

 # Default: org.apache.turbine.services.security.db.DBUserManager
 services.SecurityService.user.manager = org.apache.turbine.services.security.db.DBUserManager

 #
 # These are the default classes used by the Security Service to
 # provide User, Group, Role and Permission objects.
 # You want to override this setting only if you want your
 # implementation to provide application specific addtional
 # functionality.
 #
 # For LDAP use:
 # services.SecurityService.user.class=org.apache.turbine.services.security.ldap.LDAPUser
 # LDAP does not yet provide custom Group, User and Role objects so you
 # must use it with the default TurbineGroup, TurbineRole and
 # TurbinePermission objects.
 #
 # Class for User. Default: org.apache.turbine.om.security.TurbineUser
 services.SecurityService.user.class=org.apache.turbine.om.security.TurbineUser
 # Class for Group. Default: org.apache.turbine.om.security.TurbineGroup
 services.SecurityService.group.class=org.apache.turbine.om.security.TurbineGroup
 # Class for Role. Default: org.apache.turbine.om.security.TurbineRole
 services.SecurityService.role.class=org.apache.turbine.om.security.TurbineRole
 # Class for Permission. Default: org.apache.turbine.om.security.TurbinePermission
 services.SecurityService.permission.class=org.apache.turbine.om.security.TurbinePermission

 #
 # This is the class that implements the ACL interface.
 # You want to override this setting only if you want your ACL
 # implementation to provide application specific addtional
 # functionality.
 #

 # Default: org.apache.turbine.util.security.TurbineAccessControlList
 services.SecurityService.acl.class = org.apache.turbine.util.security.TurbineAccessControlList

 #
 # This setting is DBSecurityService specific - this class is consulted for the names
 # of the columns in the users' tables for the purpose of creating join queries.
 # If you use your own User implementation in conjunction with DBSecurityService,
 # it's peer class must implement org.apache.turbine.om.security.peer.UserPeer interface,
 # and you need to specify the name of the peer class here.
 #
 # Default: org.apache.turbine.om.security.peer.TurbineUserPeer
 #
 services.SecurityService.userPeer.class=org.apache.turbine.om.security.peer.TurbineUserPeer

 #
 # This is used by the SecurityService to make the password checking
 # secure. When enabled, passwords are transformed by a one-way
 # function into a sequence of bytes that is base64 encoded.
 # It is impossible to guess the plain-text form of the password
 # from the representation. When user logs in, the entered password
 # is transformed the same way and then compared with stored value.
 #
 # Default: false
 #

 services.SecurityService.secure.passwords=false

 #
 # This property lets you choose what digest algorithm will be used
 # for encrypting passwords. Check documentation of your JRE for
 # available algorithms.
 #
 # Default: SHA
 #

 services.SecurityService.secure.passwords.algorithm=SHA

 # Configuration for the LDAP Security Service implementation

 #services.SecurityService.ldap.security.athentication=simple
 #services.SecurityService.ldap.port=<LDAP PORT>
 #services.SecurityService.ldap.host=<LDAP HOST>
 #services.SecurityService.ldap.admin.username=<ADMIN USERNAME>
 #services.SecurityService.ldap.admin.password=<ADMIN PASSWORD>
 #services.SecurityService.ldap.user.basesearch=<SEARCH PATTERN>
 #services.SecurityService.ldap.user.search.filter=<SEARCH FILTER>
 #services.SecurityService.ldap.dn.attribute=userPrincipalName
 #services.SecurityService.ldap.provider=com.sun.jndi.ldap.LdapCtxFactory

 #
 # This property specifies the type of security authentication
 #
 # Default: simple
 #

 # services.SecurityService.ldap.security.authentication=simple

 #
 # The host name where the LDAP server is listenting.
 #
 # Default: localhost
 #

 # services.SecurityService.ldap.host=localhost

 #
 # The port number where the LDAP server is listenting.
 #
 # Default: 389
 #

 # services.SecurityService.ldap.port=389

 #
 # The user name of the admin user. The admin user should be able to
 # read from the LDAP repository.
 # Characteres '/' are replaced by '=' and '%' are replaced by ','.
 #
 # Default: none
 #

 # services.SecurityService.ldap.admin.username=turbineUserUniqueId/turbine%dc/example%dc/com

 #
 # The password of the admin user.
 #
 # Default: none
 #

 # services.SecurityService.ldap.admin.password=turbine

 #
 # The class name of the ldap provider.
 #
 # Default: com.sun.jndi.ldap.LdapCtxFactory
 #

 # services.SecurityService.ldap.provider=com.sun.jndi.ldap.LdapCtxFactory

 #
 # The directory base to search.
 # '/' are replaced by '=' and '%' are replaced by ','.
 #
 # Default: none
 #

 # services.SecurityService.ldap.basesearch=dc/example%dc/com

 #
 # The unique id. It must be an integer field and it is required only when
 # the users are in LDAP but the groups, roles and permissions are in the
 # Database.
 #
 # services.SecurityService.ldap.user.userid=

 #
 # This property maps the username with an attribute in LDAP.
 #
 # Default: turbineUserUniqueId
 #

 # services.SecurityService.ldap.user.username=turbineUserUniqueId

 #
 # This property maps the firstname with an attribute in LDAP.
 #
 # Default: turbineUserFirstName
 #

 # services.SecurityService.ldap.user.firstname=turbineUserFirstName

 #
 # This property maps the lastname with an attribute in LDAP.
 #
 # Default: turbineUserLastName
 #

 # services.SecurityService.ldap.user.lastname=turbineUserLastName

 #
 # This property maps the email with an attribute in LDAP.
 #
 # Default: turbineUserMailAddress
 #

 # services.SecurityService.ldap.user.email=turbineUserMailAddress

 #
 # This property maps the userPassword with an attribute in LDAP.
 #
 # Default: none
 #

 # services.SecurityService.ldap.user.password=userPassword


 ]]></source>

 </section>

 <section name="User Manager">

 <p>
 To access user specific data and information, each Security Service
 must provide an UserManager class. It is service specific and must be
 configured in TurbineResource.properties with the
 <i>service.SecurityService.user.manager</i> property. The UserManager
 allows access to various properties of an Turbine User object, can
 change password, authenticate users to the Security service and
 manages the Turbine user objects.
 </p>

 </section>

 <section name="Security Objects">
 <p>
 The Security Service allows you to configure the various
 objects used to implement the User, Group, Role and Permission
 interfaces. These objects are typically service specific, so you
 should consult the documentation to the Security Service
 implementation, which objects should be used. The default are the
 object classes from the DB Security Service:

 <table>
 <tr>
 <th>Object type</th>
 <th>Property</th>
 <th>Class</th>
 </tr>
 <tr>
 <td>User</td>
 <td>service.SecurityService.user.class</td>
 <td>org.apache.turbine.om.security.TurbineUser</td>
 </tr>
 <tr>
 <td>Group</td>
 <td>service.SecurityService.group.class</td>
 <td>org.apache.turbine.om.security.TurbineGroup</td>
 </tr>
 <tr>
 <td>Role</td>
 <td>service.SecurityService.role.class</td>
 <td>org.apache.turbine.om.security.TurbineRole</td>
 </tr>
 <tr>
 <td>Permission</td>
 <td>service.SecurityService.permission.class</td>
 <td>org.apache.turbine.om.security.TurbinePermission</td>
 </tr>
 </table>
 </p>
 </section>

 <section name="Access Control List">
 <p>
 The Fulcrum security system is built on Access Control Lists
 (ACL). There is a default implementation included with the security
 service. If, for any reason, you need a different ACL implementation,
 you can change it with the <i>services.SecurityService.acl.class</i>
 property in Fulcrum.properties. If you provide a different class here,
 it must implement the
 <i>org.apache.fulcrum.security.util.AccessControlList</i> interface.
 </p>

 <p>
 Warning! In earlier versions of the Security Service,
 <i>org.apache.fulcrum.security.util.AccessControlList</i> was not an
 interface but a class and the implementation wasn't configurable. If
 you upgrade to this version of Fulcrum from an earlier version and get
 "IncompatibleClassChange" exceptions regarding to the
 AccessControlList class, then you need to recompile your application
 (there is no need to <b>rewrite</b> it, but you must <b>recompile</b>
 it).
 </p>

 </section>
 </body>
 </document>
	<?xml version="1.0"?>
	<!--
	/*
	* Copyright 2001-2004 The Apache Software Foundation.
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/
	-->

	<document>

	<properties>
	<title>Turbine Services - Security Service</title>
	</properties>

	<body>

	<section name="Security Service">

	<p>
	The Security Service is for authenticating users and assigning them roles
	and permissions in groups.
	</p>
	<p>
	In Turbine 2.3 a replacement for the default DBSecurityService is
	provided that makes it possible to map the security service onto an
	pre existing user structure and much easier to extend the TurbineUser
	table to include additional columns - see <a
	href="torque-Security-service.html"> Torque Security Service</a> for
	configuration details.
	</p>

	</section>

	<section name="Configuration">

	<source><![CDATA[
	# -------------------------------------------------------------------
	#
	# S E R V I C E S
	#
	# -------------------------------------------------------------------
	# Classes for Turbine Services should be defined here.
	# Format: services.[name].classname=[implementing class]
	#
	# To specify properties of a service use the following syntax:
	# service.[name].[property]=[value]

	#
	# Here you specify, which Security Service is used. This example
	# uses the Database (DB) Security Service. There is no default.

	services.SecurityService.classname=org.apache.turbine.services.security.db.DBSecurityService
	.
	.
	.

	# -------------------------------------------------------------------
	#
	# S E C U R I T Y S E R V I C E
	#
	# -------------------------------------------------------------------

	#
	# This is the class that implements the UserManager interface to
	# manage User objects. Default is the UserManager from the
	# DBSecurityService.
	# Override this setting if you want your User information stored
	# on a different medium (LDAP directory is a good example).
	#
	# Adjust this setting if you change the Setting of the SecurityService class (see above).

	# Default: org.apache.turbine.services.security.db.DBUserManager
	services.SecurityService.user.manager = org.apache.turbine.services.security.db.DBUserManager

	#
	# These are the default classes used by the Security Service to
	# provide User, Group, Role and Permission objects.
	# You want to override this setting only if you want your
	# implementation to provide application specific addtional
	# functionality.
	#
	# For LDAP use:
	# services.SecurityService.user.class=org.apache.turbine.services.security.ldap.LDAPUser
	# LDAP does not yet provide custom Group, User and Role objects so you
	# must use it with the default TurbineGroup, TurbineRole and
	# TurbinePermission objects.
	#
	# Class for User. Default: org.apache.turbine.om.security.TurbineUser
	services.SecurityService.user.class=org.apache.turbine.om.security.TurbineUser
	# Class for Group. Default: org.apache.turbine.om.security.TurbineGroup
	services.SecurityService.group.class=org.apache.turbine.om.security.TurbineGroup
	# Class for Role. Default: org.apache.turbine.om.security.TurbineRole
	services.SecurityService.role.class=org.apache.turbine.om.security.TurbineRole
	# Class for Permission. Default: org.apache.turbine.om.security.TurbinePermission
	services.SecurityService.permission.class=org.apache.turbine.om.security.TurbinePermission

	#
	# This is the class that implements the ACL interface.
	# You want to override this setting only if you want your ACL
	# implementation to provide application specific addtional
	# functionality.
	#

	# Default: org.apache.turbine.util.security.TurbineAccessControlList
	services.SecurityService.acl.class = org.apache.turbine.util.security.TurbineAccessControlList

	#
	# This setting is DBSecurityService specific - this class is consulted for the names
	# of the columns in the users' tables for the purpose of creating join queries.
	# If you use your own User implementation in conjunction with DBSecurityService,
	# it's peer class must implement org.apache.turbine.om.security.peer.UserPeer interface,
	# and you need to specify the name of the peer class here.
	#
	# Default: org.apache.turbine.om.security.peer.TurbineUserPeer
	#
	services.SecurityService.userPeer.class=org.apache.turbine.om.security.peer.TurbineUserPeer

	#
	# This is used by the SecurityService to make the password checking
	# secure. When enabled, passwords are transformed by a one-way
	# function into a sequence of bytes that is base64 encoded.
	# It is impossible to guess the plain-text form of the password
	# from the representation. When user logs in, the entered password
	# is transformed the same way and then compared with stored value.
	#
	# Default: false
	#

	services.SecurityService.secure.passwords=false

	#
	# This property lets you choose what digest algorithm will be used
	# for encrypting passwords. Check documentation of your JRE for
	# available algorithms.
	#
	# Default: SHA
	#

	services.SecurityService.secure.passwords.algorithm=SHA

	# Configuration for the LDAP Security Service implementation

	#services.SecurityService.ldap.security.athentication=simple
	#services.SecurityService.ldap.port=<LDAP PORT>
	#services.SecurityService.ldap.host=<LDAP HOST>
	#services.SecurityService.ldap.admin.username=<ADMIN USERNAME>
	#services.SecurityService.ldap.admin.password=<ADMIN PASSWORD>
	#services.SecurityService.ldap.user.basesearch=<SEARCH PATTERN>
	#services.SecurityService.ldap.user.search.filter=<SEARCH FILTER>
	#services.SecurityService.ldap.dn.attribute=userPrincipalName
	#services.SecurityService.ldap.provider=com.sun.jndi.ldap.LdapCtxFactory

	#
	# This property specifies the type of security authentication
	#
	# Default: simple
	#

	# services.SecurityService.ldap.security.authentication=simple

	#
	# The host name where the LDAP server is listenting.
	#
	# Default: localhost
	#

	# services.SecurityService.ldap.host=localhost

	#
	# The port number where the LDAP server is listenting.
	#
	# Default: 389
	#

	# services.SecurityService.ldap.port=389

	#
	# The user name of the admin user. The admin user should be able to
	# read from the LDAP repository.
	# Characteres '/' are replaced by '=' and '%' are replaced by ','.
	#
	# Default: none
	#

	# services.SecurityService.ldap.admin.username=turbineUserUniqueId/turbine%dc/example%dc/com

	#
	# The password of the admin user.
	#
	# Default: none
	#

	# services.SecurityService.ldap.admin.password=turbine

	#
	# The class name of the ldap provider.
	#
	# Default: com.sun.jndi.ldap.LdapCtxFactory
	#

	# services.SecurityService.ldap.provider=com.sun.jndi.ldap.LdapCtxFactory

	#
	# The directory base to search.
	# '/' are replaced by '=' and '%' are replaced by ','.
	#
	# Default: none
	#

	# services.SecurityService.ldap.basesearch=dc/example%dc/com

	#
	# The unique id. It must be an integer field and it is required only when
	# the users are in LDAP but the groups, roles and permissions are in the
	# Database.
	#
	# services.SecurityService.ldap.user.userid=

	#
	# This property maps the username with an attribute in LDAP.
	#
	# Default: turbineUserUniqueId
	#

	# services.SecurityService.ldap.user.username=turbineUserUniqueId

	#
	# This property maps the firstname with an attribute in LDAP.
	#
	# Default: turbineUserFirstName
	#

	# services.SecurityService.ldap.user.firstname=turbineUserFirstName

	#
	# This property maps the lastname with an attribute in LDAP.
	#
	# Default: turbineUserLastName
	#

	# services.SecurityService.ldap.user.lastname=turbineUserLastName

	#
	# This property maps the email with an attribute in LDAP.
	#
	# Default: turbineUserMailAddress
	#

	# services.SecurityService.ldap.user.email=turbineUserMailAddress

	#
	# This property maps the userPassword with an attribute in LDAP.
	#
	# Default: none
	#

	# services.SecurityService.ldap.user.password=userPassword


	]]></source>

	</section>

	<section name="User Manager">

	<p>
	To access user specific data and information, each Security Service
	must provide an UserManager class. It is service specific and must be
	configured in TurbineResource.properties with the
	<i>service.SecurityService.user.manager</i> property. The UserManager
	allows access to various properties of an Turbine User object, can
	change password, authenticate users to the Security service and
	manages the Turbine user objects.
	</p>

	</section>

	<section name="Security Objects">
	<p>
	The Security Service allows you to configure the various
	objects used to implement the User, Group, Role and Permission
	interfaces. These objects are typically service specific, so you
	should consult the documentation to the Security Service
	implementation, which objects should be used. The default are the
	object classes from the DB Security Service:

	<table>
	<tr>
	<th>Object type</th>
	<th>Property</th>
	<th>Class</th>
	</tr>
	<tr>
	<td>User</td>
	<td>service.SecurityService.user.class</td>
	<td>org.apache.turbine.om.security.TurbineUser</td>
	</tr>
	<tr>
	<td>Group</td>
	<td>service.SecurityService.group.class</td>
	<td>org.apache.turbine.om.security.TurbineGroup</td>
	</tr>
	<tr>
	<td>Role</td>
	<td>service.SecurityService.role.class</td>
	<td>org.apache.turbine.om.security.TurbineRole</td>
	</tr>
	<tr>
	<td>Permission</td>
	<td>service.SecurityService.permission.class</td>
	<td>org.apache.turbine.om.security.TurbinePermission</td>
	</tr>
	</table>
	</p>
	</section>

	<section name="Access Control List">
	<p>
	The Fulcrum security system is built on Access Control Lists
	(ACL). There is a default implementation included with the security
	service. If, for any reason, you need a different ACL implementation,
	you can change it with the <i>services.SecurityService.acl.class</i>
	property in Fulcrum.properties. If you provide a different class here,
	it must implement the
	<i>org.apache.fulcrum.security.util.AccessControlList</i> interface.
	</p>

	<p>
	Warning! In earlier versions of the Security Service,
	<i>org.apache.fulcrum.security.util.AccessControlList</i> was not an
	interface but a class and the implementation wasn't configurable. If
	you upgrade to this version of Fulcrum from an earlier version and get
	"IncompatibleClassChange" exceptions regarding to the
	AccessControlList class, then you need to recompile your application
	(there is no need to <b>rewrite</b> it, but you must <b>recompile</b>
	it).
	</p>

	</section>
	</body>
	</document>