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>
  </properties>

 <body>

 <section name="Security Service">

 <p>
 The Security Service is for authenticating users and assigning them roles
 and permissions in groups.
 </p>
 <p>
 Turbine uses the <a href="/fulcrum//fulcrum-security-api/index.html">Fulcrum Security API</a>
 to provide security features to applications. In the Fulcrum repository,
 implementations exist for
 <a href="/fulcrum/fulcrum-security-hibernate/index.html">Hibernate</a>,
 <a href="/fulcrum/fulcrum-security-torque/index.html">Torque</a>
 and <a href="/fulcrum/fulcrum-security-nt/index.html">NTLM</a>.
 </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 Fulcrum Security Service. There is no default.

 services.SecurityService.classname=org.apache.turbine.services.security.DefaultSecurityService
 .
 .
 .

 # -------------------------------------------------------------------
 #
 #  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 PassiveUserManager.
 #
 # 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.passive.PassiveUserManager
 services.SecurityService.user.manager = org.apache.turbine.services.security.DefaultUserManager

 # Default: org.apache.turbine.om.security.DefaultUserImpl
 #services.SecurityService.wrapper.class =

 ]]></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.

 If you have have additional columns in the User (e.g. TurbineUser) table, you get them handled properly (persisting and reading) this way:

 - create a non default wrapper.class. This class should extend DefaultUserImpl and override or add the required properties.

 - best practice would be to provide an interface to communicate on same standards between this wrapper.class and the backend ORM-class (e.g generated TurbineTorqueUser class). Otherwise you could use your ORM class.

  The ORM class is e.g. fetched from the default implementation of the Fulcrum User Manager (org.apache.fulcrum.security.UserManager) (as configured in componentConfiguration.xml userManager->className) and the Turbine User Manager gets it by fetching it first from the Fulcrum User Manager (= umDelegate) and then setting this class as userDelegate in the wrapper class.

 </p>

 </section>

 <section name="Using Fulcrum Security">
 <p>
 The actual implementations for the different Fulcrum services that
 define the behavior of the security service are configured in the
 files <code>roleConfiguration.xml</code> and
 <code>componentConfiguration.xml</code>. All of them can be extended
 and/or modified to meet your requirements. The following example shows
 the sections for the
 <a href="/fulcrum/fulcrum-security-torque/index.html">Torque</a>
 implementation, using the Turbine security model.

 <subsection name="Dependencies">
 Turbine 4.0 does not depend on a particular Fulcrum Security
 implementation. To use the Torque-flavor, you need to specify
 the dependency explicitly in your POM:
 <source><![CDATA[
 <dependency>
   <groupId>org.apache.fulcrum</groupId>
   <artifactId>fulcrum-security-torque</artifactId>
   <version>1.1.0</version>
 </dependency>
 ]]></source>
 </subsection>
 <subsection name="roleConfiguration.xml">
 <source><![CDATA[
 <role
     name="org.apache.torque.avalon.Torque"
     shorthand="torqueService"
     default-class="org.apache.torque.avalon.TorqueComponent"
     early-init="true" />
 <role
     name="org.apache.fulcrum.security.SecurityService"
     shorthand="securityService"
     default-class="org.apache.fulcrum.security.BaseSecurityService"/>
 <role
     name="org.apache.fulcrum.security.UserManager"
     shorthand="userManager"
     early-init="true"
     default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineUserManagerImpl"/>
 <role
     name="org.apache.fulcrum.security.GroupManager"
     shorthand="groupManager"
     default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineGroupManagerImpl"/>
 <role
     name="org.apache.fulcrum.security.RoleManager"
     shorthand="roleManager"
     default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineRoleManagerImpl"/>
 <role
     name="org.apache.fulcrum.security.PermissionManager"
     shorthand="permissionManager"
     default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbinePermissionManagerImpl"/>
 <role
     name="org.apache.fulcrum.security.ModelManager"
     shorthand="modelManager"
     default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineModelManagerImpl"/>
 <role
     name="org.apache.fulcrum.security.authenticator.Authenticator"
     shorthand="authenticator"
     default-class="org.apache.fulcrum.security.authenticator.TextMatchAuthenticator"/>
 <role
     name="org.apache.fulcrum.security.model.ACLFactory"
     shorthand="aclFactory"
     default-class="org.apache.fulcrum.security.model.turbine.TurbineACLFactory"/>
 ]]></source>
 </subsection>

 <subsection name="componentConfiguration.xml">
 <source><![CDATA[
 <securityService/>
 <authenticator/>
 <modelManager/>
 <aclFactory/>

 <userManager>
     <className>org.apache.fulcrum.security.torque.om.TorqueTurbineUser</className>
 </userManager>
 <groupManager>
     <className>org.apache.fulcrum.security.torque.om.TorqueTurbineGroup</className>
 </groupManager>
 <roleManager>
     <className>org.apache.fulcrum.security.torque.om.TorqueTurbineRole</className>
 </roleManager>
 <permissionManager>
     <className>org.apache.fulcrum.security.torque.om.TorqueTurbinePermission</className>
 </permissionManager>

 <torqueService>
     <configfile>WEB-INF/conf/Torque.properties</configfile>
 </torqueService>
 ]]></source>
 </subsection>
 </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>
	</properties>

	<body>

	<section name="Security Service">

	<p>
	The Security Service is for authenticating users and assigning them roles
	and permissions in groups.
	</p>
	<p>
	Turbine uses the <a href="/fulcrum//fulcrum-security-api/index.html">Fulcrum Security API</a>
	to provide security features to applications. In the Fulcrum repository,
	implementations exist for
	<a href="/fulcrum/fulcrum-security-hibernate/index.html">Hibernate</a>,
	<a href="/fulcrum/fulcrum-security-torque/index.html">Torque</a>
	and <a href="/fulcrum/fulcrum-security-nt/index.html">NTLM</a>.
	</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 Fulcrum Security Service. There is no default.

	services.SecurityService.classname=org.apache.turbine.services.security.DefaultSecurityService
	.
	.
	.

	# -------------------------------------------------------------------
	#
	# 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 PassiveUserManager.
	#
	# 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.passive.PassiveUserManager
	services.SecurityService.user.manager = org.apache.turbine.services.security.DefaultUserManager

	# Default: org.apache.turbine.om.security.DefaultUserImpl
	#services.SecurityService.wrapper.class =

	]]></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.

	If you have have additional columns in the User (e.g. TurbineUser) table, you get them handled properly (persisting and reading) this way:

	- create a non default wrapper.class. This class should extend DefaultUserImpl and override or add the required properties.

	- best practice would be to provide an interface to communicate on same standards between this wrapper.class and the backend ORM-class (e.g generated TurbineTorqueUser class). Otherwise you could use your ORM class.

	The ORM class is e.g. fetched from the default implementation of the Fulcrum User Manager (org.apache.fulcrum.security.UserManager) (as configured in componentConfiguration.xml userManager->className) and the Turbine User Manager gets it by fetching it first from the Fulcrum User Manager (= umDelegate) and then setting this class as userDelegate in the wrapper class.

	</p>

	</section>

	<section name="Using Fulcrum Security">
	<p>
	The actual implementations for the different Fulcrum services that
	define the behavior of the security service are configured in the
	files <code>roleConfiguration.xml</code> and
	<code>componentConfiguration.xml</code>. All of them can be extended
	and/or modified to meet your requirements. The following example shows
	the sections for the
	<a href="/fulcrum/fulcrum-security-torque/index.html">Torque</a>
	implementation, using the Turbine security model.

	<subsection name="Dependencies">
	Turbine 4.0 does not depend on a particular Fulcrum Security
	implementation. To use the Torque-flavor, you need to specify
	the dependency explicitly in your POM:
	<source><![CDATA[
	<dependency>
	<groupId>org.apache.fulcrum</groupId>
	<artifactId>fulcrum-security-torque</artifactId>
	<version>1.1.0</version>
	</dependency>
	]]></source>
	</subsection>
	<subsection name="roleConfiguration.xml">
	<source><![CDATA[
	<role
	name="org.apache.torque.avalon.Torque"
	shorthand="torqueService"
	default-class="org.apache.torque.avalon.TorqueComponent"
	early-init="true" />
	<role
	name="org.apache.fulcrum.security.SecurityService"
	shorthand="securityService"
	default-class="org.apache.fulcrum.security.BaseSecurityService"/>
	<role
	name="org.apache.fulcrum.security.UserManager"
	shorthand="userManager"
	early-init="true"
	default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineUserManagerImpl"/>
	<role
	name="org.apache.fulcrum.security.GroupManager"
	shorthand="groupManager"
	default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineGroupManagerImpl"/>
	<role
	name="org.apache.fulcrum.security.RoleManager"
	shorthand="roleManager"
	default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineRoleManagerImpl"/>
	<role
	name="org.apache.fulcrum.security.PermissionManager"
	shorthand="permissionManager"
	default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbinePermissionManagerImpl"/>
	<role
	name="org.apache.fulcrum.security.ModelManager"
	shorthand="modelManager"
	default-class="org.apache.fulcrum.security.torque.turbine.TorqueTurbineModelManagerImpl"/>
	<role
	name="org.apache.fulcrum.security.authenticator.Authenticator"
	shorthand="authenticator"
	default-class="org.apache.fulcrum.security.authenticator.TextMatchAuthenticator"/>
	<role
	name="org.apache.fulcrum.security.model.ACLFactory"
	shorthand="aclFactory"
	default-class="org.apache.fulcrum.security.model.turbine.TurbineACLFactory"/>
	]]></source>
	</subsection>

	<subsection name="componentConfiguration.xml">
	<source><![CDATA[
	<securityService/>
	<authenticator/>
	<modelManager/>
	<aclFactory/>

	<userManager>
	<className>org.apache.fulcrum.security.torque.om.TorqueTurbineUser</className>
	</userManager>
	<groupManager>
	<className>org.apache.fulcrum.security.torque.om.TorqueTurbineGroup</className>
	</groupManager>
	<roleManager>
	<className>org.apache.fulcrum.security.torque.om.TorqueTurbineRole</className>
	</roleManager>
	<permissionManager>
	<className>org.apache.fulcrum.security.torque.om.TorqueTurbinePermission</className>
	</permissionManager>

	<torqueService>
	<configfile>WEB-INF/conf/Torque.properties</configfile>
	</torqueService>
	]]></source>
	</subsection>
	</p>
	</section>
	</body>
	</document>