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

 <?xml version="1.0"?>

 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you 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>
   <author email="jvanzyl@apache.org">Jason van Zyl</author>
   <author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
   <author email="tv@apache.org">Thomas Vandahl</author>
  </properties>

 <body>

 <section name="Security Service">

 <p>
 The Security Service is for authenticating users and assigning them roles
 and permissions in groups. Different implementations are available, which
 can be deployed in dependence of your application needs:
   <ul>
     <li>DBSecurityService (deprecated as of Turbine 2.3.3)</li>
     <li>TorqueSecurityService (recommended default)</li>
     <li>LDAPSecurityService</li>
   </ul>
 </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. The LDAPSecurityService allows to attach to an
 existing legacy server for authentication. Groups, roles and permissions
 can be provided by the TorqueSecurityService, for example. See the
 <a href="ldap-security-service.html">LDAP Security Service</a> for an
 example on how to attach Turbine to Active Directory.
 </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 Torque Security Service. There is no default.

 services.SecurityService.classname=org.apache.turbine.services.security.torque.TorqueSecurityService
 .
 .
 .

 # -------------------------------------------------------------------
 #
 #  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.torque.TorqueUserManager
 services.SecurityService.user.manager = org.apache.turbine.services.security.torque.TorqueUserManager

 #
 # 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 additional
 # 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 TorqueGroup, TorqueRole and
 # TorquePermission objects.
 #
 # Class for User. Default: org.apache.turbine.services.security.torque.TorqueUser
 services.SecurityService.user.class=org.apache.turbine.services.security.torque.TorqueUser
 # Class for Group. Default: org.apache.turbine.services.security.torque.TorqueGroup
 services.SecurityService.group.class=org.apache.turbine.services.security.torque.TorqueGroup
 # Class for Role. Default: org.apache.turbine.services.security.torque.TorqueRole
 services.SecurityService.role.class=org.apache.turbine.services.security.torque.TorqueRole
 # Class for Permission. Default: org.apache.turbine.services.security.torque.TorquePermission
 services.SecurityService.permission.class=org.apache.turbine.services.security.torque.TorquePermission

 #
 # 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 additional
 # functionality.
 #

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

 #
 # 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.authentication=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 listening.
 #
 # Default: localhost
 #

 # services.SecurityService.ldap.host=localhost

 #
 # The port number where the LDAP server is listening.
 #
 # 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.
 # Characters '/' 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 Torque 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.services.security.torque.TorqueUser</td>
 </tr>
 <tr>
 <td>Group</td>
 <td>service.SecurityService.group.class</td>
 <td>org.apache.turbine.services.security.torque.TorqueGroup</td>
 </tr>
 <tr>
 <td>Role</td>
 <td>service.SecurityService.role.class</td>
 <td>org.apache.turbine.services.security.torque.TorqueRole</td>
 </tr>
 <tr>
 <td>Permission</td>
 <td>service.SecurityService.permission.class</td>
 <td>org.apache.turbine.services.security.torque.TorquePermission</td>
 </tr>
 </table>
 </p>
 </section>

 <section name="Access Control List">
 <p>
 The Turbine 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 TurbineResources.properties. If you provide a different class here,
 it must implement the
 <i>org.apache.turbine.util.security.AccessControlList</i> interface.
 </p>

 <p>
 Warning! In earlier versions of the Security Service,
 <i>org.apache.turbine.util.security.AccessControlList</i> was not an
 interface but a class and the implementation wasn't configurable. If
 you upgrade to this version of Turbine 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"?>

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you 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>
	<author email="jvanzyl@apache.org">Jason van Zyl</author>
	<author email="hps@intermeta.de">Henning P. Schmiedehausen</author>
	<author email="tv@apache.org">Thomas Vandahl</author>
	</properties>

	<body>

	<section name="Security Service">

	<p>
	The Security Service is for authenticating users and assigning them roles
	and permissions in groups. Different implementations are available, which
	can be deployed in dependence of your application needs:
	<ul>
	<li>DBSecurityService (deprecated as of Turbine 2.3.3)</li>
	<li>TorqueSecurityService (recommended default)</li>
	<li>LDAPSecurityService</li>
	</ul>
	</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. The LDAPSecurityService allows to attach to an
	existing legacy server for authentication. Groups, roles and permissions
	can be provided by the TorqueSecurityService, for example. See the
	<a href="ldap-security-service.html">LDAP Security Service</a> for an
	example on how to attach Turbine to Active Directory.
	</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 Torque Security Service. There is no default.

	services.SecurityService.classname=org.apache.turbine.services.security.torque.TorqueSecurityService
	.
	.
	.

	# -------------------------------------------------------------------
	#
	# 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.torque.TorqueUserManager
	services.SecurityService.user.manager = org.apache.turbine.services.security.torque.TorqueUserManager

	#
	# 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 additional
	# 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 TorqueGroup, TorqueRole and
	# TorquePermission objects.
	#
	# Class for User. Default: org.apache.turbine.services.security.torque.TorqueUser
	services.SecurityService.user.class=org.apache.turbine.services.security.torque.TorqueUser
	# Class for Group. Default: org.apache.turbine.services.security.torque.TorqueGroup
	services.SecurityService.group.class=org.apache.turbine.services.security.torque.TorqueGroup
	# Class for Role. Default: org.apache.turbine.services.security.torque.TorqueRole
	services.SecurityService.role.class=org.apache.turbine.services.security.torque.TorqueRole
	# Class for Permission. Default: org.apache.turbine.services.security.torque.TorquePermission
	services.SecurityService.permission.class=org.apache.turbine.services.security.torque.TorquePermission

	#
	# 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 additional
	# functionality.
	#

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

	#
	# 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.authentication=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 listening.
	#
	# Default: localhost
	#

	# services.SecurityService.ldap.host=localhost

	#
	# The port number where the LDAP server is listening.
	#
	# 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.
	# Characters '/' 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 Torque 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.services.security.torque.TorqueUser</td>
	</tr>
	<tr>
	<td>Group</td>
	<td>service.SecurityService.group.class</td>
	<td>org.apache.turbine.services.security.torque.TorqueGroup</td>
	</tr>
	<tr>
	<td>Role</td>
	<td>service.SecurityService.role.class</td>
	<td>org.apache.turbine.services.security.torque.TorqueRole</td>
	</tr>
	<tr>
	<td>Permission</td>
	<td>service.SecurityService.permission.class</td>
	<td>org.apache.turbine.services.security.torque.TorquePermission</td>
	</tr>
	</table>
	</p>
	</section>

	<section name="Access Control List">
	<p>
	The Turbine 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 TurbineResources.properties. If you provide a different class here,
	it must implement the
	<i>org.apache.turbine.util.security.AccessControlList</i> interface.
	</p>

	<p>
	Warning! In earlier versions of the Security Service,
	<i>org.apache.turbine.util.security.AccessControlList</i> was not an
	interface but a class and the implementation wasn't configurable. If
	you upgrade to this version of Turbine 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>