src/docbkx/security.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter version="5.0" xml:id="security" xmlns="http://docbook.org/ns/docbook"
   3          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   4          xmlns:xs="http://www.w3.org/2001/XMLSchema"
   5          xmlns:xlink="http://www.w3.org/1999/xlink"
   6          xmlns:xi="http://www.w3.org/2001/XInclude"
   7          xmlns:ns5="http://www.w3.org/1999/xhtml"
   8          xmlns:ns4="http://www.w3.org/2000/svg"
   9          xmlns:ns3="http://www.w3.org/1998/Math/MathML"
  10          xmlns:ns="http://docbook.org/ns/docbook">
  11   <info>
  12     <title>Security and Identity within the CDM Library</title>
  13   </info>
  14
  15   <section>
  16     <para>The CDM Library uses the Spring Security sub-project as the basis of
  17     its security implementation. The best place to get information on using
  18     Spring Security is the <link
  19     xlink:href="http://static.springsource.org/spring-security/site/index.html">project
  20     website</link>.</para>
  21
  22     <para>Spring Security is based around a non-intrusive and non-invasive
  23     architecture that can be configured as needed by a particular application.
  24     The CDM Java Library does not have any restricted or protected methods by
  25     default - it is likely that each application based on the CDM will wish to
  26     protect services in a different way. The CDM service layer does provide a
  27     number of classes that make it straightforward to set up.</para>
  28
  29     <para>In addition to providing generic components for authentication and
  30     authorization, Spring Security provides a number of components that can be
  31     used by web applications. Details on authentication and authorization
  32     concepts applied to web applications can be found in the documentation for
  33     the <package>cdmlib-remote</package> package.</para>
  34
  35     <section>
  36       <info>
  37         <title>Identity</title>
  38       </info>
  39
  40       <para>Identity in Spring Security is based around the
  41       <interfacename>UserDetails</interfacename> interface, that provides
  42       access to the principal's username, password, granted authorities and
  43       other details. The CDM provides the <classname>User</classname> class
  44       that implements this interface. In addition, it provides implementations
  45       of the <interfacename>GrantedAuthority</interfacename> and a
  46       <classname>Group</classname> class to allow group authorities
  47       (permissions that belong to a group of individuals rather than belonging
  48       to a single <classname>User</classname>). Creation of new user accounts,
  49       manipulation of account details, permissions, and group membership is
  50       achieved through an implementation of
  51       <interfacename>IUserService</interfacename> provided by the
  52       library.</para>
  53
  54       <para>The CDM provides some basic auditing functionality by storing the
  55       user account and timestamp each time an object is modified (and a
  56       transaction is comitted). The user details are retrieved from the
  57       <classname>SecurityContextHolder</classname> provided by Spring
  58       Security. If authentication is set up (see below) and the user is logged
  59       in, then this data will be present automatically in the
  60       <classname>SecurityContext</classname>. In the case of applications that
  61       do not use Spring Security, the <classname>User</classname> object must
  62       be placed into the <classname>SecurityContext</classname> explicitly for
  63       the user details to be recorded in this way.</para>
  64     </section>
  65
  66     <section>
  67       <info>
  68         <title>Authentication</title>
  69       </info>
  70
  71       <para>To enable authentication within your application, a small number
  72       of additional beans need to be added to the application context, thus
  73       (note the use of the <emphasis>security</emphasis> spring-security
  74       namespace):</para>
  75
  76       <programlisting>&lt;security:authentication-manager alias="authenticationManager"/&gt;
  77
  78 &lt;bean id="daoAuthenticationProvider" class="org.springframework.security.providers.dao.DaoAuthenticationProvider"&gt;
  79   &lt;security:custom-authentication-provider/&gt;
  80   &lt;property name="userDetailsService" ref="userService"/&gt;
  81   &lt;property name="saltSource" ref="saltSource"/&gt;
  82   &lt;property name="passwordEncoder" ref="passwordEncoder"/&gt;
  83 &lt;/bean&gt;
  84
  85 &lt;bean id="passwordEncoder" class="org.springframework.security.providers.encoding.Md5PasswordEncoder"/&gt;
  86
  87 &lt;bean id="saltSource" class="org.springframework.security.providers.dao.salt.ReflectionSaltSource"&gt;
  88   &lt;property name="userPropertyToUse" value="getUsername"/&gt;
  89 &lt;/bean&gt;</programlisting>
  90
  91       <para>In the case of web applications, application developers will
  92       probably want to authenticate users transparently, using the servlet
  93       filter provided by spring security. For desktop applications, you can
  94       also authenticate a user programatically:</para>
  95
  96       <programlisting>UsernamePasswordAuthenticationToken token = new UsernamePasswordAuthenticationToken("<emphasis>username</emphasis>","<emphasis>password</emphasis>");
  97 authenticationManager.authenticate(token);</programlisting>
  98     </section>
  99
 100     <section>
 101       <info>
 102         <title>Authorization</title>
 103       </info>
 104
 105       <para>As with authentication, web applications based upon the CDM may
 106       find the standard methods provided by Spring Security or protecting URLs
 107       to be sufficient in most cases. To protect service methods, or to secure
 108       desktop applications, developers can also use global method security by
 109       specifying a pointcut expression that matches the service and method
 110       that they wish to protect, and a granted authority that is allowed to
 111       access the method thus:</para>
 112
 113       <programlisting>&lt;security:global-method-security&gt;
 114   &lt;security:protect-pointcut expression="execution(* eu.etaxonomy.cdm.api.service.UserService.changePasswordForUser(..))" access="ROLE_ADMINISTRATE"/&gt;
 115 &lt;/security:global-method-security&gt;</programlisting>
 116     </section>
 117   </section>
 118 </chapter>