##### General Information

- Overview
- Features
- Specification
- Getting Started
- Howto Build Turbine
- Changes

##### Documentation

- Services
  - Assembler Broker Service
  - Avalon Component Service
  - Crypto Service
  - Cache Service
  - Component Service
  - Factory Service
  - Intake Service
  - JSON-RPC Service
  - JSP Service
  - Localization Service
  - MimeType Service
  - Naming Service
  - Parser Service
  - Pool Service
  - Pull Service
  - RunData Service
  - Scheduler Service
  - Security Service
  - Servlet Service
  - Session Service
  - Template Service
  - Torque Security Service
  - Torque Security Service Schema
  - UI Service
  - Unique ID Service
  - Upload Service
  - Velocity Service
  - XML-RPC Service
  - XSLT Service
- Howtos
- Wiki
- JavaDocs

##### Development

- Proposals
- How To Help
- Todo

##### Project Documentation

- Project Information
- Project Reports

##### Apache

- Apache Website
- License
- How the ASF works
- Sponsorship
- Thanks
- Security

## Security Service

The Security Service is for authenticating users and assigning them roles and permissions in groups.

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 Torque Security Service for configuration details.

## Configuration

    # -------------------------------------------------------------------
    #
    #  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

## User Manager

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 service.SecurityService.user.manager 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.

## Security Objects

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:

Object type | Property | Class
--- | --- | ---
User | service.SecurityService.user.class | org.apache.turbine.om.security.TurbineUser
Group | service.SecurityService.group.class | org.apache.turbine.om.security.TurbineGroup
Role | service.SecurityService.role.class | org.apache.turbine.om.security.TurbineRole
Permission | service.SecurityService.permission.class | org.apache.turbine.om.security.TurbinePermission

## Access Control List

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 services.SecurityService.acl.class property in Fulcrum.properties. If you provide a different class here, it must implement the org.apache.fulcrum.security.util.AccessControlList interface.

Warning! In earlier versions of the Security Service, org.apache.fulcrum.security.util.AccessControlList 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 rewrite it, but you must recompile it).