|
|
@@ -1,6323 +0,0 @@
|
|
|
-<?xml version="1.0" encoding="UTF-8"?>
|
|
|
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
|
-"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
-<!--
|
|
|
- * ========================================================================
|
|
|
- *
|
|
|
- * Copyright 2004 Acegi Technology Pty Limited
|
|
|
- *
|
|
|
- * 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.
|
|
|
- *
|
|
|
- * ========================================================================
|
|
|
--->
|
|
|
-<book>
|
|
|
- <bookinfo>
|
|
|
- <title>Acegi Security</title>
|
|
|
-
|
|
|
- <subtitle>Reference Documentation</subtitle>
|
|
|
-
|
|
|
- <releaseinfo>1.0.4</releaseinfo>
|
|
|
-
|
|
|
- <authorgroup>
|
|
|
- <author>
|
|
|
- <firstname>Ben</firstname>
|
|
|
-
|
|
|
- <surname>Alex</surname>
|
|
|
- </author>
|
|
|
- </authorgroup>
|
|
|
- </bookinfo>
|
|
|
-
|
|
|
- <toc></toc>
|
|
|
-
|
|
|
- <preface id="preface">
|
|
|
- <title>Preface</title>
|
|
|
-
|
|
|
- <para>Acegi Security provides a comprehensive security solution for
|
|
|
- J2EE-based enterprise software applications. As you will discover as you
|
|
|
- venture through this reference guide, we have tried to provide you a
|
|
|
- useful and highly configurable security system.</para>
|
|
|
-
|
|
|
- <para>Security is an ever-moving target, and it's important to pursue a
|
|
|
- comprehensive, system-wide approach. In security circles we encourage you
|
|
|
- to adopt "layers of security", so that each layer tries to be as secure as
|
|
|
- possible in its own right, with successive layers providing additional
|
|
|
- security. The "tighter" the security of each layer, the more robust and
|
|
|
- safe your application will be. At the bottom level you'll need to deal
|
|
|
- with issues such as transport security and system identification, in order
|
|
|
- to mitigate man-in-the-middle attacks. Next you'll generally utilise
|
|
|
- firewalls, perhaps with VPNs or IP security to ensure only authorised
|
|
|
- systems can attempt to connect. In corporate environments you may deploy a
|
|
|
- DMZ to separate public-facing servers from backend database and
|
|
|
- application servers. Your operating system will also play a critical part,
|
|
|
- addressing issues such as running processes as non-privileged users and
|
|
|
- maximising file system security. An operating system will usually also be
|
|
|
- configured with its own firewall. Hopefully somewhere along the way you'll
|
|
|
- be trying to prevent denial of service and brute force attacks against the
|
|
|
- system. An intrusion detection system will also be especially useful for
|
|
|
- monitoring and responding to attacks, with such systems able to take
|
|
|
- protective action such as blocking offending TCP/IP addresses in
|
|
|
- real-time. Moving to the higher layers, your Java Virtual Machine will
|
|
|
- hopefully be configured to minimize the permissions granted to different
|
|
|
- Java types, and then your application will add its own problem
|
|
|
- domain-specific security configuration. Acegi Security makes this latter
|
|
|
- area - application security - much easier.</para>
|
|
|
-
|
|
|
- <para>Of course, you will need to properly address all security layers
|
|
|
- mentioned above, together with managerial factors that encompass every
|
|
|
- layer. A non-exhaustive list of such managerial factors would include
|
|
|
- security bulletin monitoring, patching, personnel vetting, audits, change
|
|
|
- control, engineering management systems, data backup, disaster recovery,
|
|
|
- performance benchmarking, load monitoring, centralised logging, incident
|
|
|
- response procedures etc.</para>
|
|
|
-
|
|
|
- <para>With Acegi Security being focused on helping you with the enterprise
|
|
|
- application security layer, you will find that there are as many different
|
|
|
- requirements as there are business problem domains. A banking application
|
|
|
- has different needs from an ecommerce application. An ecommerce
|
|
|
- application has different needs from a corporate sales force automation
|
|
|
- tool. These custom requirements make application security interesting,
|
|
|
- challenging and rewarding.</para>
|
|
|
-
|
|
|
- <para>This reference guide has been largely restructured for the 1.0.0
|
|
|
- release of Acegi Security. Please read Part I, <link
|
|
|
- linkend="overall-architecture">Overall Architecture</link>, in its
|
|
|
- entirety. The remaining parts of the reference guide are structured in a
|
|
|
- more traditional reference style, designed to be read on an as-required
|
|
|
- basis.</para>
|
|
|
-
|
|
|
- <para>We hope that you find this reference guide useful, and we welcome
|
|
|
- your feedback and <link linkend="jira">suggestions</link>.</para>
|
|
|
-
|
|
|
- <para>Finally, welcome to the Acegi Security <link
|
|
|
- linkend="community">community</link>.</para>
|
|
|
- </preface>
|
|
|
-
|
|
|
- <part id="overall-architecture">
|
|
|
- <title>Overall Architecture</title>
|
|
|
-
|
|
|
- <partintro>
|
|
|
- <para>Like most software, Acegi Security has certain central interfaces,
|
|
|
- classes and conceptual abstractions that are commonly used throughout
|
|
|
- the framework. In this part of the reference guide we will introduce
|
|
|
- Acegi Security, before examining these central elements that are
|
|
|
- necessary to successfully planning and executing an Acegi Security
|
|
|
- integration.</para>
|
|
|
- </partintro>
|
|
|
-
|
|
|
- <chapter id="introduction">
|
|
|
- <title>Introduction</title>
|
|
|
-
|
|
|
- <sect1 id="what-is-acegi-security">
|
|
|
- <title>What is Acegi Security?</title>
|
|
|
-
|
|
|
- <para>Acegi Security provides comprehensive security services for
|
|
|
- J2EE-based enterprise software applications. There is a particular
|
|
|
- emphasis on supporting projects built using The Spring Framework,
|
|
|
- which is the leading J2EE solution for enterprise software
|
|
|
- development. If you're not using Spring for developing enterprise
|
|
|
- applications, we warmly encourage you to take a closer look at it.
|
|
|
- Some familiarity with Spring - and in particular dependency injection
|
|
|
- principles - will help you get up to speed with Acegi Security more
|
|
|
- easily.</para>
|
|
|
-
|
|
|
- <para>People use Acegi Security for many reasons, but most are drawn
|
|
|
- to the project after finding the security features of J2EE's Servlet
|
|
|
- Specification or EJB Specification lack the depth required for typical
|
|
|
- enterprise application scenarios. Whilst mentioning these standards,
|
|
|
- it's important to recognise that they are not portable at a WAR or EAR
|
|
|
- level. Therefore, if you switch server environments, it is typically a
|
|
|
- lot of work to reconfigure your application's security in the new
|
|
|
- target environment. Using Acegi Security overcomes these problems, and
|
|
|
- also brings you dozens of other useful, entirely customisable security
|
|
|
- features.</para>
|
|
|
-
|
|
|
- <para>As you probably know, security comprises two major operations.
|
|
|
- The first is known as "authentication", which is the process of
|
|
|
- establishing a principal is who they claim to be. A "principal"
|
|
|
- generally means a user, device or some other system which can perform
|
|
|
- an action in your application. "Authorization" refers to the process
|
|
|
- of deciding whether a principal is allowed to perform an action in
|
|
|
- your application. To arrive at the point where an authorization
|
|
|
- decision is needed, the identity of the principal has already been
|
|
|
- established by the authentication process. These concepts are common,
|
|
|
- and not at all specific to Acegi Security.</para>
|
|
|
-
|
|
|
- <para>At an authentication level, Acegi Security supports a wide range
|
|
|
- of authentication models. Most of these authentication models are
|
|
|
- either provided by third parties, or are developed by relevant
|
|
|
- standards bodies such as the Internet Engineering Task Force. In
|
|
|
- addition, Acegi Security provides its own set of authentication
|
|
|
- features. Specifically, Acegi Security currently supports
|
|
|
- authentication with all of these technologies:</para>
|
|
|
-
|
|
|
- <itemizedlist spacing="compact">
|
|
|
- <listitem>
|
|
|
- <para>HTTP BASIC authentication headers (an IEFT RFC-based
|
|
|
- standard)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>HTTP Digest authentication headers (an IEFT RFC-based
|
|
|
- standard)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>HTTP X.509 client certificate exchange (an IEFT RFC-based
|
|
|
- standard)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>LDAP (a very common approach to cross-platform
|
|
|
- authentication needs, especially in large environments)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Form-based authentication (for simple user interface
|
|
|
- needs)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Computer Associates Siteminder</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>JA-SIG Central Authentication Service (otherwise known as
|
|
|
- CAS, which is a popular open source single sign on system)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Transparent authentication context propagation for Remote
|
|
|
- Method Invocation (RMI) and HttpInvoker (a Spring remoting
|
|
|
- protocol)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Automatic "remember-me" authentication (so you can tick a
|
|
|
- box to avoid re-authentication for a predetermined period of
|
|
|
- time)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Anonymous authentication (allowing every call to
|
|
|
- automatically assume a particular security identity)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Run-as authentication (which is useful if one call should
|
|
|
- proceed with a different security identity)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Java Authentication and Authorization Service (JAAS)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Container integration with JBoss, Jetty, Resin and Tomcat
|
|
|
- (so you can still use Container Manager Authentication if
|
|
|
- desired)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Your own authentication systems (see below)</para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist>
|
|
|
-
|
|
|
- <para>Many independent software vendors (ISVs) adopt Acegi Security
|
|
|
- because of this rich choice of authentication models. Doing so allows
|
|
|
- them to quickly integrate their solutions with whatever their end
|
|
|
- clients need, without undertaking a lot of engineering or requiring
|
|
|
- the client to change their environment. If none of the above
|
|
|
- authentication mechanisms suit your needs, Acegi Security is an open
|
|
|
- platform and it is quite simple to write your own authentication
|
|
|
- mechanism. Many corporate users of Acegi Security need to integrate
|
|
|
- with "legacy" systems that don't follow any particular security
|
|
|
- standards, and Acegi Security is happy to "play nicely" with such
|
|
|
- systems.</para>
|
|
|
-
|
|
|
- <para>Sometimes the mere process of authentication isn't enough.
|
|
|
- Sometimes you need to also differentiate security based on the way a
|
|
|
- principal is interacting with your application. For example, you might
|
|
|
- want to ensure requests only arrive over HTTPS, in order to protect
|
|
|
- passwords from eavesdropping or end users from man-in-the-middle
|
|
|
- attacks. Or, you might want to ensure that an actual human being is
|
|
|
- making the requests and not some robot or other automated process.
|
|
|
- This is especially helpful to protect password recovery processes from
|
|
|
- brute force attacks, or simply to make it harder for people to
|
|
|
- duplicate your application's key content. To help you achieve these
|
|
|
- goals, Acegi Security fully supports automatic "channel security",
|
|
|
- together with JCaptcha integration for human user detection.</para>
|
|
|
-
|
|
|
- <para>Irrespective of how authentication was undertaken, Acegi
|
|
|
- Security provides a deep set of authorization capabilities. There are
|
|
|
- three main areas of interest in respect of authorization, these being
|
|
|
- authorizing web requests, authorizing methods can be invoked, and
|
|
|
- authorizing access to individual domain object instances. To help you
|
|
|
- understand the differences, consider the authorization capabilities
|
|
|
- found in the Servlet Specification web pattern security, EJB Container
|
|
|
- Managed Security and file system security respectively. Acegi Security
|
|
|
- provides deep capabilities in all of these important areas, which
|
|
|
- we'll explore later in this reference guide.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="history">
|
|
|
- <title>History</title>
|
|
|
-
|
|
|
- <para>Acegi Security began in late 2003, when a question was posed on
|
|
|
- the Spring Developers' mailing list asking whether there had been any
|
|
|
- consideration given to a Spring-based security implementation. At the
|
|
|
- time the Spring community was relatively small (especially by today's
|
|
|
- size!), and indeed Spring itself had only existed as a SourceForge
|
|
|
- project from early 2003. The response to the question was that it was
|
|
|
- a worthwhile area, although a lack of time currently prevented its
|
|
|
- exploration.</para>
|
|
|
-
|
|
|
- <para>With that in mind, a simple security implementation was built
|
|
|
- and not released. A few weeks later another member of the Spring
|
|
|
- community inquired about security, and at the time this code was
|
|
|
- offered to them. Several other requests followed, and by January 2004
|
|
|
- around twenty people were using the code. These pioneering users were
|
|
|
- joined by others who suggested a SourceForge project was in order,
|
|
|
- which was duly established in March 2004.</para>
|
|
|
-
|
|
|
- <para>In those early days, the project didn't have any of its own
|
|
|
- authentication modules. Container Managed Security was relied upon for
|
|
|
- the authentication process, with Acegi Security instead focusing on
|
|
|
- authorization. This was suitable at first, but as more and more users
|
|
|
- requested additional container support, the fundamental limitation of
|
|
|
- container-specific authentication realm interfaces was experienced.
|
|
|
- There was also a related issue of adding new JARs to the container's
|
|
|
- classpath, which was a common source of end user confusion and
|
|
|
- misconfiguration.</para>
|
|
|
-
|
|
|
- <para>Acegi Security-specific authentication services were
|
|
|
- subsequently introduced. Around a year later, the Acegi Security
|
|
|
- became an official Spring Framework subproject. The 1.0.0 final
|
|
|
- release was published in May 2006 - after more than two and a half
|
|
|
- years of active use in numerous production software projects and many
|
|
|
- hundreds of improvements and community contributions.</para>
|
|
|
-
|
|
|
- <para>Today Acegi Security enjoys a strong and active open source
|
|
|
- community. There are thousands of messages about Acegi Security on the
|
|
|
- support forums. Fourteen developers work on the code itself, with an
|
|
|
- active community who also regularly share patches and support their
|
|
|
- peers.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="release-numbering">
|
|
|
- <title>Release Numbering</title>
|
|
|
-
|
|
|
- <para>It is useful to understand how Acegi Security release numbers
|
|
|
- work, as it will help you identify the effort (or lack thereof)
|
|
|
- involved in migrating to future releases of the project. Officially,
|
|
|
- we use the Apache Portable Runtime Project versioning guidelines,
|
|
|
- which can be viewed at
|
|
|
- <literal>http://apr.apache.org/versioning.html</literal>. We quote the
|
|
|
- introduction contained on that page for your convenience:</para>
|
|
|
-
|
|
|
- <para><quote>Versions are denoted using a standard triplet of
|
|
|
- integers: MAJOR.MINOR.PATCH. The basic intent is that MAJOR versions
|
|
|
- are incompatible, large-scale upgrades of the API. MINOR versions
|
|
|
- retain source and binary compatibility with older minor versions, and
|
|
|
- changes in the PATCH level are perfectly compatible, forwards and
|
|
|
- backwards.</quote></para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="technical-overview">
|
|
|
- <title>Technical Overview</title>
|
|
|
-
|
|
|
- <sect1 id="runtime-environment">
|
|
|
- <title>Runtime Environment</title>
|
|
|
-
|
|
|
- <para>Acegi Security is written to execute within a standard Java 1.3
|
|
|
- Runtime Environment. It also supports Java 5.0, although the Java
|
|
|
- types which are specific to this release are packaged in a separate
|
|
|
- package with the suffix "tiger" in their JAR filename. As Acegi
|
|
|
- Security aims to operate in a self-contained manner, there is no need
|
|
|
- to place any special configuration files into your Java Runtime
|
|
|
- Environment. In particular, there is no need to configure a special
|
|
|
- Java Authentication and Authorization Service (JAAS) policy file or
|
|
|
- place Acegi Security into common classpath locations.</para>
|
|
|
-
|
|
|
- <para>Similarly, if you are using an EJB Container or Servlet
|
|
|
- Container there is no need to put any special configuration files
|
|
|
- anywhere, nor include Acegi Security in a server classloader.</para>
|
|
|
-
|
|
|
- <para>This above design offers maximum deployment time flexibility, as
|
|
|
- you can simply copy your target artifact (be it a JAR, WAR or EAR)
|
|
|
- from one system to another and it will immediately work.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="shared-components">
|
|
|
- <title>Shared Components</title>
|
|
|
-
|
|
|
- <para>Let's explore some of the most important shared components in
|
|
|
- Acegi Security. Components are considered "shared" if they are central
|
|
|
- to the framework and the framework cannot operate without them. These
|
|
|
- Java types represent the building blocks of the remaining system, so
|
|
|
- it's important to understand that they're there, even if you don't
|
|
|
- need to directly interact with them.</para>
|
|
|
-
|
|
|
- <para>The most fundamental object is
|
|
|
- <literal>SecurityContextHolder</literal>. This is where we store
|
|
|
- details of the present security context of the application, which
|
|
|
- includes details of the principal currently using the application. By
|
|
|
- default the <literal>SecurityContextHolder</literal> uses a
|
|
|
- <literal>ThreadLocal</literal> to store these details, which means
|
|
|
- that the security context is always available to methods in the same
|
|
|
- thread of execution, even if the security context is not explicitly
|
|
|
- passed around as an argument those methods. Using a
|
|
|
- <literal>ThreadLocal</literal> in this way is quite safe if care is
|
|
|
- taken to clear the thread after the present principal's request is
|
|
|
- processed. Of course, Acegi Security takes care of for you
|
|
|
- automatically so there is no need to worry about it.</para>
|
|
|
-
|
|
|
- <para>Some applications aren't entirely suitable for using a
|
|
|
- <literal>ThreadLocal</literal>, because of the specific way they work
|
|
|
- with threads. For example, a Swing client might want all threads in a
|
|
|
- Java Virtual Machine to use the same security context. For this
|
|
|
- situation you would use the
|
|
|
- <literal>SecurityContextHolder.MODE_GLOBAL</literal>. Other
|
|
|
- applications might want to have threads spawned by the secure thread
|
|
|
- also assume the same security identity. This is achieved by using
|
|
|
- <literal>SecurityContextHolder.MODE_INHERITABLETHREADLOCAL</literal>.
|
|
|
- You can change the mode from the default
|
|
|
- <literal>SecurityContextHolder.MODE_THREADLOCAL</literal> in two ways.
|
|
|
- The first is to set a system property. Alternatively, call a static
|
|
|
- method on <literal>SecurityContextHolder</literal>. Most applications
|
|
|
- won't need to change from the default, but if you do, take a look at
|
|
|
- the JavaDocs for <literal>SecurityContextHolder</literal> to learn
|
|
|
- more.</para>
|
|
|
-
|
|
|
- <para>Inside the <literal>SecurityContextHolder</literal> we store
|
|
|
- details of the principal currently interacting with the application.
|
|
|
- Acegi Security uses an <literal>Authentication</literal> object to
|
|
|
- represent this information. Whilst you won't normally need to create
|
|
|
- an <literal>Authentication</literal> object yourself, it is fairly
|
|
|
- common for users to query the <literal>Authentication</literal>
|
|
|
- object. You can use the following code block - from anywhere in your
|
|
|
- application - to do this:</para>
|
|
|
-
|
|
|
- <programlisting>Object obj = SecurityContextHolder.getContext().getAuthentication().getPrincipal();
|
|
|
-
|
|
|
-if (obj instanceof UserDetails) {
|
|
|
- String username = ((UserDetails)obj).getUsername();
|
|
|
-} else {
|
|
|
- String username = obj.toString();
|
|
|
-}</programlisting>
|
|
|
-
|
|
|
- <para>The above code introduces a number of interesting relationships
|
|
|
- and key objects. First, you will notice that there is an intermediate
|
|
|
- object between <literal>SecurityContextHolder</literal> and
|
|
|
- <literal>Authentication</literal>. The
|
|
|
- <literal>SecurityContextHolder.getContext()</literal> method is
|
|
|
- actually returning a <literal>SecurityContext</literal>. Acegi
|
|
|
- Security uses a few different <literal>SecurityContext</literal>
|
|
|
- implementations, such as if we need to store special information
|
|
|
- related to a request that is not principal-specific. A good example of
|
|
|
- this is our JCaptcha integration, which needs to know whether the
|
|
|
- current request came from a human user or not. Because such a decision
|
|
|
- has nothing at all to do with the principal the request may or may not
|
|
|
- be authenticated as, we store it in the
|
|
|
- <literal>SecurityContext</literal>.</para>
|
|
|
-
|
|
|
- <para>Another item to note from the above code fragment is that you
|
|
|
- can obtain a principal from the <literal>Authentication</literal>
|
|
|
- object. The principal is just an <literal>Object</literal>. Most of
|
|
|
- the time this can be cast into a <literal>UserDetails</literal>
|
|
|
- object. <literal>UserDetails</literal> is a central interface in Acegi
|
|
|
- Security. It represents a principal, but in an extensible and
|
|
|
- application-specific way. Think of <literal>UserDetails</literal> as
|
|
|
- the adapter between your own user database and what Acegi Security
|
|
|
- needs inside the <literal>SecurityContextHolder</literal>. Being a
|
|
|
- representation of something from your own user database, quite often
|
|
|
- you will cast the <literal>UserDetails</literal> to the original
|
|
|
- object that your application provided, so you can call
|
|
|
- business-specific methods (like <literal>getEmail()</literal>,
|
|
|
- <literal>getEmployeeNumber()</literal> and so on).</para>
|
|
|
-
|
|
|
- <para>By now you're probably wondering, so when do I provide a
|
|
|
- <literal>UserDetails</literal> object? How do I do that? I thought you
|
|
|
- said this thing was declarative and I didn't need to write any Java
|
|
|
- code - what gives? The short answer is that there is a special
|
|
|
- interface called <literal>UserDetailsService</literal>. The only
|
|
|
- method on this interface accepts a <literal>String</literal>-based
|
|
|
- username argument and returns a <literal>UserDetails</literal>. Most
|
|
|
- authentication providers that ship with Acegi Security delegate to a
|
|
|
- <literal>UserDetailsService</literal> as part of the authentication
|
|
|
- process. The <literal>UserDetailsService</literal> is used to build
|
|
|
- the <literal>Authentication</literal> object that is stored in the
|
|
|
- <literal>SecurityContextHolder</literal>. The good news is that we
|
|
|
- provide a number of <literal>UserDetailsService</literal>
|
|
|
- implementations, including one that uses an in-memory map and another
|
|
|
- that uses JDBC. Most users tends to write their own, though, with such
|
|
|
- implementations often simply sitting on top of an existing Data Access
|
|
|
- Object (DAO) that represents their employees, customers, or other
|
|
|
- users of the enterprise application. Remember the advantage that
|
|
|
- whatever your UserDetailsService returns can always be obtained from
|
|
|
- the <literal>SecurityContextHolder</literal>, as per the above code
|
|
|
- fragment.</para>
|
|
|
-
|
|
|
- <para>Besides the principal, another important method provided by
|
|
|
- <literal>Authentication</literal> is
|
|
|
- <literal>getAuthorities(</literal>). This method provides an array of
|
|
|
- <literal>GrantedAuthority</literal> objects. A
|
|
|
- <literal>GrantedAuthority</literal> is, not surprisingly, an authority
|
|
|
- that is granted to the principal. Such authorities are usually
|
|
|
- "roles", such as <literal>ROLE_ADMINISTRATOR</literal> or
|
|
|
- <literal>ROLE_HR_SUPERVISOR</literal>. These roles are later on
|
|
|
- configured for web authorization, method authorization and domain
|
|
|
- object authorization. Other parts of Acegi Security are capable of
|
|
|
- interpreting these authorities, and expect them to be present. You
|
|
|
- will usually return <literal>GrantedAuthority</literal> objects from
|
|
|
- the <literal>UserDetailsService</literal>.</para>
|
|
|
-
|
|
|
- <para>Usually the <literal>GrantedAuthority</literal> objects are
|
|
|
- application-wide permissions. They are not specific to a given domain
|
|
|
- object. Thus, you wouldn't likely have a
|
|
|
- <literal>GrantedAuthority</literal> to represent a permission to
|
|
|
- <literal>Employee</literal> object number 54, because if there are
|
|
|
- thousands of such authorities you would quickly run out of memory (or,
|
|
|
- at the very least, cause the application to take a long time to
|
|
|
- authenticate a user). Of course, Acegi Security is expressly designed
|
|
|
- to handle this common requirement, but you'd instead use the project's
|
|
|
- domain object security capabilities for this purpose.</para>
|
|
|
-
|
|
|
- <para>Last but not least, sometimes you will need to store the
|
|
|
- <literal>SecurityContext</literal> between HTTP requests. Other times
|
|
|
- the principal will re-authenticate on every request, although most of
|
|
|
- the time it will be stored. The
|
|
|
- <literal>HttpSessionContextIntegrationFilter</literal> is responsible
|
|
|
- for storing a <literal>SecurityContext</literal> between HTTP
|
|
|
- requests. As suggested by the name of the class, the
|
|
|
- <literal>HttpSession</literal> is used to store this information. You
|
|
|
- should never interact directly with the <literal>HttpSession</literal>
|
|
|
- for security purposes. There is simply no justification for doing so -
|
|
|
- always use the <literal>SecurityContextHolder</literal>
|
|
|
- instead.</para>
|
|
|
-
|
|
|
- <para>Just to recap, the major building blocks of Acegi Security
|
|
|
- are:</para>
|
|
|
-
|
|
|
- <itemizedlist spacing="compact">
|
|
|
- <listitem>
|
|
|
- <para><literal>SecurityContextHolder</literal>, to provide any
|
|
|
- type access to the <literal>SecurityContext</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>SecurityContext</literal>, to hold the
|
|
|
- <literal>Authentication</literal> and possibly request-specific
|
|
|
- security information.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>HttpSessionContextIntegrationFilter</literal>, to
|
|
|
- store the <literal>SecurityContext</literal> in the
|
|
|
- <literal>HttpSession</literal> between web requests.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>Authentication</literal>, to represent the
|
|
|
- principal in an Acegi Security-specific manner.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>GrantedAuthority</literal>, to reflect the
|
|
|
- application-wide permissions granted to a principal.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>UserDetails</literal>, to provide the necessary
|
|
|
- information to build an Authentication object from your
|
|
|
- application's DAOs.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>UserDetailsService</literal>, to create a
|
|
|
- <literal>UserDetails</literal> when passed in a
|
|
|
- <literal>String</literal>-based username (or certificate ID or
|
|
|
- alike).</para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist>
|
|
|
-
|
|
|
- <para>Now that you've gained an understanding of these repeatedly-used
|
|
|
- components, let's take a closer look at the process of
|
|
|
- authentication.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="common-authentication">
|
|
|
- <title>Authentication</title>
|
|
|
-
|
|
|
- <para>As mentioned in the beginning of this reference guide, Acegi
|
|
|
- Security can participate in many different authentication
|
|
|
- environments. Whilst we recommend people use Acegi Security for
|
|
|
- authentication and not integrate with existing Container Managed
|
|
|
- Authentication, it is nevertheless supported - as is integrating with
|
|
|
- your own proprietary authentication system. Let's first explore
|
|
|
- authentication from the perspective of Acegi Security managing web
|
|
|
- security entirely on its own, which is illustrative of the most
|
|
|
- complex and most common situation.</para>
|
|
|
-
|
|
|
- <para>Consider a typical web application's authentication
|
|
|
- process:</para>
|
|
|
-
|
|
|
- <orderedlist>
|
|
|
- <listitem>
|
|
|
- <para>You visit the home page, and click on a link.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>A request goes to the server, and the server decides that
|
|
|
- you've asked for a protected resource.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>As you're not presently authenticated, the server sends back
|
|
|
- a response indicating that you must authenticate. The response
|
|
|
- will either be a HTTP response code, or a redirect to a particular
|
|
|
- web page.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Depending on the authentication mechanism, your browser will
|
|
|
- either redirect to the specific web page so that you can fill out
|
|
|
- the form, or the browser will somehow retrieve your identity (eg a
|
|
|
- BASIC authentication dialogue box, a cookie, a X509 certificate
|
|
|
- etc).</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The browser will send back a response to the server. This
|
|
|
- will either be a HTTP POST containing the contents of the form
|
|
|
- that you filled out, or a HTTP header containing your
|
|
|
- authentication details.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Next the server will decide whether or not the presented
|
|
|
- credentials are valid. If they're valid, the next step will
|
|
|
- happen. If they're invalid, usually your browser will be asked to
|
|
|
- try again (so you return to step two above).</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The original request that you made to cause the
|
|
|
- authentication process will be retried. Hopefully you've
|
|
|
- authenticated with sufficient granted authorities to access the
|
|
|
- protected resource. If you have sufficient access, the request
|
|
|
- will be successful. Otherwise, you'll receive back a HTTP error
|
|
|
- code 403, which means "forbidden".</para>
|
|
|
- </listitem>
|
|
|
- </orderedlist>
|
|
|
-
|
|
|
- <para>Acegi Security has distinct classes responsible for most of the
|
|
|
- steps described above. The main participants (in the order that they
|
|
|
- are used) are the <literal>ExceptionTranslationFilter</literal>, an
|
|
|
- <literal>AuthenticationEntryPoint</literal>, an authentication
|
|
|
- mechanism, and an <literal>AuthenticationProvider</literal>.</para>
|
|
|
-
|
|
|
- <para><literal>ExceptionTranslationFilter</literal> is an Acegi
|
|
|
- Security filter that has responsibility for detecting any Acegi
|
|
|
- Security exceptions that are thrown. Such exceptions will generally be
|
|
|
- thrown by an <literal>AbstractSecurityInterceptor</literal>, which is
|
|
|
- the main provider of authorization services. We will discuss
|
|
|
- <literal>AbstractSecurityInterceptor</literal> in the next section,
|
|
|
- but for now we just need to know that it produces Java exceptions and
|
|
|
- knows nothing about HTTP or how to go about authenticating a
|
|
|
- principal. Instead the <literal>ExceptionTranslationFilter</literal>
|
|
|
- offers this service, with specific responsibility for either returning
|
|
|
- error code 403 (if the principal has been authenticated and therefore
|
|
|
- simply lacks sufficient access - as per step seven above), or
|
|
|
- launching an <literal>AuthenticationEntryPoint</literal> (if the
|
|
|
- principal has not been authenticated and therefore we need to go
|
|
|
- commence step three).</para>
|
|
|
-
|
|
|
- <para>The <literal>AuthenticationEntryPoint</literal> is responsible
|
|
|
- for step three in the above list. As you can imagine, each web
|
|
|
- application will have a default authentication strategy (well, this
|
|
|
- can be configured like nearly everything else in Acegi Security, but
|
|
|
- let's keep it simple for now). Each major authentication system will
|
|
|
- have its own <literal>AuthenticationEntryPoint</literal>
|
|
|
- implementation, which takes actions such as described in step
|
|
|
- three.</para>
|
|
|
-
|
|
|
- <para>After your browser decides to submit your authentication
|
|
|
- credentials (either as a HTTP form post or HTTP header) there needs to
|
|
|
- be something on the server that "collects" these authentication
|
|
|
- details. By now we're at step six in the above list. In Acegi Security
|
|
|
- was have a special name for the function of collecting authentication
|
|
|
- details from a user agent (usually a web browser), and that name is
|
|
|
- "authentication mechanism". After the authentication details are
|
|
|
- collected from the user agent, an "<literal>Authentication</literal>
|
|
|
- request" object is built and then presented to an
|
|
|
- AuthenticationProvider.</para>
|
|
|
-
|
|
|
- <para>The last played in the Acegi Security authentication process is
|
|
|
- an <literal>AuthenticationProvider</literal>. Quite simply, it is
|
|
|
- responsible for taking an <literal>Authentication</literal> request
|
|
|
- object and deciding whether or not it is valid. The provider will
|
|
|
- either throw an exception, or return a fully populated
|
|
|
- <literal>Authentication</literal> object. Remember our good friends,
|
|
|
- <literal>UserDetails</literal> and
|
|
|
- <literal>UserDetailsService</literal>? If not, head back to the
|
|
|
- previous section and refresh your memory. Most
|
|
|
- <literal>AuthenticationProvider</literal>s will ask a
|
|
|
- <literal>UserDetailsService</literal> to provide a
|
|
|
- <literal>UserDetails</literal> object. As mentioned earlier, most
|
|
|
- application will provide their own
|
|
|
- <literal>UserDetailsService</literal>, although some will be able to
|
|
|
- use the JDBC or in-memory implementation that ships with Acegi
|
|
|
- Security. The resultant <literal>UserDetails</literal> object - and
|
|
|
- particularly the <literal>GrantedAuthority[]</literal>s contained
|
|
|
- within the <literal>UserDetails</literal> object - will be used when
|
|
|
- building the fully populated <literal>Authentication</literal>
|
|
|
- object.</para>
|
|
|
-
|
|
|
- <para>After the authentication mechanism receives back the
|
|
|
- fully-populated <literal>Authentication</literal> object, it will deem
|
|
|
- the request valid, put the <literal>Authentication</literal> into the
|
|
|
- <literal>SecurityContextHolder</literal>, and cause the original
|
|
|
- request to be retried (step seven above). If, on the other hand, the
|
|
|
- <literal>AuthenticationProvider</literal> rejected the request, the
|
|
|
- authentication mechanism will ask the user agent to retry (step two
|
|
|
- above).</para>
|
|
|
-
|
|
|
- <para>Whilst this describes the typical authentication workflow, the
|
|
|
- good news is that Acegi Security doesn't mind how you put an
|
|
|
- <literal>Authentication</literal> inside the
|
|
|
- <literal>SecurityContextHolder</literal>. The only critical
|
|
|
- requirement is that the <literal>SecurityContextHolder</literal>
|
|
|
- contains an <literal>Authentication</literal> that represents a
|
|
|
- principal before the <literal>AbstractSecurityInterceptor</literal>
|
|
|
- needs to authorize a request.</para>
|
|
|
-
|
|
|
- <para>You can (and many users do) write their own filters or MVC
|
|
|
- controllers to provide interoperability with authentication systems
|
|
|
- that are not based on Acegi Security. For example, you might be using
|
|
|
- Container Managed Authentication which makes the current user
|
|
|
- available from a ThreadLocal or JNDI location. Or you might work for a
|
|
|
- company that has a legacy proprietary authentication system, which is
|
|
|
- a corporate "standard" over which you have little control. In such
|
|
|
- situations it's quite easy to get Acegi Security to work, and still
|
|
|
- provide authorization capabilities. All you need to do is write a
|
|
|
- filter (or equivalent) that reads the third-party user information
|
|
|
- from a location, build an Acegi Security-specific Authentication
|
|
|
- object, and put it onto the SecurityContextHolder. It's quite easy to
|
|
|
- do this, and a fully-supported integration approach.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="secure-objects">
|
|
|
- <title>Secure Objects</title>
|
|
|
-
|
|
|
- <para>If you're familiar with AOP, you'd be aware there are different
|
|
|
- types of advice available: before, after, throws and around. An around
|
|
|
- advice is very useful, because an advisor can elect whether or not to
|
|
|
- proceed with a method invocation, whether or not to modify the
|
|
|
- response, and whether or not to throw an exception. Acegi Security
|
|
|
- provides an around advice for method invocations as well as web
|
|
|
- requests. We achieve an around advice for method invocations using AOP
|
|
|
- Alliance, and we achieve an around advice for web requests using a
|
|
|
- standard Filter.</para>
|
|
|
-
|
|
|
- <para>For those not familiar with AOP, the key point to understand is
|
|
|
- that Acegi Security can help you protect method invocations as well as
|
|
|
- web requests. Most people are interested in securing method
|
|
|
- invocations on their services layer. This is because the services
|
|
|
- layer is where most business logic resides in current-generation J2EE
|
|
|
- applications (for clarification, the author disapproves of this design
|
|
|
- and instead advocates properly encapsulated domain objects together
|
|
|
- with the DTO, assembly, facade and transparent persistence patterns,
|
|
|
- but as anemic domain objects is the present mainstream approach, we'll
|
|
|
- talk about it here). If you just need to secure method invocations to
|
|
|
- the services layer, using the Spring's standard AOP platform
|
|
|
- (otherwise known as AOP Alliance) will be adequate. If you need to
|
|
|
- secure domain objects directly, you will likely find that AspectJ is
|
|
|
- worth considering.</para>
|
|
|
-
|
|
|
- <para>You can elect to perform method authorization using AspectJ or
|
|
|
- AOP Alliance, or you can elect to perform web request authorization
|
|
|
- using filters. You can use zero, one, two or three of these approaches
|
|
|
- together. The mainstream usage is to perform some web request
|
|
|
- authorization, coupled with some AOP Alliance method invocation
|
|
|
- authorization on the services layer.</para>
|
|
|
-
|
|
|
- <para>Acegi Security uses the term "secure object" to refer to any
|
|
|
- object that can have security applies to it. Each secure object
|
|
|
- supported by Acegi Security has its own class, which is a subclass of
|
|
|
- <literal>AbstractSecurityInterceptor</literal>. Importantly, by the
|
|
|
- time the <literal>AbstractSecurityInterceptor</literal> is run, the
|
|
|
- <literal>SecurityContextHolder</literal> will contain a valid
|
|
|
- <literal>Authentication</literal> if the principal has been
|
|
|
- authenticated.</para>
|
|
|
-
|
|
|
- <para>The <literal>AbstractSecurityInterceptor</literal> provides a
|
|
|
- consistent workflow for handling secure object requests. This workflow
|
|
|
- includes looking up the "configuration attributes" associated with the
|
|
|
- present request. A "configuration attribute" can be thought of as a
|
|
|
- String that has special meaning to the classes used by
|
|
|
- <literal>AbstractSecurityInterceptor</literal>. They're normally
|
|
|
- configured against your AbstractSecurityInterceptor using XML. Anyway,
|
|
|
- the <literal>AbstractSecurityInterceptor</literal> will ask an
|
|
|
- <literal>AccessDecisionManager</literal> "here's the configuration
|
|
|
- attributes, here's the current <literal>Authentication</literal>
|
|
|
- object, and here's details of the current request - is this particular
|
|
|
- principal allowed to perform this particular operation?".</para>
|
|
|
-
|
|
|
- <para>Assuming <literal>AccessDecisionManager</literal> decides to
|
|
|
- allow the request, the <literal>AbstractSecurityInterceptor</literal>
|
|
|
- will normally just proceed with the request. Having said that, on rare
|
|
|
- occasions users may want to replace the
|
|
|
- <literal>Authentication</literal> inside the
|
|
|
- <literal>SecurityContext</literal> with a different
|
|
|
- <literal>Authentication</literal>, which is handled by the
|
|
|
- <literal>AccessDecisionManager</literal> calling a
|
|
|
- <literal>RunAsManager</literal>. This might be useful in reasonably
|
|
|
- unusual situations, such as if a services layer method needs to call a
|
|
|
- remote system and present a different identity. Because Acegi Security
|
|
|
- automatically propagates security identity from one server to another
|
|
|
- (assuming you're using a properly-configured RMI or HttpInvoker
|
|
|
- remoting protocol client), this may be useful.</para>
|
|
|
-
|
|
|
- <para>Following the secure object proceeding and then returning -
|
|
|
- which may mean a method invocation completing or a filter chain
|
|
|
- proceeding - the <literal>AbstractSecurityInterceptor</literal> gets
|
|
|
- one final chance to handle the invocation. At this stage the
|
|
|
- <literal>AbstractSecurityInterceptor</literal> is interested in
|
|
|
- possibly modifying the return object. We might want this to happen
|
|
|
- because an authorization decision couldn't be made "on the way in" to
|
|
|
- a secure object invocation. Being highly pluggable,
|
|
|
- <literal>AbstractSecurityInterceptor</literal> will pass control to an
|
|
|
- <literal>AfterInvocationManager</literal> to actually modify the
|
|
|
- object if needed. This class even can entirely replace the object, or
|
|
|
- throw an exception, or not change it in any way.</para>
|
|
|
-
|
|
|
- <para>Because <literal>AbstractSecurityInterceptor</literal> is the
|
|
|
- central template class, it seems fitting that the first figure should
|
|
|
- be devoted to it.</para>
|
|
|
-
|
|
|
- <para><mediaobject>
|
|
|
- <imageobject role="html">
|
|
|
- <imagedata align="center"
|
|
|
- fileref="images/SecurityInterception.gif"
|
|
|
- format="GIF" />
|
|
|
- </imageobject>
|
|
|
-
|
|
|
- <caption>
|
|
|
- <para>Figure 1: The key "secure object" model</para>
|
|
|
- </caption>
|
|
|
- </mediaobject></para>
|
|
|
-
|
|
|
- <para>Only developers contemplating an entirely new way of
|
|
|
- intercepting and authorizing requests would need to use secure objects
|
|
|
- directly. For example, it would be possible to build a new secure
|
|
|
- object to secure calls to a messaging system. Anything that requires
|
|
|
- security and also provides a way of intercepting a call (like the AOP
|
|
|
- around advice semantics) is capable of being made into a secure
|
|
|
- object. Having said that, most Spring applications will simply use the
|
|
|
- three currently supported secure object types (AOP Alliance
|
|
|
- <literal>MethodInvocation</literal>, AspectJ
|
|
|
- <literal>JoinPoint</literal> and web request
|
|
|
- <literal>FilterInterceptor</literal>) with complete
|
|
|
- transparency.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="common-conclusion">
|
|
|
- <title>Conclusion</title>
|
|
|
-
|
|
|
- <para>Congratulations! You have enough of a high-level picture of
|
|
|
- Acegi Security to embark on your project. We've explored the shared
|
|
|
- components, how authentication works, and reviewed the common
|
|
|
- authorization concept of a "secure object". Everything that follows in
|
|
|
- this reference guide may or may not apply to your particular needs,
|
|
|
- and can be read in any order.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="supporting-infrastructure">
|
|
|
- <title>Supporting Infrastructure</title>
|
|
|
-
|
|
|
- <para>This chapter introduces some of the supplementary and supporting
|
|
|
- infrastructure used by Acegi Security. If a capability is not directly
|
|
|
- related to security, yet included in the Acegi Security project, we will
|
|
|
- discuss it in this chapter.</para>
|
|
|
-
|
|
|
- <sect1 id="localization">
|
|
|
- <title>Localization</title>
|
|
|
-
|
|
|
- <para>Acegi Security supports localization of exception messages that
|
|
|
- end users are likely to see. If your application is designed for
|
|
|
- English users, you don't need to do anything as by default all Acegi
|
|
|
- Security messages are in English. If you need to support other
|
|
|
- locales, everything you need to know is contained in this
|
|
|
- section.</para>
|
|
|
-
|
|
|
- <para>All exception messages can be localized, including messages
|
|
|
- related to authentication failures and access being denied
|
|
|
- (authorization failures). Exceptions and logging that is focused on
|
|
|
- developers or system deployers (including incorrect attributes,
|
|
|
- interface contract violations, using incorrect constructors, startup
|
|
|
- time validation, debug-level logging) etc are not localized and
|
|
|
- instead are hard-coded in English within Acegi Security's code.</para>
|
|
|
-
|
|
|
- <para>Shipping in the <literal>acegi-security-xx.jar</literal> you
|
|
|
- will find an <literal>org.acegisecurity</literal> package that in turn
|
|
|
- contains a <literal>messages.properties</literal> file. This should be
|
|
|
- referred to by your <literal>ApplicationContext</literal>, as Acegi
|
|
|
- Security classes implement Spring's
|
|
|
- <literal>MessageSourceAware</literal> interface and expect the message
|
|
|
- resolver to be dependency injected at application context startup
|
|
|
- time. Usually all you need to do is register a bean inside your
|
|
|
- application context to refer to the messages. An example is shown
|
|
|
- below:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="messageSource" class="org.springframework.context.support.ReloadableResourceBundleMessageSource">
|
|
|
- <property name="basename"><value>org/acegisecurity/messages</value></property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>messages.properties</literal> is named in
|
|
|
- accordance with standard resource bundles and represents the default
|
|
|
- language supported by Acegi Securtiy messages. This default file is in
|
|
|
- English. If you do not register a message source, Acegi Security will
|
|
|
- still work correctly and fallback to hard-coded English versions of
|
|
|
- the messages.</para>
|
|
|
-
|
|
|
- <para>If you wish to customize the
|
|
|
- <literal>messages.properties</literal> file, or support other
|
|
|
- languages, you should copy the file, rename it accordingly, and
|
|
|
- register it inside the above bean definition. There are not a large
|
|
|
- number of message keys inside this file, so localization should not be
|
|
|
- considered a major initiative. If you do perform localization of this
|
|
|
- file, please consider sharing your work with the community by logging
|
|
|
- a JIRA task and attaching your appropriately-named localized version
|
|
|
- of <literal>messages.properties</literal>.</para>
|
|
|
-
|
|
|
- <para>Rounding out the discussion on localization is the Spring
|
|
|
- <literal>ThreadLocal</literal> known as
|
|
|
- <literal>org.springframework.context.i18n.LocaleContextHolder</literal>.
|
|
|
- You should set the <literal>LocaleContextHolder</literal> to represent
|
|
|
- the preferred <literal>Locale</literal> of each user. Acegi Security
|
|
|
- will attempt to locate a message from the message source using the
|
|
|
- <literal>Locale</literal> obtained from this
|
|
|
- <literal>ThreadLocal</literal>. Please refer to Spring documentation
|
|
|
- for further details on using <literal>LocaleContextHolder</literal>
|
|
|
- and the helper classes that can automatically set it for you (eg
|
|
|
- <literal>AcceptHeaderLocaleResolver</literal>,
|
|
|
- <literal>CookieLocaleResolver</literal>,
|
|
|
- <literal>FixedLocaleResolver</literal>,
|
|
|
- <literal>SessionLocaleResolver</literal> etc)</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="filters">
|
|
|
- <title>Filters</title>
|
|
|
-
|
|
|
- <para>Acegi Security uses many filters, as referred to throughout the
|
|
|
- remainder of this reference guide. You have a choice in how these
|
|
|
- filters are added to your web application, in that you can use either
|
|
|
- <literal>FilterToBeanProxy</literal> or
|
|
|
- <literal>FilterChainProxy</literal>. We'll look at both below.</para>
|
|
|
-
|
|
|
- <para>Most filters are configured using the
|
|
|
- <literal>FilterToBeanProxy</literal>. An example configuration from
|
|
|
- <literal>web.xml</literal> follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><filter>
|
|
|
- <filter-name>Acegi HTTP Request Security Filter</filter-name>
|
|
|
- <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
|
|
|
- <init-param>
|
|
|
- <param-name>targetClass</param-name>
|
|
|
- <param-value>org.acegisecurity.ClassThatImplementsFilter</param-value>
|
|
|
- </init-param>
|
|
|
-</filter></programlisting></para>
|
|
|
-
|
|
|
- <para>Notice that the filter in <literal>web.xml</literal> is actually
|
|
|
- a <literal>FilterToBeanProxy</literal>, and not the filter that will
|
|
|
- actually implement the logic of the filter. What
|
|
|
- <literal>FilterToBeanProxy</literal> does is delegate the
|
|
|
- <literal>Filter</literal>'s methods through to a bean which is
|
|
|
- obtained from the Spring application context. This enables the bean to
|
|
|
- benefit from the Spring application context lifecycle support and
|
|
|
- configuration flexibility. The bean must implement
|
|
|
- <literal>javax.servlet.Filter</literal>.</para>
|
|
|
-
|
|
|
- <para>The <literal>FilterToBeanProxy</literal> only requires a single
|
|
|
- initialization parameter, <literal>targetClass</literal> or
|
|
|
- <literal>targetBean</literal>. The <literal>targetClass</literal>
|
|
|
- parameter locates the first object in the application context of the
|
|
|
- specified class, whilst <literal>targetBean</literal> locates the
|
|
|
- object by bean name. Like standard Spring web applications, the
|
|
|
- <literal>FilterToBeanProxy</literal> accesses the application context
|
|
|
- via<literal>
|
|
|
- WebApplicationContextUtils.getWebApplicationContext(ServletContext)</literal>,
|
|
|
- so you should configure a <literal>ContextLoaderListener</literal> in
|
|
|
- <literal>web.xml</literal>.</para>
|
|
|
-
|
|
|
- <para>There is a lifecycle issue to consider when hosting
|
|
|
- <literal>Filter</literal>s in an IoC container instead of a servlet
|
|
|
- container. Specifically, which container should be responsible for
|
|
|
- calling the <literal>Filter</literal>'s "startup" and "shutdown"
|
|
|
- methods? It is noted that the order of initialization and destruction
|
|
|
- of a <literal>Filter</literal> can vary by servlet container, and this
|
|
|
- can cause problems if one <literal>Filter</literal> depends on
|
|
|
- configuration settings established by an earlier initialized
|
|
|
- <literal>Filter</literal>. The Spring IoC container on the other hand
|
|
|
- has more comprehensive lifecycle/IoC interfaces (such as
|
|
|
- <literal>InitializingBean</literal>,
|
|
|
- <literal>DisposableBean</literal>, <literal>BeanNameAware</literal>,
|
|
|
- <literal>ApplicationContextAware</literal> and many others) as well as
|
|
|
- a well-understood interface contract, predictable method invocation
|
|
|
- ordering, autowiring support, and even options to avoid implementing
|
|
|
- Spring interfaces (eg the <literal>destroy-method</literal> attribute
|
|
|
- in Spring XML). For this reason we recommend the use of Spring
|
|
|
- lifecycle services instead of servlet container lifecycle services
|
|
|
- wherever possible. By default <literal>FilterToBeanProxy</literal>
|
|
|
- will not delegate <literal>init(FilterConfig)</literal> and
|
|
|
- <literal>destroy()</literal> methods through to the proxied bean. If
|
|
|
- you do require such invocations to be delegated, set the
|
|
|
- <literal>lifecycle</literal> initialization parameter to
|
|
|
- <literal>servlet-container-managed</literal>.</para>
|
|
|
-
|
|
|
- <para>Rather than using <literal>FilterToBeanProxy</literal>, we
|
|
|
- strongly recommend to use <literal>FilterChainProxy</literal> instead.
|
|
|
- Whilst <literal>FilterToBeanProxy</literal> is a very useful class,
|
|
|
- the problem is that the lines of code required for
|
|
|
- <literal><filter></literal> and
|
|
|
- <literal><filter-mapping></literal> entries in
|
|
|
- <literal>web.xml</literal> explodes when using more than a few
|
|
|
- filters. To overcome this issue, Acegi Security provides a
|
|
|
- <literal>FilterChainProxy</literal> class. It is wired using a
|
|
|
- <literal>FilterToBeanProxy</literal> (just like in the example above),
|
|
|
- but the target class is
|
|
|
- <literal>org.acegisecurity.util.FilterChainProxy</literal>. The filter
|
|
|
- chain is then declared in the application context, using code such as
|
|
|
- this:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy">
|
|
|
- <property name="filterInvocationDefinitionSource">
|
|
|
- <value>
|
|
|
- CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
|
|
|
- PATTERN_TYPE_APACHE_ANT
|
|
|
- /webServices/**=httpSessionContextIntegrationFilterWithASCFalse,basicProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor
|
|
|
- /**=httpSessionContextIntegrationFilterWithASCTrue,authenticationProcessingFilter,exceptionTranslationFilter,filterSecurityInterceptor
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>You may notice similarities with the way
|
|
|
- <literal>FilterSecurityInterceptor</literal> is declared. Both regular
|
|
|
- expressions and Ant Paths are supported, and the most specific URIs
|
|
|
- appear first. At runtime the <literal>FilterChainProxy</literal> will
|
|
|
- locate the first URI pattern that matches the current web request.
|
|
|
- Each of the corresponding configuration attributes represent the name
|
|
|
- of a bean defined in the application context. The filters will then be
|
|
|
- invoked in the order they are specified, with standard
|
|
|
- <literal>FilterChain</literal> behaviour being respected (a
|
|
|
- <literal>Filter</literal> can elect not to proceed with the chain if
|
|
|
- it wishes to end processing).</para>
|
|
|
-
|
|
|
- <para>As you can see, <literal>FilterChainProxy</literal> requires the
|
|
|
- duplication of filter names for different request patterns (in the
|
|
|
- above example, <literal>exceptionTranslationFilter</literal> and
|
|
|
- <literal>filterSecurityInterceptor</literal> are duplicated). This
|
|
|
- design decision was made to enable <literal>FilterChainProxy</literal>
|
|
|
- to specify different <literal>Filter</literal> invocation orders for
|
|
|
- different URI patterns, and also to improve both the expressiveness
|
|
|
- (in terms of regular expressions, Ant Paths, and any custom
|
|
|
- <literal>FilterInvocationDefinitionSource</literal> implementations)
|
|
|
- and clarity of which <literal>Filter</literal>s should be
|
|
|
- invoked.</para>
|
|
|
-
|
|
|
- <para>You may have noticed we have declared two
|
|
|
- <literal>HttpSessionContextIntegrationFilter</literal>s in the filter
|
|
|
- chain (<literal>ASC</literal> is short for
|
|
|
- <literal>allowSessionCreation</literal>, a property of
|
|
|
- <literal>HttpSessionContextIntegrationFilter</literal>). As web
|
|
|
- services will never present a <literal>jsessionid</literal> on future
|
|
|
- requests, creating <literal>HttpSession</literal>s for such user
|
|
|
- agents would be wasteful. If you had a high-volume application which
|
|
|
- required maximum scalability, we recommend you use the approach shown
|
|
|
- above. For smaller applications, using a single
|
|
|
- <literal>HttpSessionContextIntegrationFilter</literal> (with its
|
|
|
- default <literal>allowSessionCreation</literal> as
|
|
|
- <literal>true</literal>) would likely be sufficient.</para>
|
|
|
-
|
|
|
- <para>In relation to lifecycle issues, the
|
|
|
- <literal>FilterChainProxy</literal> will always delegate
|
|
|
- <literal>init(FilterConfig)</literal> and <literal>destroy()</literal>
|
|
|
- methods through to the underlaying <literal>Filter</literal>s if such
|
|
|
- methods are called against <literal>FilterChainProxy</literal> itself.
|
|
|
- In this case, <literal>FilterChainProxy</literal> guarantees to only
|
|
|
- initialize and destroy each <literal>Filter</literal> once,
|
|
|
- irrespective of how many times it is declared by the
|
|
|
- <literal>FilterInvocationDefinitionSource</literal>. You control the
|
|
|
- overall choice as to whether these methods are called or not via the
|
|
|
- <literal>lifecycle</literal> initialization parameter of the
|
|
|
- <literal>FilterToBeanProxy</literal> that proxies
|
|
|
- <literal>FilterChainProxy</literal>. As discussed above, by default
|
|
|
- any servlet container lifecycle invocations are not delegated through
|
|
|
- to <literal>FilterChainProxy</literal>.</para>
|
|
|
-
|
|
|
- <para>The order that filters are defined in <literal>web.xml</literal>
|
|
|
- is very important. Irrespective of which filters you are actually
|
|
|
- using, the order of the <literal><filter-mapping></literal>s
|
|
|
- should be as follows:</para>
|
|
|
-
|
|
|
- <orderedlist>
|
|
|
- <listitem>
|
|
|
- <para><literal>ChannelProcessingFilter</literal>, because it might
|
|
|
- need to redirect to a different protocol</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>ConcurrentSessionFilter</literal>, because it
|
|
|
- doesn't use any <literal>SecurityContextHolder</literal>
|
|
|
- functionality but needs to update the
|
|
|
- <literal>SessionRegistry</literal> to reflect ongoing requests
|
|
|
- from the principal</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>HttpSessionContextIntegrationFilter</literal>, so a
|
|
|
- <literal>SecurityContext</literal> can be setup in the
|
|
|
- <literal>SecurityContextHolder</literal> at the beginning of a web
|
|
|
- request, and any changes to the <literal>SecurityContext</literal>
|
|
|
- can be copied to the <literal>HttpSession</literal> when the web
|
|
|
- request ends (ready for use with the next web request)</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Authentication processing mechanisms -
|
|
|
- <literal>AuthenticationProcessingFilter</literal>,
|
|
|
- <literal>CasProcessingFilter</literal>,
|
|
|
- <literal>BasicProcessingFilter, HttpRequestIntegrationFilter,
|
|
|
- JbossIntegrationFilter</literal> etc - so that the
|
|
|
- <literal>SecurityContextHolder</literal> can be modified to
|
|
|
- contain a valid <literal>Authentication</literal> request
|
|
|
- token</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The
|
|
|
- <literal>SecurityContextHolderAwareRequestFilter</literal>, if you
|
|
|
- are using it to install an Acegi Security aware
|
|
|
- <literal>HttpServletRequestWrapper</literal> into your servlet
|
|
|
- container</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>RememberMeProcessingFilter</literal>, so that if no
|
|
|
- earlier authentication processing mechanism updated the
|
|
|
- <literal>SecurityContextHolder</literal>, and the request presents
|
|
|
- a cookie that enables remember-me services to take place, a
|
|
|
- suitable remembered
|
|
|
- <literal><literal>Authentication</literal></literal> object will
|
|
|
- be put there</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>AnonymousProcessingFilter</literal>, so that if no
|
|
|
- earlier authentication processing mechanism updated the
|
|
|
- <literal>SecurityContextHolder</literal>, an anonymous
|
|
|
- <literal>Authentication</literal> object will be put there</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>ExceptionTranslationFilter</literal>, to catch any
|
|
|
- Acegi Security exceptions so that either a HTTP error response can
|
|
|
- be returned or an appropriate
|
|
|
- <literal>AuthenticationEntryPoint</literal> can be launched</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>FilterSecurityInterceptor</literal>, to protect web
|
|
|
- URIs</para>
|
|
|
- </listitem>
|
|
|
- </orderedlist>
|
|
|
-
|
|
|
- <para>All of the above filters use
|
|
|
- <literal>FilterToBeanProxy</literal> or
|
|
|
- <literal>FilterChainProxy</literal>. It is recommended that a single
|
|
|
- <literal>FilterToBeanProxy</literal> proxy through to a single
|
|
|
- <literal>FilterChainProxy</literal> for each application, with that
|
|
|
- <literal>FilterChainProxy</literal> defining all of Acegi Security
|
|
|
- <literal>Filter</literal>s.</para>
|
|
|
-
|
|
|
- <para>If you're using SiteMesh, ensure Acegi Security filters execute
|
|
|
- before the SiteMesh filters are called. This enables the
|
|
|
- <literal>SecurityContextHolder</literal> to be populated in time for
|
|
|
- use by SiteMesh decorators</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="channel-security">
|
|
|
- <title>Channel Security</title>
|
|
|
-
|
|
|
- <sect1 id="channel-security-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>In addition to coordinating the authentication and authorization
|
|
|
- requirements of your application, Acegi Security is also able to
|
|
|
- ensure unauthenticated web requests have certain properties. These
|
|
|
- properties may include being of a particular transport type, having a
|
|
|
- particular <literal>HttpSession</literal> attribute set and so on. The
|
|
|
- most common requirement is for your web requests to be received using
|
|
|
- a particular transport protocol, such as HTTPS.</para>
|
|
|
-
|
|
|
- <para>An important issue in considering transport security is that of
|
|
|
- session hijacking. Your web container manages a
|
|
|
- <literal>HttpSession</literal> by reference to a
|
|
|
- <literal>jsessionid</literal> that is sent to user agents either via a
|
|
|
- cookie or URL rewriting. If the <literal>jsessionid</literal> is ever
|
|
|
- sent over HTTP, there is a possibility that session identifier can be
|
|
|
- intercepted and used to impersonate the user after they complete the
|
|
|
- authentication process. This is because most web containers maintain
|
|
|
- the same session identifier for a given user, even after they switch
|
|
|
- from HTTP to HTTPS pages.</para>
|
|
|
-
|
|
|
- <para>If session hijacking is considered too significant a risk for
|
|
|
- your particular application, the only option is to use HTTPS for every
|
|
|
- request. This means the <literal>jsessionid</literal> is never sent
|
|
|
- across an insecure channel. You will need to ensure your
|
|
|
- <literal>web.xml</literal>-defined
|
|
|
- <literal><welcome-file></literal> points to a HTTPS location,
|
|
|
- and the application never directs the user to a HTTP location. Acegi
|
|
|
- Security provides a solution to assist with the latter.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="channel-security-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>To utilise Acegi Security's channel security services, add the
|
|
|
- following lines to <literal>web.xml</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<filter>
|
|
|
- <filter-name>Acegi Channel Processing Filter</filter-name>
|
|
|
- <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
|
|
|
- <init-param>
|
|
|
- <param-name>targetClass</param-name>
|
|
|
- <param-value>org.acegisecurity.securechannel.ChannelProcessingFilter</param-value>
|
|
|
- </init-param>
|
|
|
-</filter>
|
|
|
-
|
|
|
-<filter-mapping>
|
|
|
- <filter-name>Acegi Channel Processing Filter</filter-name>
|
|
|
- <url-pattern>/*</url-pattern>
|
|
|
-</filter-mapping>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>As usual when running <literal>FilterToBeanProxy</literal>, you
|
|
|
- will also need to configure the filter in your application
|
|
|
- context:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="channelProcessingFilter" class="org.acegisecurity.securechannel.ChannelProcessingFilter">
|
|
|
- <property name="channelDecisionManager"><ref bean="channelDecisionManager"/></property>
|
|
|
- <property name="filterInvocationDefinitionSource">
|
|
|
- <value>
|
|
|
- CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
|
|
|
- \A/secure/.*\Z=REQUIRES_SECURE_CHANNEL
|
|
|
- \A/acegilogin.jsp.*\Z=REQUIRES_SECURE_CHANNEL
|
|
|
- \A/j_acegi_security_check.*\Z=REQUIRES_SECURE_CHANNEL
|
|
|
- \A.*\Z=REQUIRES_INSECURE_CHANNEL
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="channelDecisionManager" class="org.acegisecurity.securechannel.ChannelDecisionManagerImpl">
|
|
|
- <property name="channelProcessors">
|
|
|
- <list>
|
|
|
- <ref bean="secureChannelProcessor"/>
|
|
|
- <ref bean="insecureChannelProcessor"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="secureChannelProcessor" class="org.acegisecurity.securechannel.SecureChannelProcessor"/>
|
|
|
-<bean id="insecureChannelProcessor" class="org.acegisecurity.securechannel.InsecureChannelProcessor"/>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>Like <literal>FilterSecurityInterceptor</literal>, Apache Ant
|
|
|
- style paths are also supported by the
|
|
|
- <literal>ChannelProcessingFilter</literal>.</para>
|
|
|
-
|
|
|
- <para>The <literal>ChannelProcessingFilter</literal> operates by
|
|
|
- filtering all web requests and determining the configuration
|
|
|
- attributes that apply. It then delegates to the
|
|
|
- <literal>ChannelDecisionManager</literal>. The default implementation,
|
|
|
- <literal>ChannelDecisionManagerImpl</literal>, should suffice in most
|
|
|
- cases. It simply delegates through the list of configured
|
|
|
- <literal>ChannelProcessor</literal> instances. A
|
|
|
- <literal>ChannelProcessor</literal> will review the request, and if it
|
|
|
- is unhappy with the request (eg it was received across the incorrect
|
|
|
- transport protocol), it will perform a redirect, throw an exception or
|
|
|
- take whatever other action is appropriate.</para>
|
|
|
-
|
|
|
- <para>Included with Acegi Security are two concrete
|
|
|
- <literal>ChannelProcessor</literal> implementations:
|
|
|
- <literal>SecureChannelProcessor</literal> ensures requests with a
|
|
|
- configuration attribute of <literal>REQUIRES_SECURE_CHANNEL</literal>
|
|
|
- are received over HTTPS, whilst
|
|
|
- <literal>InsecureChannelProcessor</literal> ensures requests with a
|
|
|
- configuration attribute of
|
|
|
- <literal>REQUIRES_INSECURE_CHANNEL</literal> are received over HTTP.
|
|
|
- Both implementations delegate to a
|
|
|
- <literal>ChannelEntryPoint</literal> if the required transport
|
|
|
- protocol is not used. The two <literal>ChannelEntryPoint</literal>
|
|
|
- implementations included with Acegi Security simply redirect the
|
|
|
- request to HTTP and HTTPS as appropriate. Appropriate defaults are
|
|
|
- assigned to the <literal>ChannelProcessor</literal> implementations
|
|
|
- for the configuration attribute keywords they respond to and the
|
|
|
- <literal>ChannelEntryPoint</literal> they delegate to, although you
|
|
|
- have the ability to override these using the application
|
|
|
- context.</para>
|
|
|
-
|
|
|
- <para>Note that the redirections are absolute (eg
|
|
|
- <literal>http://www.company.com:8080/app/page</literal>), not relative
|
|
|
- (eg <literal>/app/page</literal>). During testing it was discovered
|
|
|
- that Internet Explorer 6 Service Pack 1 has a bug whereby it does not
|
|
|
- respond correctly to a redirection instruction which also changes the
|
|
|
- port to use. Accordingly, absolute URLs are used in conjunction with
|
|
|
- bug detection logic in the <literal>PortResolverImpl</literal> that is
|
|
|
- wired up by default to many Acegi Security beans. Please refer to the
|
|
|
- JavaDocs for <literal>PortResolverImpl</literal> for further
|
|
|
- details.</para>
|
|
|
-
|
|
|
- <para>You should note that using a secure channel is recommended if
|
|
|
- usernames and passwords are to be kept secure during the login
|
|
|
- process. If you do decide to use
|
|
|
- <literal>ChannelProcessingFilter</literal> with form-based login,
|
|
|
- please ensure that your login page is set to
|
|
|
- <literal>REQUIRES_SECURE_CHANNEL</literal>, and that the
|
|
|
- <literal>AuthenticationProcessingFilterEntryPoint.forceHttps</literal>
|
|
|
- property is <literal>true</literal>.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="channel-security-conclusion">
|
|
|
- <title>Conclusion</title>
|
|
|
-
|
|
|
- <para>Once configured, using the channel security filter is very easy.
|
|
|
- Simply request pages without regard to the protocol (ie HTTP or HTTPS)
|
|
|
- or port (eg 80, 8080, 443, 8443 etc). Obviously you'll still need a
|
|
|
- way of making the initial request (probably via the
|
|
|
- <literal>web.xml</literal> <literal><welcome-file></literal> or
|
|
|
- a well-known home page URL), but once this is done the filter will
|
|
|
- perform redirects as defined by your application context.</para>
|
|
|
-
|
|
|
- <para>You can also add your own <literal>ChannelProcessor</literal>
|
|
|
- implementations to the <literal>ChannelDecisionManagerImpl</literal>.
|
|
|
- For example, you might set a <literal>HttpSession</literal> attribute
|
|
|
- when a human user is detected via a "enter the contents of this
|
|
|
- graphic" procedure. Your <literal>ChannelProcessor</literal> would
|
|
|
- respond to say <literal>REQUIRES_HUMAN_USER</literal> configuration
|
|
|
- attributes and redirect to an appropriate entry point to start the
|
|
|
- human user validation process if the <literal>HttpSession</literal>
|
|
|
- attribute is not currently set.</para>
|
|
|
-
|
|
|
- <para>To decide whether a security check belongs in a
|
|
|
- <literal>ChannelProcessor</literal> or an
|
|
|
- <literal>AccessDecisionVoter</literal>, remember that the former is
|
|
|
- designed to handle unauthenticated requests, whilst the latter is
|
|
|
- designed to handle authenticated requests. The latter therefore has
|
|
|
- access to the granted authorities of the authenticated principal. In
|
|
|
- addition, problems detected by a <literal>ChannelProcessor</literal>
|
|
|
- will generally cause a HTTP/HTTPS redirection so its requirements can
|
|
|
- be met, whilst problems detected by an
|
|
|
- <literal>AccessDecisionVoter</literal> will ultimately result in an
|
|
|
- <literal>AccessDeniedException</literal> (depending on the governing
|
|
|
- <literal>AccessDecisionManager</literal>).</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="taglib">
|
|
|
- <title>Tag Libraries</title>
|
|
|
-
|
|
|
- <sect1 id="taglib-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Acegi Security comes bundled with several JSP tag libraries that
|
|
|
- eases JSP writing. The tag libraries are known as
|
|
|
- <literal>authz</literal> and provide a range of different
|
|
|
- services.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="taglib-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>All taglib classes are included in the core
|
|
|
- <literal>acegi-security-xx.jar</literal> file, with the
|
|
|
- <literal>authz.tld</literal> located in the JAR's
|
|
|
- <literal>META-INF</literal> directory. This means for JSP 1.2+ web
|
|
|
- containers you can simply include the JAR in the WAR's
|
|
|
- <literal>WEB-INF/lib</literal> directory and it will be available. If
|
|
|
- you're using a JSP 1.1 container, you'll need to declare the JSP
|
|
|
- taglib in your <literal>web.xml file</literal>, and include
|
|
|
- <literal>authz.tld</literal> in the <literal>WEB-INF/lib</literal>
|
|
|
- directory. The following fragment is added to
|
|
|
- <literal>web.xml</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting><taglib>
|
|
|
- <taglib-uri>http://acegisecurity.org/authz</taglib-uri>
|
|
|
- <taglib-location>/WEB-INF/authz.tld</taglib-location>
|
|
|
-</taglib> </programlisting></para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="taglib-usage">
|
|
|
- <title>Usage</title>
|
|
|
-
|
|
|
- <para>Now that you've configured the tag libraries, refer to the
|
|
|
- individual reference guide sections for details on how to use
|
|
|
- them.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
- </part>
|
|
|
-
|
|
|
- <part id="authentication">
|
|
|
- <title>Authentication</title>
|
|
|
-
|
|
|
- <partintro>
|
|
|
- <para>In this part of the reference guide we will examine individual
|
|
|
- authentication mechanisms and their corresponding
|
|
|
- <literal>AuthenticationProvider</literal>s. We'll also look at how to
|
|
|
- configure authentication more generally, including if you have several
|
|
|
- authentication approaches that need to be chained together.</para>
|
|
|
- </partintro>
|
|
|
-
|
|
|
- <chapter id="authentication-common-auth-services">
|
|
|
- <title>Common Authentication Services</title>
|
|
|
-
|
|
|
- <sect1 id="mechanisms-providers-entry-points">
|
|
|
- <title>Mechanisms, Providers and Entry Points</title>
|
|
|
-
|
|
|
- <para>If you're using Acegi Security-provided authentication
|
|
|
- approaches, you'll usually need to configure a web filter, together
|
|
|
- with an <literal>AuthenticationProvider</literal> and
|
|
|
- <literal>AuthenticationEntryPoint</literal>. In this section we are
|
|
|
- going to explore an example application that needs to support both
|
|
|
- form-based authentication (ie so a nice HTML page is presented to a
|
|
|
- user for them to login) plus BASIC authentication (ie so a web service
|
|
|
- or similar can access protected resources).</para>
|
|
|
-
|
|
|
- <para>In the web.xml, this application will need a single Acegi
|
|
|
- Security filter in order to use the FilterChainProxy. Nearly every
|
|
|
- Acegi Security application will have such an entry, and it looks like
|
|
|
- this:</para>
|
|
|
-
|
|
|
- <para><programlisting><filter>
|
|
|
- <filter-name>Acegi Filter Chain Proxy</filter-name>
|
|
|
- <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
|
|
|
- <init-param>
|
|
|
- <param-name>targetClass</param-name>
|
|
|
- <param-value>org.acegisecurity.util.FilterChainProxy</param-value>
|
|
|
- </init-param>
|
|
|
-</filter>
|
|
|
-
|
|
|
-<filter-mapping>
|
|
|
- <filter-name>Acegi Filter Chain Proxy</filter-name>
|
|
|
- <url-pattern>/*</url-pattern>
|
|
|
-</filter-mapping></programlisting></para>
|
|
|
-
|
|
|
- <para>The above declarations will cause every web request to be passed
|
|
|
- through to Acegi Security's FilterChainProxy. As explained in the
|
|
|
- filters section of this reference guide, the FilterChainProxy is a
|
|
|
- generally-useful class that enables web requests to be passed to
|
|
|
- different filters based on the URL patterns. Those delegated filters
|
|
|
- are managed inside the application context, so they can benefit from
|
|
|
- dependency injection. Let's have a look at what the FilterChainProxy
|
|
|
- bean definition would look like inside your application
|
|
|
- context:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="filterChainProxy" class="org.acegisecurity.util.FilterChainProxy">
|
|
|
- <property name="filterInvocationDefinitionSource">
|
|
|
- <value>
|
|
|
- CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
|
|
|
- PATTERN_TYPE_APACHE_ANT
|
|
|
- /**=httpSessionContextIntegrationFilter,logoutFilter,authenticationProcessingFilter,basicProcessingFilter,securityContextHolderAwareRequestFilter,rememberMeProcessingFilter,anonymousProcessingFilter,switchUserProcessingFilter,exceptionTranslationFilter,filterInvocationInterceptor
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean></programlisting></para>
|
|
|
-
|
|
|
- <para>Internally Acegi Security will use a
|
|
|
- <literal>PropertyEditor</literal> to convert the string presented in
|
|
|
- the above XML fragment into a
|
|
|
- <literal>FilterInvocationDefinitionSource</literal> object. What's
|
|
|
- important to note at this stage is that a series of filters will be
|
|
|
- run - in the order specified by the declaration - and each of those
|
|
|
- filters are actually the <literal><bean id></literal> of another
|
|
|
- bean inside the application context. So, in our case some extra beans
|
|
|
- will also appear in the application context, and they'll be named
|
|
|
- <literal>httpSessionContextIntegrationFilter</literal>,
|
|
|
- <literal>logoutFilter</literal> and so on. The order that the filters
|
|
|
- should appear is discussed in the filters section of the reference
|
|
|
- guide - although they are correct in the above example.</para>
|
|
|
-
|
|
|
- <para>In our example we have the
|
|
|
- <literal>AuthenticationProcessingFilter</literal> and
|
|
|
- <literal>BasicProcessingFilter</literal> being used. These are the
|
|
|
- "authentication mechanisms" that respond to form-based authentication
|
|
|
- and BASIC HTTP header-based authentication respectively (we discussed
|
|
|
- the role of authentication mechanisms earlier in this reference
|
|
|
- guide). If you weren't using form or BASIC authentication, neither of
|
|
|
- these beans would be defined. You'd instead define filters applicable
|
|
|
- to your desired authentication environment, such as
|
|
|
- <literal>DigestProcessingFilter</literal> or
|
|
|
- <literal>CasProcessingFilter</literal>. Refer to the individual
|
|
|
- chapters of this part of the reference guide to learn how to configure
|
|
|
- each of these authentication mechanisms.</para>
|
|
|
-
|
|
|
- <para>Recall that
|
|
|
- <literal>HttpSessionContextIntegrationFilter</literal> keeps the
|
|
|
- contents of the <literal>SecurityContext</literal> between invocations
|
|
|
- inside a HTTP session. This means the authentication mechanisms are
|
|
|
- only used once, being when the principal initially tries to
|
|
|
- authenticate. The rest of the time the authentication mechanisms sit
|
|
|
- there and silently pass the request through to the next filter in the
|
|
|
- chain. That is a practical requirement due to the fact that few
|
|
|
- authentication approaches present credentials on each and every call
|
|
|
- (BASIC authentication being a notable exception), but what happens if
|
|
|
- a principal's account gets cancelled or disabled or otherwise changed
|
|
|
- (eg an increase or decrease in <literal>GrantedAuthority[]</literal>s)
|
|
|
- after the initial authentication step? Let's look at how that is
|
|
|
- handled now.</para>
|
|
|
-
|
|
|
- <para>The major authorization provider for secure objects has
|
|
|
- previously been introduced as
|
|
|
- <literal>AbstractSecurityInterceptor</literal>. This class needs to
|
|
|
- have access to an <literal>AuthenticationManager</literal>. It also
|
|
|
- has configurable settings to indicate whether an
|
|
|
- <literal>Authentication</literal> object should be re-authenticated on
|
|
|
- each secure object invocation. By default it just accepts any
|
|
|
- <literal>Authentication</literal> inside the
|
|
|
- <literal>SecurityContextHolder</literal> is authenticated if
|
|
|
- <literal>Authentication.isAuthenticated()</literal> returns true. This
|
|
|
- is great for performance, but not ideal if you want to ensure
|
|
|
- up-to-the-moment authentication validity. For such cases you'll
|
|
|
- probably want to set the
|
|
|
- <literal>AbstractSecurityInterceptor.alwaysReauthenticate</literal>
|
|
|
- property to true.</para>
|
|
|
-
|
|
|
- <para>You might be asking yourself, "what's this
|
|
|
- <literal>AuthenticationManager</literal>?". We haven't explored it
|
|
|
- before, but we have discussed the concept of an
|
|
|
- <literal>AuthenticationProvider</literal>. Quite simply, an
|
|
|
- AuthenticationManager is responsible for passing requests through a
|
|
|
- chain of AuthenticationProviders. It's a little like the filter chain
|
|
|
- we discussed earlier, although there are some differences. There is
|
|
|
- only one AuthenticationManager implementation shipped with Acegi
|
|
|
- Security, so let's look at how it's configured for the example we're
|
|
|
- using in this chapter:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="authenticationManager" class="org.acegisecurity.providers.ProviderManager">
|
|
|
- <property name="providers">
|
|
|
- <list>
|
|
|
- <ref local="daoAuthenticationProvider"/>
|
|
|
- <ref local="anonymousAuthenticationProvider"/>
|
|
|
- <ref local="rememberMeAuthenticationProvider"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean></programlisting></para>
|
|
|
-
|
|
|
- <para>It's probably worth mentioning at this point that your
|
|
|
- authentication mechanisms (which are usually filters) are also
|
|
|
- injected with a reference to the
|
|
|
- <literal>AuthenticationManager</literal>. So both
|
|
|
- <literal>AbstractSecurityInterceptor</literal> as well as the
|
|
|
- authentication mechanisms will use the above
|
|
|
- <literal>ProviderManager</literal> to poll a list of
|
|
|
- <literal>AuthenticationProvider</literal>s.</para>
|
|
|
-
|
|
|
- <para>In our example we have three providers. They are tried in the
|
|
|
- order shown (which is implied by the use of a <literal>List</literal>
|
|
|
- instead of a <literal>Set</literal>), with each provider able to
|
|
|
- attempt authentication, or skip authentication by simply returning
|
|
|
- <literal>null</literal>. If all implementations return null, the
|
|
|
- <literal>ProviderManager</literal> will throw a suitable exception. If
|
|
|
- you're interested in learning more about chaining providers, please
|
|
|
- refer to the <literal>ProviderManager</literal> JavaDocs.</para>
|
|
|
-
|
|
|
- <para>The providers to use will sometimes be interchangeable with the
|
|
|
- authentication mechanisms, whilst at other times they will depend on a
|
|
|
- specific authentication mechanism. For example, the
|
|
|
- <literal>DaoAuthenticationProvider</literal> just needs a string-based
|
|
|
- username and password. Various authentication mechanisms result in the
|
|
|
- collection of a string-based username and password, including (but not
|
|
|
- limited to) BASIC and form authentication. Equally, some
|
|
|
- authentication mechanisms create an authentication request object
|
|
|
- which can only be interpreted by a single type of
|
|
|
- <literal>AuthenticationProvider</literal>. An example of this
|
|
|
- one-to-one mapping would be JA-SIG CAS, which uses the notion of a
|
|
|
- service ticket which can therefore only be authenticated by
|
|
|
- <literal>CasAuthenticationProvider</literal>. A further example of a
|
|
|
- one-to-one mapping would be the LDAP authentication mechanism, which
|
|
|
- can only be processed an the
|
|
|
- <literal>LdapAuthenticationProvider</literal>. The specifics of such
|
|
|
- relationships are detailed in the JavaDocs for each class, plus the
|
|
|
- authentication approach-specific chapters of this reference guide. You
|
|
|
- need not be terribly concerned about this implementation detail,
|
|
|
- because if you forget to register a suitable provider, you'll simply
|
|
|
- receive a <literal>ProviderNotFoundException</literal> when an attempt
|
|
|
- to authenticate is made.</para>
|
|
|
-
|
|
|
- <para>After configuring the correct authentication mechanisms in the
|
|
|
- <literal>FilterChainProxy</literal>, and ensuring that a corresponding
|
|
|
- <literal>AuthenticationProvider</literal> is registered in the
|
|
|
- <literal>ProviderManager</literal>, your last step is to configure an
|
|
|
- <literal>AuthenticationEntryPoint</literal>. Recall that earlier we
|
|
|
- discussed the role of <literal>ExceptionTranslationFilter</literal>,
|
|
|
- which is used when HTTP-based requests should receive back a HTTP
|
|
|
- header or HTTP redirect in order to start authentication. Continuing
|
|
|
- on with our earlier example:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="exceptionTranslationFilter" class="org.acegisecurity.ui.ExceptionTranslationFilter">
|
|
|
- <property name="authenticationEntryPoint"><ref local="authenticationProcessingFilterEntryPoint"/></property>
|
|
|
- <property name="accessDeniedHandler">
|
|
|
- <bean class="org.acegisecurity.ui.AccessDeniedHandlerImpl">
|
|
|
- <property name="errorPage" value="/accessDenied.jsp"/>
|
|
|
- </bean>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="authenticationProcessingFilterEntryPoint" class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint">
|
|
|
- <property name="loginFormUrl"><value>/acegilogin.jsp</value></property>
|
|
|
- <property name="forceHttps"><value>false</value></property>
|
|
|
-</bean></programlisting></para>
|
|
|
-
|
|
|
- <para>Notice that the <literal>ExceptionTranslationFilter</literal>
|
|
|
- requires two collaborators. The first,
|
|
|
- <literal>AccessDeniedHandlerImpl</literal>, uses a
|
|
|
- <literal>RequestDispatcher</literal> forward to display the specified
|
|
|
- access denied error page. We use a forward so that the
|
|
|
- <literal>SecurityContextHolder</literal> still contains details of the
|
|
|
- principal, which may be useful for display to the user (in old
|
|
|
- releases of Acegi Security we relied upon the servlet container to
|
|
|
- handle a 403 error message, which lacked this useful contextual
|
|
|
- information). <literal>AccessDeniedHandlerImpl</literal> will also set
|
|
|
- the HTTP header to 403, which is the official error code to indicate
|
|
|
- access denied. In the case of the
|
|
|
- <literal>AuthentionEntryPoint</literal>, here we're setting what
|
|
|
- action we would like taken when an unauthenticated principal attempts
|
|
|
- to perform a protected operation. Because in our example we're going
|
|
|
- to be using form-based authentication, we specify
|
|
|
- <literal>AuthenticationProcessinFilterEntryPoint</literal> and the URL
|
|
|
- of the login page. Your application will usually only have one entry
|
|
|
- point, and most authentication approaches define their own specific
|
|
|
- <literal>AuthenticationEntryPoint</literal>. Details of which entry
|
|
|
- point to use for each authentication approach is discussed in the
|
|
|
- authentication approach-specific chapters of this reference
|
|
|
- guide.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="userdetails-and-associated-types">
|
|
|
- <title>UserDetails and Associated Types</title>
|
|
|
-
|
|
|
- <para>As mentioned in the first part of the reference guide, most
|
|
|
- authentication providers take advantage of the
|
|
|
- <literal>UserDetails</literal> and
|
|
|
- <literal>UserDetailsService</literal> interfaces. The contract for
|
|
|
- this latter interface consists of a single method:</para>
|
|
|
-
|
|
|
- <para><programlisting>public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException, DataAccessException;</programlisting></para>
|
|
|
-
|
|
|
- <para>The returned <literal>UserDetails</literal> is an interface that
|
|
|
- provides getters that guarantee non-null provision of basic
|
|
|
- authentication information such as the username, password, granted
|
|
|
- authorities and whether the user is enabled or disabled. Most
|
|
|
- authentication providers will use a
|
|
|
- <literal>UserDetailsService</literal>, even if the username and
|
|
|
- password are not actually used as part of the authentication decision.
|
|
|
- Generally such provider will be using the returned
|
|
|
- <literal>UserDetails</literal> object just for its
|
|
|
- <literal>GrantedAuthority[]</literal> information, because some other
|
|
|
- system (like LDAP or X509 or CAS etc) has undertaken the
|
|
|
- responsibility of actually validating the credentials.</para>
|
|
|
-
|
|
|
- <para>A single concrete implementation of
|
|
|
- <literal>UserDetails</literal> is provided with Acegi Security, being
|
|
|
- the <literal>User</literal> class. Acegi Security users will need to
|
|
|
- decide when writing their <literal>UserDetailsService</literal> what
|
|
|
- concrete <literal>UserDetails</literal> class to return. In most cases
|
|
|
- <literal>User</literal> will be used directly or subclassed, although
|
|
|
- special circumstances (such as object relational mappers) may require
|
|
|
- users to write their own <literal>UserDetails</literal> implementation
|
|
|
- from scratch. This is not such an unusual situation, and users should
|
|
|
- not hesitate to simply return their normal domain object that
|
|
|
- represents a user of the system. This is especially common given that
|
|
|
- <literal>UserDetails</literal> is often used to store additional
|
|
|
- principal-related properties (such as their telephone number and email
|
|
|
- address), so that they can be easily used by web views.</para>
|
|
|
-
|
|
|
- <para>Given <literal>UserDetailsService</literal> is so simple to
|
|
|
- implement, it should be easy for users to retrieve authentication
|
|
|
- information using a persistence strategy of their choice. Having said
|
|
|
- that, Acegi Security does include a couple of useful base
|
|
|
- implementations, which we'll look at below.</para>
|
|
|
-
|
|
|
- <sect2 id="in-memory-service">
|
|
|
- <title>In-Memory Authentication</title>
|
|
|
-
|
|
|
- <para>Whilst it is easy to use create a custom
|
|
|
- <literal>UserDetailsService</literal> implementation that extracts
|
|
|
- information from a persistence engine of choice, many applications
|
|
|
- do not require such complexity. This is particularly true if you're
|
|
|
- undertaking a rapid prototype or just starting integrating Acegi
|
|
|
- Security, when you don't really want to spend time configuring
|
|
|
- databases or writing <literal>UserDetailsService</literal>
|
|
|
- implementations. For this sort of situation, a simple option is to
|
|
|
- configure the <literal>InMemoryDaoImpl</literal>
|
|
|
- implementation:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="inMemoryDaoImpl" class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl">
|
|
|
- <property name="userMap">
|
|
|
- <value>
|
|
|
- marissa=koala,ROLE_TELLER,ROLE_SUPERVISOR
|
|
|
- dianne=emu,ROLE_TELLER
|
|
|
- scott=wombat,ROLE_TELLER
|
|
|
- peter=opal,disabled,ROLE_TELLER
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>In the above example, the <literal>userMap</literal> property
|
|
|
- contains each of the usernames, passwords, a list of granted
|
|
|
- authorities and an optional enabled/disabled keyword. Commas are
|
|
|
- used to delimit each token. The username must appear to the left of
|
|
|
- the equals sign, and the password must be the first token to the
|
|
|
- right of the equals sign. The <literal>enabled</literal> and
|
|
|
- <literal>disabled</literal> keywords (case insensitive) may appear
|
|
|
- in the second or any subsequent token. Any remaining tokens are
|
|
|
- treated as granted authorities, which are created as
|
|
|
- <literal>GrantedAuthorityImpl</literal> objects (this is just for
|
|
|
- your reference - most application don't need custom
|
|
|
- <literal>GrantedAuthority</literal> implementations, so using the
|
|
|
- default implementation in this manner is just fine). Note that if a
|
|
|
- user has no password and/or no granted authorities, the user will
|
|
|
- not be created in the in-memory authentication repository.</para>
|
|
|
-
|
|
|
- <para><literal>InMemoryDaoImpl</literal> also offers a
|
|
|
- <literal>setUserProperties(Properties)</literal> method, which
|
|
|
- allows you to externalise the
|
|
|
- <literal>java.util.Properties</literal> in another Spring configured
|
|
|
- bean or an external properties file. You might like to use Spring's
|
|
|
- <literal>PropertiesFactoryBean</literal>, which is useful for
|
|
|
- loading such external properties files. This setter might prove
|
|
|
- useful for simple applications that have a larger number of users,
|
|
|
- or deployment-time configuration changes, but do not wish to use a
|
|
|
- full database for handling authentication details.</para>
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="jdbc-service">
|
|
|
- <title>JDBC Authentication</title>
|
|
|
-
|
|
|
- <para>Acegi Security also includes a
|
|
|
- <literal>UserDetailsService</literal> that can obtain authentication
|
|
|
- information from a JDBC data source. Internally Spring JDBC is used,
|
|
|
- so it avoids the complexity of a fully-featured object relational
|
|
|
- mapper (ORM) just to store user details. If your application does
|
|
|
- use an ORM tool, you might prefer to write a custom
|
|
|
- <literal>UserDetailsService</literal> to reuse the mapping files
|
|
|
- you've probably already created. Returning to
|
|
|
- <literal>JdbcDaoImpl</literal>, an example configuration is shown
|
|
|
- below:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="dataSource" class="org.springframework.jdbc.datasource.DriverManagerDataSource">
|
|
|
- <property name="driverClassName"><value>org.hsqldb.jdbcDriver</value></property>
|
|
|
- <property name="url"><value>jdbc:hsqldb:hsql://localhost:9001</value></property>
|
|
|
- <property name="username"><value>sa</value></property>
|
|
|
- <property name="password"><value></value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="jdbcDaoImpl" class="org.acegisecurity.userdetails.jdbc.JdbcDaoImpl">
|
|
|
- <property name="dataSource"><ref bean="dataSource"/></property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>You can use different relational database management systems
|
|
|
- by modifying the <literal>DriverManagerDataSource</literal> shown
|
|
|
- above. You can also use a global data source obtained from JNDI, as
|
|
|
- per normal Spring options. Irrespective of the database used and how
|
|
|
- a <literal>DataSource</literal> is obtained, a standard schema must
|
|
|
- be used as indicated in <literal>dbinit.txt</literal>. You can
|
|
|
- download this file from the Acegi Security web site.</para>
|
|
|
-
|
|
|
- <para>If you default schema is unsuitable for your needs,
|
|
|
- <literal>JdbcDaoImpl</literal> provides two properties that allow
|
|
|
- customisation of the SQL statements. You may also subclass the
|
|
|
- <literal>JdbcDaoImpl</literal> if further customisation is
|
|
|
- necessary. Please refer to the JavaDocs for details, although please
|
|
|
- note that the class is not intended for complex custom subclasses.
|
|
|
- If you have complex needs (such as a special schema or would like a
|
|
|
- certain <literal>UserDetails</literal> implementation returned),
|
|
|
- you'd be better off writing your own
|
|
|
- <literal>UserDetailsService</literal>. The base implementation
|
|
|
- provided with Acegi Security is intended for typical situations, and
|
|
|
- does not offer infinite configuration flexibility.</para>
|
|
|
- </sect2>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="concurrent-sessions">
|
|
|
- <title>Concurrent Session Handling</title>
|
|
|
-
|
|
|
- <para>Acegi Security is able to prevent a principal from concurrently
|
|
|
- authenticating to the same application more than a specified number of
|
|
|
- times. Many ISVs take advantage of this to enforce licensing, whilst
|
|
|
- network administrators like this feature because it helps prevent
|
|
|
- people from sharing login names. You can, for example, stop user
|
|
|
- "Batman" from logging onto the web application from two different
|
|
|
- sessions.</para>
|
|
|
-
|
|
|
- <para>To use concurrent session support, you'll need to add the
|
|
|
- following to <literal>web.xml</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting><listener>
|
|
|
- <listener-class>org.acegisecurity.ui.session.HttpSessionEventPublisher</listener-class>
|
|
|
-</listener> </programlisting></para>
|
|
|
-
|
|
|
- <para>In addition, you will need to add the
|
|
|
- <literal>org.acegisecurity.concurrent.ConcurrentSessionFilter</literal>
|
|
|
- to your <literal>FilterChainProxy</literal>. The
|
|
|
- ConcurrentSessionFilter requires two properties,
|
|
|
- <literal>sessionRegistry</literal>, which generally points to an
|
|
|
- instance of <literal>SessionRegistryImpl</literal>, and
|
|
|
- <literal>expiredUrl</literal>, which points to the page to display
|
|
|
- when a session has expired.</para>
|
|
|
-
|
|
|
- <para>The <literal>web.xml</literal>
|
|
|
- <literal>HttpSessionEventPublisher</literal> causes an
|
|
|
- <literal>ApplicationEvent</literal> to be published to the Spring
|
|
|
- <literal>ApplicationContext</literal> every time a
|
|
|
- <literal>HttpSession</literal> commences or terminates. This is
|
|
|
- critical, as it allows the <literal>SessionRegistryImpl</literal> to
|
|
|
- be notified when a session ends.</para>
|
|
|
-
|
|
|
- <para>You will also need to wire up the
|
|
|
- <literal>ConcurrentSessionControllerImpl</literal> and refer to it
|
|
|
- from your <literal>ProviderManager</literal> bean:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="authenticationManager" class="org.acegisecurity.providers.ProviderManager">
|
|
|
- <property name="providers">
|
|
|
- <!-- your providers go here -->
|
|
|
- </property>
|
|
|
- <property name="sessionController"><ref bean="concurrentSessionController"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="concurrentSessionController" class="org.acegisecurity.concurrent.ConcurrentSessionControllerImpl">
|
|
|
- <property name="maximumSessions"><value>1</value></property>
|
|
|
- <property name="sessionRegistry"><ref local="sessionRegistry"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="sessionRegistry" class="org.acegisecurity.concurrent.SessionRegistryImpl"/></programlisting></para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="authentication-taglibs">
|
|
|
- <title>Authentication Tag Libraries</title>
|
|
|
-
|
|
|
- <para><literal>AuthenticationTag</literal> is used to simply output a
|
|
|
- property of the current principal's
|
|
|
- <literal>Authentication.getPrincipal()</literal> object to the web
|
|
|
- page.</para>
|
|
|
-
|
|
|
- <para>The following JSP fragment illustrates how to use the
|
|
|
- <literal>AuthenticationTag</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting><authz:authentication operation="username"/></programlisting></para>
|
|
|
-
|
|
|
- <para>This tag would cause the principal's name to be output. Here we
|
|
|
- are assuming the <literal>Authentication.getPrincipal()</literal> is a
|
|
|
- <literal>UserDetails</literal> object, which is generally the case
|
|
|
- when using the typical
|
|
|
- <literal>DaoAuthenticationProvider</literal>.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="dao-provider">
|
|
|
- <title>DAO Authentication Provider</title>
|
|
|
-
|
|
|
- <sect1 id="dao-provider-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Acegi Security includes a production-quality
|
|
|
- <literal>AuthenticationProvider</literal> implementation called
|
|
|
- <literal>DaoAuthenticationProvider</literal>. This authentication
|
|
|
- provider is compatible with all of the authentication mechanisms that
|
|
|
- generate a <literal>UsernamePasswordAuthenticationToken</literal>, and
|
|
|
- is probably the most commonly used provider in the framework. Like
|
|
|
- most of the other authentication providers, the
|
|
|
- DaoAuthenticationProvider leverages a UserDetailsService in order to
|
|
|
- lookup the username, password and GrantedAuthority[]s. Unlike most of
|
|
|
- the other authentication providers that leverage UserDetailsService,
|
|
|
- this authentication provider actually requires the password to be
|
|
|
- presented, and the provider will actually evaluate the validity or
|
|
|
- otherwise of the password presented in an authentication request
|
|
|
- object.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="dao-provider-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>Aside from adding DaoAuthenticationProvider to your
|
|
|
- ProviderManager list (as discussed at the start of this part of the
|
|
|
- reference guide), and ensuring a suitable authentication mechanism is
|
|
|
- configured to present a UsernamePasswordAuthenticationToken, the
|
|
|
- configuration of the provider itself is rather simple:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="daoAuthenticationProvider" class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
|
|
|
- <property name="userDetailsService"><ref bean="inMemoryDaoImpl"/></property>
|
|
|
- <property name="saltSource"><ref bean="saltSource"/></property>
|
|
|
- <property name="passwordEncoder"><ref bean="passwordEncoder"/></property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>PasswordEncoder</literal> and
|
|
|
- <literal>SaltSource</literal> are optional. A
|
|
|
- <literal>PasswordEncoder</literal> provides encoding and decoding of
|
|
|
- passwords presented in the <literal>UserDetails</literal> object that
|
|
|
- is returned from the configured <literal>UserDetailsService</literal>.
|
|
|
- A <literal>SaltSource</literal> enables the passwords to be populated
|
|
|
- with a "salt", which enhances the security of the passwords in the
|
|
|
- authentication repository. <literal>PasswordEncoder</literal>
|
|
|
- implementations are provided with Acegi Security covering MD5, SHA and
|
|
|
- cleartext encodings. Two <literal>SaltSource</literal> implementations
|
|
|
- are also provided: <literal>SystemWideSaltSource</literal> which
|
|
|
- encodes all passwords with the same salt, and
|
|
|
- <literal>ReflectionSaltSource</literal>, which inspects a given
|
|
|
- property of the returned <literal>UserDetails</literal> object to
|
|
|
- obtain the salt. Please refer to the JavaDocs for further details on
|
|
|
- these optional features.</para>
|
|
|
-
|
|
|
- <para>In addition to the properties above, the
|
|
|
- <literal>DaoAuthenticationProvider</literal> supports optional caching
|
|
|
- of <literal>UserDetails</literal> objects. The
|
|
|
- <literal>UserCache</literal> interface enables the
|
|
|
- <literal>DaoAuthenticationProvider</literal> to place a
|
|
|
- <literal>UserDetails</literal> object into the cache, and retrieve it
|
|
|
- from the cache upon subsequent authentication attempts for the same
|
|
|
- username. By default the <literal>DaoAuthenticationProvider</literal>
|
|
|
- uses the <literal>NullUserCache</literal>, which performs no caching.
|
|
|
- A usable caching implementation is also provided,
|
|
|
- <literal>EhCacheBasedUserCache</literal>, which is configured as
|
|
|
- follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="daoAuthenticationProvider" class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
|
|
|
- <property name="userDetailsService"><ref bean="userDetailsService"/></property>
|
|
|
- <property name="userCache"><ref bean="userCache"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean">
|
|
|
- <property name="configLocation">
|
|
|
- <value>classpath:/ehcache-failsafe.xml</value>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="userCacheBackend" class="org.springframework.cache.ehcache.EhCacheFactoryBean">
|
|
|
- <property name="cacheManager">
|
|
|
- <ref local="cacheManager"/>
|
|
|
- </property>
|
|
|
- <property name="cacheName">
|
|
|
- <value>userCache</value>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="userCache" class="org.acegisecurity.providers.dao.cache.EhCacheBasedUserCache">
|
|
|
- <property name="cache"><ref local="userCacheBackend"/></property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>All Acegi Security EH-CACHE implementations (including
|
|
|
- <literal>EhCacheBasedUserCache</literal>) require an EH-CACHE
|
|
|
- <literal>Cache</literal> object. The <literal>Cache</literal> object
|
|
|
- can be obtained from wherever you like, although we recommend you use
|
|
|
- Spring's factory classes as shown in the above configuration. If using
|
|
|
- Spring's factory classes, please refer to the Spring documentation for
|
|
|
- further details on how to optimise the cache storage location, memory
|
|
|
- usage, eviction policies, timeouts etc.</para>
|
|
|
-
|
|
|
- <para>A design decision was made not to support account locking in the
|
|
|
- <literal>DaoAuthenticationProvider</literal>, as doing so would have
|
|
|
- increased the complexity of the <literal>UserDetailsService</literal>
|
|
|
- interface. For instance, a method would be required to increase the
|
|
|
- count of unsuccessful authentication attempts. Such functionality
|
|
|
- could be easily provided by leveraging the application event
|
|
|
- publishing features discussed below.</para>
|
|
|
-
|
|
|
- <para><literal>DaoAuthenticationProvider</literal> returns an
|
|
|
- <literal>Authentication</literal> object which in turn has its
|
|
|
- <literal>principal</literal> property set. The principal will be
|
|
|
- either a <literal>String</literal> (which is essentially the username)
|
|
|
- or a <literal>UserDetails</literal> object (which was looked up from
|
|
|
- the <literal>UserDetailsService</literal>). By default the
|
|
|
- <literal>UserDetails</literal> is returned, as this enables
|
|
|
- applications to add extra properties potentially of use in
|
|
|
- applications, such as the user's full name, email address etc. If
|
|
|
- using container adapters, or if your applications were written to
|
|
|
- operate with <literal>String</literal>s (as was the case for releases
|
|
|
- prior to Acegi Security 0.6), you should set the
|
|
|
- <literal>DaoAuthenticationProvider.forcePrincipalAsString</literal>
|
|
|
- property to <literal>true</literal> in your application context</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="jaas">
|
|
|
- <title>Java Authentication and Authorization Service (JAAS)
|
|
|
- Provider</title>
|
|
|
-
|
|
|
- <sect1 id="jaas-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Acegi Security provides a package able to delegate
|
|
|
- authentication requests to the Java Authentication and Authorization
|
|
|
- Service (JAAS). This package is discussed in detail below.</para>
|
|
|
-
|
|
|
- <para>Central to JAAS operation are login configuration files. To
|
|
|
- learn more about JAAS login configuration files, consult the JAAS
|
|
|
- reference documentation available from Sun Microsystems. We expect you
|
|
|
- to have a basic understanding of JAAS and its login configuration file
|
|
|
- syntax in order to understand this section.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="jaas-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>The <literal>JaasAuthenticationProvider</literal> attempts to
|
|
|
- authenticate a user’s principal and credentials through JAAS.</para>
|
|
|
-
|
|
|
- <para>Let’s assume we have a JAAS login configuration file,
|
|
|
- <literal>/WEB-INF/login.conf</literal>, with the following
|
|
|
- contents:</para>
|
|
|
-
|
|
|
- <para><programlisting>JAASTest {
|
|
|
- sample.SampleLoginModule required;
|
|
|
-};</programlisting></para>
|
|
|
-
|
|
|
- <para>Like all Acegi Security beans, the
|
|
|
- <literal>JaasAuthenticationProvider</literal> is configured via the
|
|
|
- application context. The following definitions would correspond to the
|
|
|
- above JAAS login configuration file:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="jaasAuthenticationProvider" class="org.acegisecurity.providers.jaas.JaasAuthenticationProvider">
|
|
|
- <property name="loginConfig">
|
|
|
- <value>/WEB-INF/login.conf</value>
|
|
|
- </property>
|
|
|
- <property name="loginContextName">
|
|
|
- <value>JAASTest</value>
|
|
|
- </property>
|
|
|
- <property name="callbackHandlers">
|
|
|
- <list>
|
|
|
- <bean class="org.acegisecurity.providers.jaas.JaasNameCallbackHandler"/>
|
|
|
- <bean class="org.acegisecurity.providers.jaas.JaasPasswordCallbackHandler"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
- <property name="authorityGranters">
|
|
|
- <list>
|
|
|
- <bean class="org.acegisecurity.providers.jaas.TestAuthorityGranter"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>CallbackHandler</literal>s and
|
|
|
- <literal>AuthorityGranter</literal>s are discussed below.</para>
|
|
|
-
|
|
|
- <sect2 id="jaas-callbackhandler">
|
|
|
- <title id="jaas-callback-handler">JAAS CallbackHandler</title>
|
|
|
-
|
|
|
- <para>Most JAAS <literal>LoginModule</literal>s require a callback
|
|
|
- of some sort. These callbacks are usually used to obtain the
|
|
|
- username and password from the user.</para>
|
|
|
-
|
|
|
- <para>In an Acegi Security deployment, Acegi Security is responsible
|
|
|
- for this user interaction (via the authentication mechanism). Thus,
|
|
|
- by the time the authentication request is delegated through to JAAS,
|
|
|
- Acegi Security's authentication mechanism will already have
|
|
|
- fully-populated an <literal>Authentication</literal> object
|
|
|
- containing all the information required by the JAAS
|
|
|
- <literal>LoginModule</literal>.</para>
|
|
|
-
|
|
|
- <para>Therefore, the JAAS package for Acegi Security provides two
|
|
|
- default callback handlers,
|
|
|
- <literal>JaasNameCallbackHandler</literal> and
|
|
|
- <literal>JaasPasswordCallbackHandler</literal>. Each of these
|
|
|
- callback handlers implement
|
|
|
- <literal>JaasAuthenticationCallbackHandler</literal>. In most cases
|
|
|
- these callback handlers can simply be used without understanding the
|
|
|
- internal mechanics.</para>
|
|
|
-
|
|
|
- <para>For those needing full control over the callback behavior,
|
|
|
- internally <literal>JaasAutheticationProvider</literal> wraps these
|
|
|
- <literal>JaasAuthenticationCallbackHandler</literal>s with an
|
|
|
- <literal>InternalCallbackHandler</literal>. The
|
|
|
- <literal>InternalCallbackHandler</literal> is the class that
|
|
|
- actually implements JAAS’ normal <literal>CallbackHandler</literal>
|
|
|
- interface. Any time that the JAAS <literal>LoginModule</literal> is
|
|
|
- used, it is passed a list of application context configured
|
|
|
- <literal>InternalCallbackHandler</literal>s. If the
|
|
|
- <literal>LoginModule</literal> requests a callback against the
|
|
|
- <literal>InternalCallbackHandler</literal>s, the callback is in-turn
|
|
|
- passed to the <literal>JaasAuthenticationCallbackHandler</literal>s
|
|
|
- being wrapped.</para>
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="jaas-authoritygranter">
|
|
|
- <title id="jaas-authority-granter">JAAS AuthorityGranter</title>
|
|
|
-
|
|
|
- <para>JAAS works with principals. Even "roles" are represented as
|
|
|
- principals in JAAS. Acegi Security, on the other hand, works with
|
|
|
- <literal>Authentication</literal> objects. Each
|
|
|
- <literal>Authentication</literal> object contains a single
|
|
|
- principal, and multiple <literal>GrantedAuthority</literal>[]s. To
|
|
|
- facilitate mapping between these different concepts, Acegi
|
|
|
- Security's JAAS package includes an
|
|
|
- <literal>AuthorityGranter</literal> interface.</para>
|
|
|
-
|
|
|
- <para>An <literal>AuthorityGranter</literal> is responsible for
|
|
|
- inspecting a JAAS principal and returning a
|
|
|
- <literal>String</literal>. The
|
|
|
- <literal>JaasAuthenticationProvider</literal> then creates a
|
|
|
- <literal>JaasGrantedAuthority</literal> (which implements Acegi
|
|
|
- Security’s <literal>GrantedAuthority</literal> interface) containing
|
|
|
- both the <literal>AuthorityGranter</literal>-returned
|
|
|
- <literal>String</literal> and the JAAS principal that the
|
|
|
- <literal>AuthorityGranter</literal> was passed. The
|
|
|
- <literal>JaasAuthenticationProvider</literal> obtains the JAAS
|
|
|
- principals by firstly successfully authenticating the user’s
|
|
|
- credentials using the JAAS <literal>LoginModule</literal>, and then
|
|
|
- accessing the <literal>LoginContext</literal> it returns. A call to
|
|
|
- <literal>LoginContext.getSubject().getPrincipals()</literal> is
|
|
|
- made, with each resulting principal passed to each
|
|
|
- <literal>AuthorityGranter</literal> defined against the
|
|
|
- <literal>JaasAuthenticationProvider.setAuthorityGranters(List)</literal>
|
|
|
- property.</para>
|
|
|
-
|
|
|
- <para>Acegi Security does not include any production
|
|
|
- <literal>AuthorityGranter</literal>s given that every JAAS principal
|
|
|
- has an implementation-specific meaning. However, there is a
|
|
|
- <literal>TestAuthorityGranter</literal> in the unit tests that
|
|
|
- demonstrates a simple <literal>AuthorityGranter</literal>
|
|
|
- implementation.</para>
|
|
|
- </sect2>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="siteminder">
|
|
|
- <title>Siteminder Authentication Mechanism</title>
|
|
|
-
|
|
|
- <sect1 id="siteminder-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Siteminder is a commercial single sign on solution by Computer
|
|
|
- Associates.</para>
|
|
|
-
|
|
|
- <para>Acegi Security provides a filter,
|
|
|
- <literal>SiteminderAuthenticationProcessingFilter</literal> and
|
|
|
- provider, <literal>SiteminderAuthenticationProvider</literal> that can
|
|
|
- be used to process requests that have been pre-authenticated by
|
|
|
- Siteminder. This filter assumes that you're using Siteminder for
|
|
|
- <emphasis>authentication</emphasis>, and that you're using Acegi
|
|
|
- Security for <emphasis>authorization</emphasis>. The use of Siteminder
|
|
|
- for <emphasis>authorization</emphasis> is not yet directly supported
|
|
|
- by Acegi Security.</para>
|
|
|
-
|
|
|
- <para>When using Siteminder, an agent is setup on your web server to
|
|
|
- intercept a principal's first call to your application. The agent
|
|
|
- redirects the web request to a single sign-on login page, and once
|
|
|
- authenticated, your application receives the request. Inside the HTTP
|
|
|
- request is a header - such as <literal>SM_USER</literal> - which
|
|
|
- identifies the authenticated principal (please refer to your
|
|
|
- organization's "single sign-on" group for header details in your
|
|
|
- particular configuration).</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="siteminder-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>The first step in setting up Acegi Security's Siteminder support
|
|
|
- is to define the authentication mechanism that will inspect the HTTP
|
|
|
- header discussed earlier. It will be responsible for generating a
|
|
|
- <literal>UsernamePasswordAuthenticationToken</literal> that is later
|
|
|
- sent to the <literal>SiteminderAuthenticationProvider</literal>. Let's
|
|
|
- look at an example:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="authenticationProcessingFilter" class="org.acegisecurity.ui.webapp.SiteminderAuthenticationProcessingFilter">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="authenticationFailureUrl"><value>/login.jsp?login_error=1</value></property>
|
|
|
- <property name="defaultTargetUrl"><value>/security.do?method=getMainMenu</value></property>
|
|
|
- <property name="filterProcessesUrl"><value>/j_acegi_security_check</value></property>
|
|
|
- <property name="siteminderUsernameHeaderKey"><value>SM_USER</value></property>
|
|
|
- <property name="formUsernameParameterKey"><value>j_username</value></property>
|
|
|
-</bean></programlisting></para>
|
|
|
-
|
|
|
- <para>In our example above, the bean is being provided an
|
|
|
- <literal>AuthenticationManager</literal>, as is normally needed by
|
|
|
- authentication mechanisms. Several URLs are also specified, with the
|
|
|
- values being self-explanatory. It's important to also specify the HTTP
|
|
|
- header that Acegi Security should inspect. If you additionally want to
|
|
|
- support form-based authentication (i.e. in your development
|
|
|
- environment where Siteminder is not installed), specify the form's
|
|
|
- username parameter as well - just don't do this in production!</para>
|
|
|
-
|
|
|
- <para>Note that you'll need a
|
|
|
- <literal><literal>SiteminderAuthenticationProvider</literal></literal>
|
|
|
- configured against your <literal>ProviderManager</literal> in order to
|
|
|
- use the Siteminder authentication mechanism. Normally an
|
|
|
- <literal>AuthenticationProvider</literal> expects the password
|
|
|
- property to match what it retrieves from the
|
|
|
- <literal>UserDetailsSource</literal>, but in this case, authentication
|
|
|
- has already been handled by Siteminder, so password property is not
|
|
|
- even relevant. This may sound like a security weakness, but remember
|
|
|
- that users have to authenticate with Siteminder before your
|
|
|
- application ever receives the requests, so the purpose of your custom
|
|
|
- <literal>UserDetailsService</literal> should simply be to build the
|
|
|
- complete <literal>Authentication</literal> object (ie with suitable
|
|
|
- <literal>GrantedAuthority[]</literal>s).</para>
|
|
|
-
|
|
|
- <para>Advanced tip and word to the wise: If you additionally want to
|
|
|
- support form-based authentication in your development environment
|
|
|
- (where Siteminder is typically not installed), specify the form's
|
|
|
- username parameter as well. Just don't do this in production!</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="runas">
|
|
|
- <title>Run-As Authentication Replacement</title>
|
|
|
-
|
|
|
- <sect1 id="runas-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>The <literal>AbstractSecurityInterceptor</literal> is able to
|
|
|
- temporarily replace the <literal>Authentication</literal> object in
|
|
|
- the <literal>SecurityContext</literal> and
|
|
|
- <literal>SecurityContextHolder</literal> during the secure object
|
|
|
- callback phase. This only occurs if the original
|
|
|
- <literal>Authentication</literal> object was successfully processed by
|
|
|
- the <literal>AuthenticationManager</literal> and
|
|
|
- <literal>AccessDecisionManager</literal>. The
|
|
|
- <literal>RunAsManager</literal> will indicate the replacement
|
|
|
- <literal>Authentication</literal> object, if any, that should be used
|
|
|
- during the <literal>SecurityInterceptorCallback</literal>.</para>
|
|
|
-
|
|
|
- <para>By temporarily replacing the <literal>Authentication</literal>
|
|
|
- object during the secure object callback phase, the secured invocation
|
|
|
- will be able to call other objects which require different
|
|
|
- authentication and authorization credentials. It will also be able to
|
|
|
- perform any internal security checks for specific
|
|
|
- <literal>GrantedAuthority</literal> objects. Because Acegi Security
|
|
|
- provides a number of helper classes that automatically configure
|
|
|
- remoting protocols based on the contents of the
|
|
|
- <literal>SecurityContextHolder</literal>, these run-as replacements
|
|
|
- are particularly useful when calling remote web services</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="runas-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>A <literal>RunAsManager</literal> interface is provided by Acegi
|
|
|
- Security:</para>
|
|
|
-
|
|
|
- <para><programlisting>public Authentication buildRunAs(Authentication authentication, Object object, ConfigAttributeDefinition config);
|
|
|
-public boolean supports(ConfigAttribute attribute);
|
|
|
-public boolean supports(Class clazz);</programlisting></para>
|
|
|
-
|
|
|
- <para>The first method returns the <literal>Authentication</literal>
|
|
|
- object that should replace the existing
|
|
|
- <literal>Authentication</literal> object for the duration of the
|
|
|
- method invocation. If the method returns <literal>null</literal>, it
|
|
|
- indicates no replacement should be made. The second method is used by
|
|
|
- the <literal>AbstractSecurityInterceptor</literal> as part of its
|
|
|
- startup validation of configuration attributes. The
|
|
|
- <literal>supports(Class)</literal> method is called by a security
|
|
|
- interceptor implementation to ensure the configured
|
|
|
- <literal>RunAsManager</literal> supports the type of secure object
|
|
|
- that the security interceptor will present.</para>
|
|
|
-
|
|
|
- <para>One concrete implementation of a <literal>RunAsManager</literal>
|
|
|
- is provided with Acegi Security. The
|
|
|
- <literal>RunAsManagerImpl</literal> class returns a replacement
|
|
|
- <literal>RunAsUserToken</literal> if any
|
|
|
- <literal>ConfigAttribute</literal> starts with
|
|
|
- <literal>RUN_AS_</literal>. If any such
|
|
|
- <literal>ConfigAttribute</literal> is found, the replacement
|
|
|
- <literal>RunAsUserToken</literal> will contain the same principal,
|
|
|
- credentials and granted authorities as the original
|
|
|
- <literal>Authentication</literal> object, along with a new
|
|
|
- <literal>GrantedAuthorityImpl</literal> for each
|
|
|
- <literal>RUN_AS_</literal> <literal>ConfigAttribute</literal>. Each
|
|
|
- new <literal>GrantedAuthorityImpl</literal> will be prefixed with
|
|
|
- <literal>ROLE_</literal>, followed by the <literal>RUN_AS</literal>
|
|
|
- <literal>ConfigAttribute</literal>. For example, a
|
|
|
- <literal>RUN_AS_SERVER</literal> will result in the replacement
|
|
|
- <literal>RunAsUserToken</literal> containing a
|
|
|
- <literal>ROLE_RUN_AS_SERVER</literal> granted authority.</para>
|
|
|
-
|
|
|
- <para>The replacement <literal>RunAsUserToken</literal> is just like
|
|
|
- any other <literal>Authentication</literal> object. It needs to be
|
|
|
- authenticated by the <literal>AuthenticationManager</literal>,
|
|
|
- probably via delegation to a suitable
|
|
|
- <literal>AuthenticationProvider</literal>. The
|
|
|
- <literal>RunAsImplAuthenticationProvider</literal> performs such
|
|
|
- authentication. It simply accepts as valid any
|
|
|
- <literal>RunAsUserToken</literal> presented.</para>
|
|
|
-
|
|
|
- <para>To ensure malicious code does not create a
|
|
|
- <literal>RunAsUserToken</literal> and present it for guaranteed
|
|
|
- acceptance by the <literal>RunAsImplAuthenticationProvider</literal>,
|
|
|
- the hash of a key is stored in all generated tokens. The
|
|
|
- <literal>RunAsManagerImpl</literal> and
|
|
|
- <literal>RunAsImplAuthenticationProvider</literal> is created in the
|
|
|
- bean context with the same key:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="runAsManager" class="org.acegisecurity.runas.RunAsManagerImpl">
|
|
|
- <property name="key"><value>my_run_as_password</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="runAsAuthenticationProvider" class="org.acegisecurity.runas.RunAsImplAuthenticationProvider">
|
|
|
- <property name="key"><value>my_run_as_password</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>By using the same key, each <literal>RunAsUserToken</literal>
|
|
|
- can be validated it was created by an approved
|
|
|
- <literal>RunAsManagerImpl</literal>. The
|
|
|
- <literal>RunAsUserToken</literal> is immutable after creation for
|
|
|
- security reasons</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="form">
|
|
|
- <title>Form Authentication Mechanism</title>
|
|
|
-
|
|
|
- <sect1 id="form-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>HTTP Form Authentication involves using the
|
|
|
- <literal>AuthenticationProcessingFilter</literal> to process a login
|
|
|
- form. This is the most common way that application authenticate end
|
|
|
- users. Form-based authentication is entirely compatible with the DAO
|
|
|
- and JAAS authentication providers.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="form-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>The login form simply contains <literal>j_username</literal> and
|
|
|
- <literal>j_password</literal> input fields, and posts to a URL that is
|
|
|
- monitored by the filter (by default
|
|
|
- <literal>j_acegi_security_check</literal>). The filter is defined in
|
|
|
- <literal>web.xml</literal> behind a
|
|
|
- <literal>FilterToBeanProxy</literal> as follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><filter>
|
|
|
- <filter-name>Acegi Authentication Processing Filter</filter-name>
|
|
|
- <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
|
|
|
- <init-param>
|
|
|
- <param-name>targetClass</param-name>
|
|
|
- <param-value>org.acegisecurity.ui.webapp.AuthenticationProcessingFilter</param-value>
|
|
|
- </init-param>
|
|
|
-</filter>
|
|
|
-
|
|
|
-<filter-mapping>
|
|
|
- <filter-name>Acegi Authentication Processing Filter</filter-name>
|
|
|
- <url-pattern>/*</url-pattern>
|
|
|
-</filter-mapping></programlisting></para>
|
|
|
-
|
|
|
- <para>For a discussion of <literal>FilterToBeanProxy</literal>, please
|
|
|
- refer to the Filters section. The application context will need to
|
|
|
- define the <literal>AuthenticationProcessingFilter</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="authenticationProcessingFilter" class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilter">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="authenticationFailureUrl"><value>/acegilogin.jsp?login_error=1</value></property>
|
|
|
- <property name="defaultTargetUrl"><value>/</value></property>
|
|
|
- <property name="filterProcessesUrl"><value>/j_acegi_security_check</value></property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>The configured <literal>AuthenticationManager</literal>
|
|
|
- processes each authentication request. If authentication fails, the
|
|
|
- browser will be redirected to the
|
|
|
- <literal>authenticationFailureUrl</literal>. The
|
|
|
- <literal>AuthenticationException</literal> will be placed into the
|
|
|
- <literal>HttpSession</literal> attribute indicated by
|
|
|
- <literal>AbstractProcessingFilter.ACEGI_SECURITY_LAST_EXCEPTION_KEY</literal>,
|
|
|
- enabling a reason to be provided to the user on the error page.</para>
|
|
|
-
|
|
|
- <para>If authentication is successful, the resulting
|
|
|
- <literal>Authentication</literal> object will be placed into the
|
|
|
- <literal>SecurityContextHolder</literal>.</para>
|
|
|
-
|
|
|
- <para>Once the <literal>SecurityContextHolder</literal> has been
|
|
|
- updated, the browser will need to be redirected to the target URL. The
|
|
|
- target URL is usually indicated by the <literal>HttpSession</literal>
|
|
|
- attribute specified by
|
|
|
- <literal>AbstractProcessingFilter.ACEGI_SECURITY_TARGET_URL_KEY</literal>.
|
|
|
- This attribute is automatically set by the
|
|
|
- <literal>ExceptionTranslationFilter</literal> when an
|
|
|
- <literal>AuthenticationException</literal> occurs, so that after login
|
|
|
- is completed the user can return to what they were trying to access.
|
|
|
- If for some reason the <literal>HttpSession</literal> does not
|
|
|
- indicate the target URL, the browser will be redirected to the
|
|
|
- <literal>defaultTargetUrl</literal> property.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="basic">
|
|
|
- <title>BASIC Authentication Mechanism</title>
|
|
|
-
|
|
|
- <sect1 id="basic-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Acegi Security provides a
|
|
|
- <literal>BasicProcessingFilter</literal> which is capable of
|
|
|
- processing basic authentication credentials presented in HTTP headers.
|
|
|
- This can be used for authenticating calls made by Spring remoting
|
|
|
- protocols (such as Hessian and Burlap), as well as normal user agents
|
|
|
- (such as Internet Explorer and Navigator). The standard governing HTTP
|
|
|
- Basic Authentication is defined by RFC 1945, Section 11, and the
|
|
|
- <literal>BasicProcessingFilter</literal> conforms with this RFC. Basic
|
|
|
- Authentication is an attractive approach to authentication, because it
|
|
|
- is very widely deployed in user agents and implementation is extremely
|
|
|
- simple (it's just a Base64 encoding of the username:password,
|
|
|
- specified in a HTTP header).</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="basic-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>To implement HTTP Basic Authentication, it is necessary to
|
|
|
- define <literal>BasicProcessingFilter</literal> in the filter chain.
|
|
|
- The application context will need to define the
|
|
|
- <literal>BasicProcessingFilter</literal> and its required
|
|
|
- collaborator:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="basicProcessingFilter" class="org.acegisecurity.ui.basicauth.BasicProcessingFilter">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="authenticationEntryPoint"><ref bean="authenticationEntryPoint"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="authenticationEntryPoint" class="org.acegisecurity.ui.basicauth.BasicProcessingFilterEntryPoint">
|
|
|
- <property name="realmName"><value>Name Of Your Realm</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>The configured <literal>AuthenticationManager</literal>
|
|
|
- processes each authentication request. If authentication fails, the
|
|
|
- configured <literal>AuthenticationEntryPoint</literal> will be used to
|
|
|
- retry the authentication process. Usually you will use the
|
|
|
- <literal>BasicProcessingFilterEntryPoint</literal>, which returns a
|
|
|
- 401 response with a suitable header to retry HTTP Basic
|
|
|
- authentication. If authentication is successful, the resulting
|
|
|
- <literal>Authentication</literal> object will be placed into the
|
|
|
- <literal>SecurityContextHolder</literal>.</para>
|
|
|
-
|
|
|
- <para>If the authentication event was successful, or authentication
|
|
|
- was not attempted because the HTTP header did not contain a supported
|
|
|
- authentication request, the filter chain will continue as normal. The
|
|
|
- only time the filter chain will be interrupted is if authentication
|
|
|
- fails and the <literal>AuthenticationEntryPoint</literal> is called,
|
|
|
- as discussed in the previous paragraph</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="digest">
|
|
|
- <title>Digest Authentication</title>
|
|
|
-
|
|
|
- <sect1 id="digest-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Acegi Security provides a
|
|
|
- <literal>DigestProcessingFilter</literal> which is capable of
|
|
|
- processing digest authentication credentials presented in HTTP
|
|
|
- headers. Digest Authentication attempts to solve many of the
|
|
|
- weaknesses of Basic authentication, specifically by ensuring
|
|
|
- credentials are never sent in clear text across the wire. Many user
|
|
|
- agents support Digest Authentication, including FireFox and Internet
|
|
|
- Explorer. The standard governing HTTP Digest Authentication is defined
|
|
|
- by RFC 2617, which updates an earlier version of the Digest
|
|
|
- Authentication standard prescribed by RFC 2069. Most user agents
|
|
|
- implement RFC 2617. Acegi Security
|
|
|
- <literal>DigestProcessingFilter</literal> is compatible with the
|
|
|
- "<literal>auth</literal>" quality of protection
|
|
|
- (<literal>qop</literal>) prescribed by RFC 2617, which also provides
|
|
|
- backward compatibility with RFC 2069. Digest Authentication is a
|
|
|
- highly attractive option if you need to use unencrypted HTTP (ie no
|
|
|
- TLS/HTTPS) and wish to maximise security of the authentication
|
|
|
- process. Indeed Digest Authentication is a mandatory requirement for
|
|
|
- the WebDAV protocol, as noted by RFC 2518 Section 17.1, so we should
|
|
|
- expect to see it increasingly deployed and replacing Basic
|
|
|
- Authentication.</para>
|
|
|
-
|
|
|
- <para>Digest Authentication is definitely the most secure choice
|
|
|
- between Form Authentication, Basic Authentication and Digest
|
|
|
- Authentication, although extra security also means more complex user
|
|
|
- agent implementations. Central to Digest Authentication is a "nonce".
|
|
|
- This is a value the server generates. Acegi Security's nonce adopts
|
|
|
- the following format:</para>
|
|
|
-
|
|
|
- <para><programlisting>base64(expirationTime + ":" + md5Hex(expirationTime + ":" + key))
|
|
|
-
|
|
|
-expirationTime: The date and time when the nonce expires, expressed in milliseconds
|
|
|
-key: A private key to prevent modification of the nonce token
|
|
|
-</programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>DigestProcessingFilterEntryPoint</literal> has a
|
|
|
- property specifying the <literal>key</literal> used for generating the
|
|
|
- nonce tokens, along with a <literal>nonceValiditySeconds</literal>
|
|
|
- property for determining the expiration time (default 300, which
|
|
|
- equals five minutes). Whist ever the nonce is valid, the digest is
|
|
|
- computed by concatenating various strings including the username,
|
|
|
- password, nonce, URI being requested, a client-generated nonce (merely
|
|
|
- a random value which the user agent generates each request), the realm
|
|
|
- name etc, then performing an MD5 hash. Both the server and user agent
|
|
|
- perform this digest computation, resulting in different hash codes if
|
|
|
- they disagree on an included value (eg password). In Acegi Security
|
|
|
- implementation, if the server-generated nonce has merely expired (but
|
|
|
- the digest was otherwise valid), the
|
|
|
- <literal>DigestProcessingFilterEntryPoint</literal> will send a
|
|
|
- <literal>"stale=true"</literal> header. This tells the user agent
|
|
|
- there is no need to disturb the user (as the password and username etc
|
|
|
- is correct), but simply to try again using a new nonce.</para>
|
|
|
-
|
|
|
- <para>An appropriate value for
|
|
|
- <literal>DigestProcessingFilterEntryPoint</literal>'s
|
|
|
- <literal>nonceValiditySeconds</literal> parameter will depend on your
|
|
|
- application. Extremely secure applications should note that an
|
|
|
- intercepted authentication header can be used to impersonate the
|
|
|
- principal until the <literal>expirationTime</literal> contained in the
|
|
|
- nonce is reached. This is the key principle when selecting an
|
|
|
- appropriate setting, but it would be unusual for immensely secure
|
|
|
- applications to not be running over TLS/HTTPS in the first
|
|
|
- instance.</para>
|
|
|
-
|
|
|
- <para>Because of the more complex implementation of Digest
|
|
|
- Authentication, there are often user agent issues. For example,
|
|
|
- Internet Explorer fails to present an "<literal>opaque</literal>"
|
|
|
- token on subsequent requests in the same session. Acegi Security
|
|
|
- filters therefore encapsulate all state information into the
|
|
|
- "<literal>nonce</literal>" token instead. In our testing, Acegi
|
|
|
- Security implementation works reliably with FireFox and Internet
|
|
|
- Explorer, correctly handling nonce timeouts etc.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="digest-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>Now that we've reviewed the theory, let's see how to use it. To
|
|
|
- implement HTTP Digest Authentication, it is necessary to define
|
|
|
- <literal>DigestProcessingFilter</literal> in the fitler chain. The
|
|
|
- application context will need to define the
|
|
|
- <literal>DigestProcessingFilter</literal> and its required
|
|
|
- collaborators:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="digestProcessingFilter" class="org.acegisecurity.ui.digestauth.DigestProcessingFilter">
|
|
|
- <property name="userDetailsService"><ref local="jdbcDaoImpl"/></property>
|
|
|
- <property name="authenticationEntryPoint"><ref local="digestProcessingFilterEntryPoint"/></property>
|
|
|
- <property name="userCache"><ref local="userCache"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="digestProcessingFilterEntryPoint" class="org.acegisecurity.ui.digestauth.DigestProcessingFilterEntryPoint">
|
|
|
- <property name="realmName"><value>Contacts Realm via Digest Authentication</value></property>
|
|
|
- <property name="key"><value>acegi</value></property>
|
|
|
- <property name="nonceValiditySeconds"><value>10</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>The configured <literal>UserDetailsService</literal> is needed
|
|
|
- because <literal>DigestProcessingFilter</literal> must have direct
|
|
|
- access to the clear text password of a user. Digest Authentication
|
|
|
- will NOT work if you are using encoded passwords in your DAO. The DAO
|
|
|
- collaborator, along with the <literal>UserCache</literal>, are
|
|
|
- typically shared directly with a
|
|
|
- <literal>DaoAuthenticationProvider</literal>. The
|
|
|
- <literal>authenticationEntryPoint</literal> property must be
|
|
|
- <literal>DigestProcessingFilterEntryPoint</literal>, so that
|
|
|
- <literal>DigestProcessingFilter</literal> can obtain the correct
|
|
|
- <literal>realmName</literal> and <literal>key</literal> for digest
|
|
|
- calculations.</para>
|
|
|
-
|
|
|
- <para>Like <literal>BasicAuthenticationFilter</literal>, if
|
|
|
- authentication is successful an <literal>Authentication</literal>
|
|
|
- request token will be placed into the
|
|
|
- <literal>SecurityContextHolder</literal>. If the authentication event
|
|
|
- was successful, or authentication was not attempted because the HTTP
|
|
|
- header did not contain a Digest Authentication request, the filter
|
|
|
- chain will continue as normal. The only time the filter chain will be
|
|
|
- interrupted is if authentication fails and the
|
|
|
- <literal>AuthenticationEntryPoint</literal> is called, as discussed in
|
|
|
- the previous paragraph.</para>
|
|
|
-
|
|
|
- <para>Digest Authentication's RFC offers a range of additional
|
|
|
- features to further increase security. For example, the nonce can be
|
|
|
- changed on every request. Despite this, Acegi Security implementation
|
|
|
- was designed to minimise the complexity of the implementation (and the
|
|
|
- doubtless user agent incompatibilities that would emerge), and avoid
|
|
|
- needing to store server-side state. You are invited to review RFC 2617
|
|
|
- if you wish to explore these features in more detail. As far as we are
|
|
|
- aware, Acegi Security implementation does comply with the minimum
|
|
|
- standards of this RFC.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="anonymous">
|
|
|
- <title>Anonymous Authentication</title>
|
|
|
-
|
|
|
- <sect1 id="anonymous-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Particularly in the case of web request URI security, sometimes
|
|
|
- it is more convenient to assign configuration attributes against every
|
|
|
- possible secure object invocation. Put differently, sometimes it is
|
|
|
- nice to say <literal>ROLE_SOMETHING</literal> is required by default
|
|
|
- and only allow certain exceptions to this rule, such as for login,
|
|
|
- logout and home pages of an application. There are also other
|
|
|
- situations where anonymous authentication would be desired, such as
|
|
|
- when an auditing interceptor queries the
|
|
|
- <literal>SecurityContextHolder</literal> to identify which principal
|
|
|
- was responsible for a given operation. Such classes can be authored
|
|
|
- with more robustness if they know the
|
|
|
- <literal>SecurityContextHolder</literal> always contains an
|
|
|
- <literal>Authentication</literal> object, and never
|
|
|
- <literal>null</literal>.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="anonymous-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>Acegi Security provides three classes that together provide an
|
|
|
- anonymous authentication feature.
|
|
|
- <literal>AnonymousAuthenticationToken</literal> is an implementation
|
|
|
- of <literal>Authentication</literal>, and stores the
|
|
|
- <literal>GrantedAuthority</literal>[]s which apply to the anonymous
|
|
|
- principal. There is a corresponding
|
|
|
- <literal>AnonymousAuthenticationProvider</literal>, which is chained
|
|
|
- into the <literal>ProviderManager</literal> so that
|
|
|
- <literal>AnonymousAuthenticationTokens</literal> are accepted.
|
|
|
- Finally, there is an AnonymousProcessingFilter, which is chained after
|
|
|
- the normal authentication mechanisms and automatically add an
|
|
|
- <literal>AnonymousAuthenticationToken</literal> to the
|
|
|
- <literal>SecurityContextHolder</literal> if there is no existing
|
|
|
- <literal>Authentication</literal> held there. The definition of the
|
|
|
- filter and authentication provider appears as follows:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="anonymousProcessingFilter" class="org.acegisecurity.providers.anonymous.AnonymousProcessingFilter">
|
|
|
- <property name="key"><value>foobar</value></property>
|
|
|
- <property name="userAttribute"><value>anonymousUser,ROLE_ANONYMOUS</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="anonymousAuthenticationProvider" class="org.acegisecurity.providers.anonymous.AnonymousAuthenticationProvider">
|
|
|
- <property name="key"><value>foobar</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>key</literal> is shared between the filter and
|
|
|
- authentication provider, so that tokens created by the former are
|
|
|
- accepted by the latter. The <literal>userAttribute</literal> is
|
|
|
- expressed in the form of
|
|
|
- <literal>usernameInTheAuthenticationToken,grantedAuthority[,grantedAuthority]</literal>.
|
|
|
- This is the same syntax as used after the equals sign for
|
|
|
- <literal>InMemoryDaoImpl</literal>'s <literal>userMap</literal>
|
|
|
- property.</para>
|
|
|
-
|
|
|
- <para>As explained earlier, the benefit of anonymous authentication is
|
|
|
- that all URI patterns can have security applied to them. For
|
|
|
- example:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="filterInvocationInterceptor" class="org.acegisecurity.intercept.web.FilterSecurityInterceptor">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="accessDecisionManager"><ref local="httpRequestAccessDecisionManager"/></property>
|
|
|
- <property name="objectDefinitionSource">
|
|
|
- <value>
|
|
|
- CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
|
|
|
- PATTERN_TYPE_APACHE_ANT
|
|
|
- /index.jsp=ROLE_ANONYMOUS,ROLE_USER
|
|
|
- /hello.htm=ROLE_ANONYMOUS,ROLE_USER
|
|
|
- /logoff.jsp=ROLE_ANONYMOUS,ROLE_USER
|
|
|
- /acegilogin.jsp*=ROLE_ANONYMOUS,ROLE_USER
|
|
|
- /**=ROLE_USER
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting>Rounding out the anonymous authentication discussion
|
|
|
- is the <literal>AuthenticationTrustResolver</literal> interface, with
|
|
|
- its corresponding <literal>AuthenticationTrustResolverImpl</literal>
|
|
|
- implementation. This interface provides an
|
|
|
- <literal>isAnonymous(Authentication)</literal> method, which allows
|
|
|
- interested classes to take into account this special type of
|
|
|
- authentication status. The
|
|
|
- <literal>ExceptionTranslationFilter</literal> uses this interface in
|
|
|
- processing <literal>AccessDeniedException</literal>s. If an
|
|
|
- <literal>AccessDeniedException</literal> is thrown, and the
|
|
|
- authentication is of an anonymous type, instead of throwing a 403
|
|
|
- (forbidden) response, the filter will instead commence the
|
|
|
- <literal>AuthenticationEntryPoint</literal> so the principal can
|
|
|
- authenticate properly. This is a necessary distinction, otherwise
|
|
|
- principals would always be deemed "authenticated" and never be given
|
|
|
- an opportunity to login via form, basic, digest or some other normal
|
|
|
- authentication mechanism</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="remember-me">
|
|
|
- <title>Remember-Me Authentication</title>
|
|
|
-
|
|
|
- <sect1 id="remember-me-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Remember-me authentication refers to web sites being able to
|
|
|
- remember the identity of a principal between sessions. This is
|
|
|
- typically accomplished by sending a cookie to the browser, with the
|
|
|
- cookie being detected during future sessions and causing automated
|
|
|
- login to take place. Acegi Security provides the necessary hooks so
|
|
|
- that such operations can take place, along with providing a concrete
|
|
|
- implementation that uses hashing to preserve the security of
|
|
|
- cookie-based tokens.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="remember-me-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>Remember-me authentication is not used with basic
|
|
|
- authentication, given it is often not used with
|
|
|
- <literal>HttpSession</literal>s. Remember-me is used with
|
|
|
- <literal>AuthenticationProcessingFilter</literal>, and is implemented
|
|
|
- via hooks in the <literal>AbstractProcessingFilter</literal>
|
|
|
- superclass. The hooks will invoke a concrete
|
|
|
- <literal>RememberMeServices</literal> at the appropriate times. The
|
|
|
- interface looks like this:</para>
|
|
|
-
|
|
|
- <para><programlisting>public Authentication autoLogin(HttpServletRequest request, HttpServletResponse response);
|
|
|
-public void loginFail(HttpServletRequest request, HttpServletResponse response);
|
|
|
-public void loginSuccess(HttpServletRequest request, HttpServletResponse response, Authentication successfulAuthentication);</programlisting></para>
|
|
|
-
|
|
|
- <para>Please refer to JavaDocs for a fuller discussion on what the
|
|
|
- methods do, although note at this stage
|
|
|
- <literal>AbstractProcessingFilter</literal> only calls the
|
|
|
- <literal>loginFail()</literal> and <literal>loginSuccess()</literal>
|
|
|
- methods. The <literal>autoLogin()</literal> method is called by
|
|
|
- <literal>RememberMeProcessingFilter</literal> whenever the
|
|
|
- <literal>SecurityContextHolder</literal> does not contain an
|
|
|
- <literal>Authentication</literal>. This interface therefore provides
|
|
|
- the underlaying remember-me implementation with sufficient
|
|
|
- notification of authentication-related events, and delegates to the
|
|
|
- implementation whenever a candidate web request might contain a cookie
|
|
|
- and wish to be remembered.</para>
|
|
|
-
|
|
|
- <para>This design allows any number of remember-me implementation
|
|
|
- strategies. In the interests of simplicity and avoiding the need for
|
|
|
- DAO implementations that specify write and create methods, Acegi
|
|
|
- Security's only concrete implementation,
|
|
|
- <literal>TokenBasedRememberMeServices</literal>, uses hashing to
|
|
|
- achieve a useful remember-me strategy. In essence a cookie is sent to
|
|
|
- the browser upon successful interactive authentication, with that
|
|
|
- cookie being composed as follows:</para>
|
|
|
-
|
|
|
- <para><programlisting>base64(username + ":" + expirationTime + ":" + md5Hex(username + ":" + expirationTime + ":" password + ":" + key))
|
|
|
-
|
|
|
-username: As identifiable to TokenBasedRememberMeServices.getUserDetailsService()
|
|
|
-password: That matches the relevant UserDetails retrieved from TokenBasedRememberMeServices.getUserDetailsService()
|
|
|
-expirationTime: The date and time when the remember-me token expires, expressed in milliseconds
|
|
|
-key: A private key to prevent modification of the remember-me token
|
|
|
-</programlisting></para>
|
|
|
-
|
|
|
- <para>As such the remember-me token is valid only for the period
|
|
|
- specified, and provided that the username, password and key does not
|
|
|
- change. Notably, this has a potential security issue in that a
|
|
|
- captured remember-me token will be usable from any user agent until
|
|
|
- such time as the token expires. This is the same issue as with digest
|
|
|
- authentication. If a principal is aware a token has been captured,
|
|
|
- they can easily change their password and immediately invalidate all
|
|
|
- remember-me tokens on issue. However, if more significant security is
|
|
|
- needed a rolling token approach should be used (this would require a
|
|
|
- database) or remember-me services should simply not be used.</para>
|
|
|
-
|
|
|
- <para><literal>TokenBasedRememberMeServices</literal> generates a
|
|
|
- <literal>RememberMeAuthenticationToken</literal>, which is processed
|
|
|
- by <literal>RememberMeAuthenticationProvider</literal>. A
|
|
|
- <literal>key</literal> is shared between this authentication provider
|
|
|
- and the <literal>TokenBasedRememberMeServices</literal>. In addition,
|
|
|
- <literal>TokenBasedRememberMeServices</literal> requires A
|
|
|
- UserDetailsService from which it can retrieve the username and
|
|
|
- password for signature comparison purposes, and generate the
|
|
|
- <literal>RememberMeAuthenticationToken</literal> to contain the
|
|
|
- correct <literal>GrantedAuthority</literal>[]s. Some sort of logout
|
|
|
- command should be provided by the application (typically via a JSP)
|
|
|
- that invalidates the cookie upon user request. See the Contacts Sample
|
|
|
- application's <literal>logout.jsp</literal> for an example.</para>
|
|
|
-
|
|
|
- <para>The beans required in an application context to enable
|
|
|
- remember-me services are as follows:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="rememberMeProcessingFilter" class="org.acegisecurity.ui.rememberme.RememberMeProcessingFilter">
|
|
|
- <property name="rememberMeServices"><ref local="rememberMeServices"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="rememberMeServices" class="org.acegisecurity.ui.rememberme.TokenBasedRememberMeServices">
|
|
|
- <property name="userDetailsService"><ref local="jdbcDaoImpl"/></property>
|
|
|
- <property name="key"><value>springRocks</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="rememberMeAuthenticationProvider" class="org.acegisecurity.providers.rememberme.RememberMeAuthenticationProvider">
|
|
|
- <property name="key"><value>springRocks</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting>Don't forget to add your
|
|
|
- <literal>RememberMeServices</literal> implementation to your
|
|
|
- <literal>AuthenticationProcessingFilter.setRememberMeServices()</literal>
|
|
|
- property, include the
|
|
|
- <literal>RememberMeAuthenticationProvider</literal> in your
|
|
|
- <literal>AuthenticationManager.setProviders()</literal> list, and add
|
|
|
- a call to <literal>RememberMeProcessingFilter</literal> into your
|
|
|
- <literal>FilterChainProxy</literal> (typically immediately after your
|
|
|
- <literal>AuthenticationProcessingFilter</literal>)</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="x509">
|
|
|
- <title>X509 Authentication</title>
|
|
|
-
|
|
|
- <sect1 id="x509-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>The most common use of X509 certificate authentication is in
|
|
|
- verifying the identity of a server when using SSL, most commonly when
|
|
|
- using HTTPS from a browser. The browser will automatically check that
|
|
|
- the certificate presented by a server has been issued (ie digitally
|
|
|
- signed) by one of a list of trusted certificate authorities which it
|
|
|
- maintains.</para>
|
|
|
-
|
|
|
- <para>You can also use SSL with <quote>mutual authentication</quote>;
|
|
|
- the server will then request a valid certificate from the client as
|
|
|
- part of the SSL handshake. The server will authenticate the client by
|
|
|
- checking that it's certificate is signed by an acceptable authority.
|
|
|
- If a valid certificate has been provided, it can be obtained through
|
|
|
- the servlet API in an application. Acegi Security X509 module extracts
|
|
|
- the certificate using a filter and passes it to the configured X509
|
|
|
- authentication provider to allow any additional application-specific
|
|
|
- checks to be applied. It also maps the certificate to an application
|
|
|
- user and loads that user's set of granted authorities for use with the
|
|
|
- standard Acegi Security infrastructure.</para>
|
|
|
-
|
|
|
- <para>You should be familiar with using certificates and setting up
|
|
|
- client authentication for your servlet container before attempting to
|
|
|
- use it with Acegi Security. Most of the work is in creating and
|
|
|
- installing suitable certificates and keys. For example, if you're
|
|
|
- using Tomcat then read the instructions here <ulink
|
|
|
- url="http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html"></ulink>.
|
|
|
- It's important that you get this working before trying it out with
|
|
|
- Acegi Security</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="x509-with-acegi">
|
|
|
- <title>Using X509 with Acegi Security</title>
|
|
|
-
|
|
|
- <para>With X509 authentication, there is no explicit login procedure
|
|
|
- so the implementation is relatively simple; there is no need to
|
|
|
- redirect requests in order to interact with the user. As a result,
|
|
|
- some of the classes behave slightly differently from their equivalents
|
|
|
- in other packages. For example, the default <quote>entry point</quote>
|
|
|
- class, which is normally responsible for starting the authentication
|
|
|
- process, is only invoked if the certificate is rejected and it always
|
|
|
- returns an error to the user. With a suitable bean configuration, the
|
|
|
- normal sequence of events is as follows <orderedlist>
|
|
|
- <listitem>
|
|
|
- <para>The <classname>X509ProcessingFilter</classname> extracts
|
|
|
- the certificate from the request and uses it as the credentials
|
|
|
- for an authentication request. The generated authentication
|
|
|
- request is an <classname>X509AuthenticationToken</classname>.
|
|
|
- The request is passed to the authentication manager.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The <classname>X509AuthenticationProvider</classname>
|
|
|
- receives the token. Its main concern is to obtain the user
|
|
|
- information (in particular the user's granted authorities) that
|
|
|
- matches the certificate. It delegates this responsibility to an
|
|
|
- <interfacename>X509AuthoritiesPopulator</interfacename>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The populator's single method,
|
|
|
- <methodname>getUserDetails(X509Certificate
|
|
|
- userCertificate)</methodname> is invoked. Implementations should
|
|
|
- return a <classname>UserDetails</classname> instance containing
|
|
|
- the array of <classname>GrantedAuthority</classname> objects for
|
|
|
- the user. This method can also choose to reject the certificate
|
|
|
- (for example if it doesn't contain a matching user name). In
|
|
|
- such cases it should throw a
|
|
|
- <exceptionname>BadCredentialsException</exceptionname>. A
|
|
|
- DAO-based implementation,
|
|
|
- <classname>DaoX509AuthoritiesPopulator</classname>, is provided
|
|
|
- which extracts the user's name from the subject <quote>common
|
|
|
- name</quote> (CN) in the certificate. It also allows you to set
|
|
|
- your own regular expression to match a different part of the
|
|
|
- subject's distinguished name. A UserDetailsService is used to
|
|
|
- load the user information.<!-- TODO: Give email matching as an example --></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>If everything has gone smoothly then there should be a
|
|
|
- valid <classname>Authentication</classname> object in the secure
|
|
|
- context and the invocation will procede as normal. If no
|
|
|
- certificate was found, or the certificate was rejected, then the
|
|
|
- <classname>ExceptionTranslationFilter</classname> will invoke
|
|
|
- the <classname>X509ProcessingFilterEntryPoint</classname> which
|
|
|
- returns a 403 error (forbidden) to the user.</para>
|
|
|
- </listitem>
|
|
|
- </orderedlist></para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="x509-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>There is a version of the <link
|
|
|
- linkend="contacts-sample">Contacts Sample Application</link> which
|
|
|
- uses X509. Copy the beans and filter setup from this as a starting
|
|
|
- point for configuring your own application. A set of example
|
|
|
- certificates is also included which you can use to configure your
|
|
|
- server. These are <itemizedlist>
|
|
|
- <listitem>
|
|
|
- <para><filename>marissa.p12</filename>: A PKCS12 format file
|
|
|
- containing the client key and certificate. These should be
|
|
|
- installed in your browser. It maps to the user
|
|
|
- <quote>marissa</quote> in the application.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><filename>server.p12</filename>: The server certificate
|
|
|
- and key for HTTPS connections.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><filename>ca.jks</filename>: A Java keystore containing
|
|
|
- the certificate for the authority which issued marissa's
|
|
|
- certificate. This will be used by the container to validate
|
|
|
- client certificates.</para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist> For JBoss 3.2.7 (with Tomcat 5.0), the SSL
|
|
|
- configuration in the <filename>server.xml</filename> file looks like
|
|
|
- this <programlisting>
|
|
|
-<!-- SSL/TLS Connector configuration -->
|
|
|
-<Connector port="8443" address="${jboss.bind.address}"
|
|
|
- maxThreads="100" minSpareThreads="5" maxSpareThreads="15"
|
|
|
- scheme="https" secure="true"
|
|
|
- sslProtocol = "TLS"
|
|
|
- clientAuth="true" keystoreFile="${jboss.server.home.dir}/conf/server.p12"
|
|
|
- keystoreType="PKCS12" keystorePass="password"
|
|
|
- truststoreFile="${jboss.server.home.dir}/conf/ca.jks"
|
|
|
- truststoreType="JKS" truststorePass="password"
|
|
|
-/>
|
|
|
-
|
|
|
- </programlisting><parameter>clientAuth</parameter> can also be set to
|
|
|
- <parameter>want</parameter> if you still want SSL connections to
|
|
|
- succeed even if the client doesn't provide a certificate. Obviously
|
|
|
- these clients won't be able to access any objects secured by Acegi
|
|
|
- Security (unless you use a non-X509 authentication mechanism, such as
|
|
|
- BASIC authentication, to authenticate the user)</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="ldap">
|
|
|
- <title>LDAP Authentication</title>
|
|
|
-
|
|
|
- <sect1 id="ldap-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>LDAP is often used by organizations as a central repository for
|
|
|
- user information and as an authentication service. It can also be used
|
|
|
- to store the role information for application users.</para>
|
|
|
-
|
|
|
- <para>There are many different scenarios for how an LDAP server may be
|
|
|
- configured so Acegi LDAP provider is fully configurable. It uses
|
|
|
- separate strategy interfaces for authentication and role retrieval and
|
|
|
- provides default implementations which can be configured to handle a
|
|
|
- wide range of situations.</para>
|
|
|
-
|
|
|
- <para>You should be familiar with LDAP before trying to use it with
|
|
|
- Acegi. The following link provides a good introduction to the concepts
|
|
|
- involved and a guide to setting up a directory using the free LDAP
|
|
|
- server OpenLDAP: <ulink
|
|
|
- url="http://www.zytrax.com/books/ldap/"></ulink>. Some familiarity
|
|
|
- with the JNDI APIs used to access LDAP from Java may also be useful.
|
|
|
- We don't use any third-party LDAP libraries (Mozilla/Netscape, JLDAP
|
|
|
- etc.) in the LDAP provider.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="ldap-with-acegi">
|
|
|
- <title>Using LDAP with Acegi Security</title>
|
|
|
-
|
|
|
- <para>The main LDAP provider class is
|
|
|
- <classname>org.acegisecurity.providers.ldap.LdapAuthenticationProvider</classname>.
|
|
|
- This bean doesn't actually do much itself other than implement the
|
|
|
- <methodname>retrieveUser</methodname> method required by its base
|
|
|
- class,
|
|
|
- <classname>AbstractUserDetailsAuthenticationProvider</classname>. It
|
|
|
- delegates the work to two other beans, an
|
|
|
- <interfacename>LdapAuthenticator</interfacename> and an
|
|
|
- <interfacename>LdapAuthoritiesPopulator</interfacename> which are
|
|
|
- responsible for authenticating the user and retrieving the user's set
|
|
|
- of <interfacename>GrantedAuthority</interfacename>s
|
|
|
- respectively.</para>
|
|
|
-
|
|
|
- <sect2 id="ldap-ldap-authenticators">
|
|
|
- <title>LdapAuthenticator Implementations</title>
|
|
|
-
|
|
|
- <para>The authenticator is also responsible for retrieving any
|
|
|
- required user attributes. This is because the permissions on the
|
|
|
- attributes may depend on the type of authentication being used. For
|
|
|
- example, if binding as the user, it may be necessary to read them
|
|
|
- with the user's own permissions.</para>
|
|
|
-
|
|
|
- <para>There are currently two authentication strategies supplied
|
|
|
- with Acegi Security: <itemizedlist>
|
|
|
- <listitem>
|
|
|
- <para>Authentication directly to the LDAP server ("bind"
|
|
|
- authentication).</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Password comparison, where the password supplied by the
|
|
|
- user is compared with the one stored in the repository. This
|
|
|
- can either be done by retrieving the value of the password
|
|
|
- attribute and checking it locally or by performing an LDAP
|
|
|
- "compare" operation, where the supplied password is passed to
|
|
|
- the server for comparison and the real password value is never
|
|
|
- retrieved.</para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist></para>
|
|
|
-
|
|
|
- <sect3 id="ldap-ldap-authenticators-common">
|
|
|
- <title>Common Functionality</title>
|
|
|
-
|
|
|
- <para>Before it is possible to authenticate a user (by either
|
|
|
- strategy), the distinguished name (DN) has to be obtained from the
|
|
|
- login name supplied to the application. This can be done either by
|
|
|
- simple pattern-matching (by setting the
|
|
|
- <property>setUserDnPatterns</property> array property) or by
|
|
|
- setting the <property>userSearch</property> property. For the DN
|
|
|
- pattern-matching approach, a standard Java pattern format is used,
|
|
|
- and the login name will be substituted for the parameter
|
|
|
- <parameter>{0}</parameter>. The pattern should be relative to the
|
|
|
- DN that the configured
|
|
|
- <interfacename>InitialDirContextFactory</interfacename> will bind
|
|
|
- to (see the section on <link
|
|
|
- linkend="ldap-dircontextfactory">connecting to the LDAP
|
|
|
- server</link> for more information on this). For example, if you
|
|
|
- are using an LDAP server specified by the URL
|
|
|
- <literal>ldap://monkeymachine.co.uk/dc=acegisecurity,dc=org</literal>,
|
|
|
- and have a pattern <literal>uid={0},ou=greatapes</literal>, then a
|
|
|
- login name of "gorilla" will map to a DN
|
|
|
- <literal>uid=gorilla,ou=greatapes,dc=acegisecurity,dc=org</literal>.
|
|
|
- Each configured DN pattern will be tried in turn until a match is
|
|
|
- found. For information on using a search, see the section on <link
|
|
|
- linkend="ldap-searchobjects">search objects</link> below. A
|
|
|
- combination of the two approaches can also be used - the patterns
|
|
|
- will be checked first and if no matching DN is found, the search
|
|
|
- will be used.</para>
|
|
|
- </sect3>
|
|
|
-
|
|
|
- <sect3 id="ldap-ldap-authenticators-bind">
|
|
|
- <title>BindAuthenticator</title>
|
|
|
-
|
|
|
- <para>The class
|
|
|
- <classname>org.acegisecurity.providers.ldap.authenticator.BindAuthenticator</classname>
|
|
|
- implements the bind authentication strategy. It simply attempts to
|
|
|
- bind as the user.</para>
|
|
|
- </sect3>
|
|
|
-
|
|
|
- <sect3 id="ldap-ldap-authenticators-password">
|
|
|
- <title>PasswordComparisonAuthenticator</title>
|
|
|
-
|
|
|
- <para>The class
|
|
|
- <classname>org.acegisecurity.providers.ldap.authenticator.PasswordComparisonAuthenticator</classname>
|
|
|
- implements the password comparison authentication strategy.</para>
|
|
|
- </sect3>
|
|
|
-
|
|
|
- <sect3 id="ldap-ldap-authenticators-active-directory">
|
|
|
- <title>Active Directory Authentication</title>
|
|
|
-
|
|
|
- <para>In addition to standard LDAP authentication (binding with a
|
|
|
- DN), Active Directory has its own non-standard syntax for user
|
|
|
- authentication.</para>
|
|
|
- </sect3>
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="ldap-dircontextfactory">
|
|
|
- <title>Connecting to the LDAP Server</title>
|
|
|
-
|
|
|
- <para>The beans discussed above have to be able to connect to the
|
|
|
- server. They both have to be supplied with an
|
|
|
- <interfacename>InitialDirContextFactory</interfacename> instance.
|
|
|
- Unless you have special requirements, this will usually be a
|
|
|
- <classname>DefaultInitialDirContextFactory</classname> bean, which
|
|
|
- can be configured with the URL of your LDAP server and optionally
|
|
|
- with the username and password of a "manager" user which will be
|
|
|
- used by default when binding to the server (instead of binding
|
|
|
- anonymously). It currently supports "simple" LDAP
|
|
|
- authentication.</para>
|
|
|
-
|
|
|
- <para><classname>DefaultInitialDirContextFactory</classname> uses
|
|
|
- Sun's JNDI LDAP implementation by default (the one that comes with
|
|
|
- the JDK). It also supports the built in connection pooling offered
|
|
|
- by Sun's provider. Connections which are obtained either anonymously
|
|
|
- or with the "manager" user's identity will be pooled automatically.
|
|
|
- Connections obtained with a specific user's identity will not be
|
|
|
- pooled. Connection pooling can be disabled completely by setting the
|
|
|
- <property>useConnectionPool</property> property to false.</para>
|
|
|
-
|
|
|
- <para>See the <ulink
|
|
|
- url="http://acegisecurity.org/multiproject/acegi-security/xref/org/acegisecurity/providers/ldap/DefaultInitialDirContextFactory.html">class
|
|
|
- Javadoc and source</ulink> for more information on this bean and its
|
|
|
- properties.</para>
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="ldap-searchobjects">
|
|
|
- <title>LDAP Search Objects</title>
|
|
|
-
|
|
|
- <para>Often more a more complicated strategy than simple DN-matching
|
|
|
- is required to locate a user entry in the directory. This can be
|
|
|
- encapsulated in an <interfacename>LdapUserSearch</interfacename>
|
|
|
- instance which can be supplied to the authenticator implementations,
|
|
|
- for example, to allow them to locate a user. The supplied
|
|
|
- implementation is
|
|
|
- <classname>FilterBasedLdapUserSearch</classname>.</para>
|
|
|
-
|
|
|
- <sect3 id="ldap-searchobjects-filter">
|
|
|
- <title
|
|
|
- id="ldap-searchobjects-filter-based"><classname>FilterBasedLdapUserSearch</classname></title>
|
|
|
-
|
|
|
- <para>This bean uses an LDAP filter to match the user object in
|
|
|
- the directory. The process is explained in the Javadoc for the
|
|
|
- corresponding search method on the <ulink
|
|
|
- url="http://java.sun.com/j2se/1.4.2/docs/api/javax/naming/directory/DirContext.html#search(javax.naming.Name,%20java.lang.String,%20java.lang.Object[],%20javax.naming.directory.SearchControls)">JDK
|
|
|
- DirContext class</ulink>. As explained there, the search filter
|
|
|
- can be supplied with parameters. For this class, the only valid
|
|
|
- parameter is <parameter>{0}</parameter> which will be replaced
|
|
|
- with the user's login name.</para>
|
|
|
- </sect3>
|
|
|
- </sect2>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="ldap-config">
|
|
|
- <title>Configuration</title>
|
|
|
-
|
|
|
- <para>There is a version of the <link
|
|
|
- linkend="contacts-sample">Contacts Sample Application</link> which
|
|
|
- uses LDAP. You can copy the beans and filter setup from this as a
|
|
|
- starting point for configuring your own application.</para>
|
|
|
-
|
|
|
- <para>A typical configuration, using some of the beans we've discussed
|
|
|
- above, might look like this: <programlisting>
|
|
|
- <bean id="initialDirContextFactory"
|
|
|
- class="org.acegisecurity.ldap.DefaultInitialDirContextFactory">
|
|
|
- <constructor-arg value="ldap://monkeymachine:389/dc=acegisecurity,dc=org"/>
|
|
|
- <property name="managerDn"><value>cn=manager,dc=acegisecurity,dc=org</value></property>
|
|
|
- <property name="managerPassword"><value>password</value></property>
|
|
|
- </bean>
|
|
|
-
|
|
|
- <bean id="userSearch"
|
|
|
- class="org.acegisecurity.ldap.search.FilterBasedLdapUserSearch">
|
|
|
- <constructor-arg index="0">
|
|
|
- <value></value>
|
|
|
- </constructor-arg>
|
|
|
- <constructor-arg index="1">
|
|
|
- <value>(uid={0})</value>
|
|
|
- </constructor-arg>
|
|
|
- <constructor-arg index="2">
|
|
|
- <ref local="initialDirContextFactory" />
|
|
|
- </constructor-arg>
|
|
|
- <property name="searchSubtree">
|
|
|
- <value>true</value>
|
|
|
- </property>
|
|
|
- </bean>
|
|
|
-
|
|
|
- <bean id="ldapAuthProvider"
|
|
|
- class="org.acegisecurity.providers.ldap.LdapAuthenticationProvider">
|
|
|
- <constructor-arg>
|
|
|
- <bean class="org.acegisecurity.providers.ldap.authenticator.BindAuthenticator">
|
|
|
- <constructor-arg><ref local="initialDirContextFactory"/></constructor-arg>
|
|
|
- <property name="userDnPatterns"><list><value>uid={0},ou=people</value></list></property>
|
|
|
- </bean>
|
|
|
- </constructor-arg>
|
|
|
- <constructor-arg>
|
|
|
- <bean class="org.acegisecurity.providers.ldap.populator.DefaultLdapAuthoritiesPopulator">
|
|
|
- <constructor-arg><ref local="initialDirContextFactory"/></constructor-arg>
|
|
|
- <constructor-arg><value>ou=groups</value></constructor-arg>
|
|
|
- <property name="groupRoleAttribute"><value>ou</value></property>
|
|
|
- </bean>
|
|
|
- </constructor-arg>
|
|
|
- </bean>
|
|
|
-
|
|
|
- </programlisting> This would set up the provider to access an LDAP
|
|
|
- server with URL
|
|
|
- <literal>ldap://monkeymachine:389/dc=acegisecurity,dc=org</literal>.
|
|
|
- Authentication will be performed by attempting to bind with the DN
|
|
|
- <literal>uid=<user-login-name>,ou=people,dc=acegisecurity,dc=org</literal>.
|
|
|
- After successful authentication, roles will be assigned to the user by
|
|
|
- searching under the DN
|
|
|
- <literal>ou=groups,dc=acegisecurity,dc=org</literal> with the default
|
|
|
- filter <literal>(member=<user's-DN>)</literal>. The role name
|
|
|
- will be taken from the <quote>ou</quote> attribute of each
|
|
|
- match.</para>
|
|
|
-
|
|
|
- <para>We've also included the configuration for a user search object,
|
|
|
- which uses the filter
|
|
|
- <literal>(uid=<user-login-name>)</literal>. This could be used
|
|
|
- instead of the DN-pattern (or in addition to it), by setting the
|
|
|
- authenticator's <property>userSearch</property> property. The
|
|
|
- authenticator would then call the search object to obtain the correct
|
|
|
- user's DN before attempting to bind as this user.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="cas">
|
|
|
- <title>CAS Authentication</title>
|
|
|
-
|
|
|
- <sect1 id="cas-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>JA-SIG produces an enterprise-wide single sign on system known
|
|
|
- as CAS. Unlike other initiatives, JA-SIG's Central Authentication
|
|
|
- Service is open source, widely used, simple to understand, platform
|
|
|
- independent, and supports proxy capabilities. Acegi Security fully
|
|
|
- supports CAS, and provides an easy migration path from
|
|
|
- single-application deployments of Acegi Security through to
|
|
|
- multiple-application deployments secured by an enterprise-wide CAS
|
|
|
- server.</para>
|
|
|
-
|
|
|
- <para>You can learn more about CAS at
|
|
|
- <literal>http://www.ja-sig.org/products/cas/</literal>. You will need
|
|
|
- to visit this URL to download the CAS Server files. Whilst Acegi
|
|
|
- Security includes two CAS libraries in the "-with-dependencies" ZIP
|
|
|
- file, you will still need the CAS Java Server Pages and
|
|
|
- <literal>web.xml</literal> to customise and deploy your CAS
|
|
|
- server.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="cas-how-it-works">
|
|
|
- <title>How CAS Works</title>
|
|
|
-
|
|
|
- <para>Whilst the CAS web site above contains two documents that detail
|
|
|
- the architecture of CAS, we present the general overview again here
|
|
|
- within the context of Acegi Security. The following refers to both CAS
|
|
|
- 2.0 (produced by Yale) and CAS 3.0 (produced by JA-SIG), being the
|
|
|
- versions of CAS that Acegi Security supports.</para>
|
|
|
-
|
|
|
- <para>Somewhere in your enterprise you will need to setup a CAS
|
|
|
- server. The CAS server is simply a standard WAR file, so there isn't
|
|
|
- anything difficult about setting up your server. Inside the WAR file
|
|
|
- you will customise the login and other single sign on pages displayed
|
|
|
- to users.</para>
|
|
|
-
|
|
|
- <para>If you are deploying CAS 2.0, you will also need to specify in
|
|
|
- the web.xml a <literal>PasswordHandler</literal>. The
|
|
|
- <literal>PasswordHandler</literal> has a simple method that returns a
|
|
|
- boolean as to whether a given username and password is valid. Your
|
|
|
- <literal>PasswordHandler</literal> implementation will need to link
|
|
|
- into some type of backend authentication repository, such as an LDAP
|
|
|
- server or database.</para>
|
|
|
-
|
|
|
- <para>If you are already running an existing CAS 2.0 server instance,
|
|
|
- you will have already established a
|
|
|
- <literal>PasswordHandler</literal>. If you do not already have a
|
|
|
- <literal>PasswordHandler</literal>, you might prefer to use Acegi
|
|
|
- Security <literal>CasPasswordHandler</literal> class. This class
|
|
|
- delegates through to the standard Acegi Security
|
|
|
- <literal>AuthenticationManager</literal>, enabling you to use a
|
|
|
- security configuration you might already have in place. You do not
|
|
|
- need to use the <literal>CasPasswordHandler</literal> class on your
|
|
|
- CAS server if you do not wish. Acegi Security will function as a CAS
|
|
|
- client successfully irrespective of the
|
|
|
- <literal>PasswordHandler</literal> you've chosen for your CAS
|
|
|
- server.</para>
|
|
|
-
|
|
|
- <para>If you are deploying CAS 3.0, you will also need to specify an
|
|
|
- <literal>AuthenticationHandler</literal> in the
|
|
|
- deployerConfigContext.xml included with CAS. The
|
|
|
- <literal>AuthenticationHandler</literal> has a simple method that
|
|
|
- returns a boolean as to whether a given set of Credentials is valid.
|
|
|
- Your <literal>AuthenticationHandler</literal> implementation will need
|
|
|
- to link into some type of backend authentication repository, such as
|
|
|
- an LDAP server or database. CAS itself includes numerous
|
|
|
- <literal>AuthenticationHandler</literal>s out of the box to assist
|
|
|
- with this.</para>
|
|
|
-
|
|
|
- <para>If you are already running an existing CAS 3.0 server instance,
|
|
|
- you will have already established an
|
|
|
- <literal>AuthenticationHandler</literal>. If you do not already have
|
|
|
- an <literal>AuthenticationHandler</literal>, you might prefer to use
|
|
|
- Acegi Security <literal>CasAuthenticationHandler</literal> class. This
|
|
|
- class delegates through to the standard Acegi Security
|
|
|
- <literal>AuthenticationManager</literal>, enabling you to use a
|
|
|
- security configuration you might already have in place. You do not
|
|
|
- need to use the <literal>CasAuthenticationHandler</literal> class on
|
|
|
- your CAS server if you do not wish. Acegi Security will function as a
|
|
|
- CAS client successfully irrespective of the
|
|
|
- <literal>AuthenticationHandler</literal> you've chosen for your CAS
|
|
|
- server.</para>
|
|
|
-
|
|
|
- <para>Apart from the CAS server itself, the other key player is of
|
|
|
- course the secure web applications deployed throughout your
|
|
|
- enterprise. These web applications are known as "services". There are
|
|
|
- two types of services: standard services and proxy services. A proxy
|
|
|
- service is able to request resources from other services on behalf of
|
|
|
- the user. This will be explained more fully later.</para>
|
|
|
-
|
|
|
- <para>Services can be developed in a large variety of languages, due
|
|
|
- to CAS 2.0's very light XML-based protocol. The JA-SIG CAS home page
|
|
|
- contains a clients archive which demonstrates CAS clients in Java,
|
|
|
- Active Server Pages, Perl, Python and others. Naturally, Java support
|
|
|
- is very strong given the CAS server is written in Java. You do not
|
|
|
- need to use any of CAS' client classes in applications secured by
|
|
|
- Acegi Security. This is handled transparently for you.</para>
|
|
|
-
|
|
|
- <para>The basic interaction between a web browser, CAS server and an
|
|
|
- Acegi Security for System Spring secured service is as follows:</para>
|
|
|
-
|
|
|
- <orderedlist>
|
|
|
- <listitem>
|
|
|
- <para>The web user is browsing the service's public pages. CAS or
|
|
|
- Acegi Security is not involved.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The user eventually requests a page that is either secure or
|
|
|
- one of the beans it uses is secure. Acegi Security's
|
|
|
- <literal>ExceptionTranslationFilter</literal> will detect the
|
|
|
- <literal>AuthenticationException</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Because the user's <literal>Authentication</literal> object
|
|
|
- (or lack thereof) caused an
|
|
|
- <literal>AuthenticationException</literal>, the
|
|
|
- <literal>ExceptionTranslationFilter</literal> will call the
|
|
|
- configured <literal>AuthenticationEntryPoint</literal>. If using
|
|
|
- CAS, this will be the
|
|
|
- <literal>CasProcessingFilterEntryPoint</literal> class.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The <literal>CasProcessingFilterEntry</literal> point will
|
|
|
- redirect the user's browser to the CAS server. It will also
|
|
|
- indicate a <literal>service</literal> parameter, which is the
|
|
|
- callback URL for Acegi Security service. For example, the URL to
|
|
|
- which the browser is redirected might be
|
|
|
- <literal>https://my.company.com/cas/login?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_acegi_cas_security_check</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>After the user's browser redirects to CAS, they will be
|
|
|
- prompted for their username and password. If the user presents a
|
|
|
- session cookie which indicates they've previously logged on, they
|
|
|
- will not be prompted to login again (there is an exception to this
|
|
|
- procedure, which we'll cover later). CAS will use the
|
|
|
- <literal>PasswordHandler</literal> (or
|
|
|
- <literal>AuthenticationHandler</literal> if using CAS 3.0)
|
|
|
- discussed above to decide whether the username and password is
|
|
|
- valid.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Upon successful login, CAS will redirect the user's browser
|
|
|
- back to the original service. It will also include a
|
|
|
- <literal>ticket</literal> parameter, which is an opaque string
|
|
|
- representing the "service ticket". Continuing our earlier example,
|
|
|
- the URL the browser is redirected to might be
|
|
|
- <literal>https://server3.company.com/webapp/j_acegi_cas_security_check?ticket=ST-0-ER94xMJmn6pha35CQRoZ</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Back in the service web application, the
|
|
|
- <literal>CasProcessingFilter</literal> is always listening for
|
|
|
- requests to <literal>/j_acegi_cas_security_check</literal> (this
|
|
|
- is configurable, but we'll use the defaults in this introduction).
|
|
|
- The processing filter will construct a
|
|
|
- <literal>UsernamePasswordAuthenticationToken</literal>
|
|
|
- representing the service ticket. The principal will be equal to
|
|
|
- <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>,
|
|
|
- whilst the credentials will be the service ticket opaque value.
|
|
|
- This authentication request will then be handed to the configured
|
|
|
- <literal>AuthenticationManager</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The <literal>AuthenticationManager</literal> implementation
|
|
|
- will be the <literal>ProviderManager</literal>, which is in turn
|
|
|
- configured with the <literal>CasAuthenticationProvider</literal>.
|
|
|
- The <literal>CasAuthenticationProvider</literal> only responds to
|
|
|
- <literal>UsernamePasswordAuthenticationToken</literal>s containing
|
|
|
- the CAS-specific principal (such as
|
|
|
- <literal>CasProcessingFilter.CAS_STATEFUL_IDENTIFIER</literal>)
|
|
|
- and <literal>CasAuthenticationToken</literal>s (discussed
|
|
|
- later).</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>CasAuthenticationProvider</literal> will validate
|
|
|
- the service ticket using a <literal>TicketValidator</literal>
|
|
|
- implementation. Acegi Security includes one implementation, the
|
|
|
- <literal>CasProxyTicketValidator</literal>. This implementation a
|
|
|
- ticket validation class included in the CAS client library. The
|
|
|
- <literal>CasProxyTicketValidator</literal> makes a HTTPS request
|
|
|
- to the CAS server in order to validate the service ticket. The
|
|
|
- <literal>CasProxyTicketValidator</literal> may also include a
|
|
|
- proxy callback URL, which is included in this example:
|
|
|
- <literal>https://my.company.com/cas/proxyValidate?service=https%3A%2F%2Fserver3.company.com%2Fwebapp%2Fj_acegi_cas_security_check&ticket=ST-0-ER94xMJmn6pha35CQRoZ&pgtUrl=https://server3.company.com/webapp/casProxy/receptor</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Back on the CAS server, the proxy validation request will be
|
|
|
- received. If the presented service ticket matches the service URL
|
|
|
- the ticket was issued to, CAS will provide an affirmative response
|
|
|
- in XML indicating the username. If any proxy was involved in the
|
|
|
- authentication (discussed below), the list of proxies is also
|
|
|
- included in the XML response.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>[OPTIONAL] If the request to the CAS validation service
|
|
|
- included the proxy callback URL (in the <literal>pgtUrl</literal>
|
|
|
- parameter), CAS will include a <literal>pgtIou</literal> string in
|
|
|
- the XML response. This <literal>pgtIou</literal> represents a
|
|
|
- proxy-granting ticket IOU. The CAS server will then create its own
|
|
|
- HTTPS connection back to the <literal>pgtUrl</literal>. This is to
|
|
|
- mutually authenticate the CAS server and the claimed service URL.
|
|
|
- The HTTPS connection will be used to send a proxy granting ticket
|
|
|
- to the original web application. For example,
|
|
|
- <literal>https://server3.company.com/webapp/casProxy/receptor?pgtIou=PGTIOU-0-R0zlgrl4pdAQwBvJWO3vnNpevwqStbSGcq3vKB2SqSFFRnjPHt&pgtId=PGT-1-si9YkkHLrtACBo64rmsi3v2nf7cpCResXg5MpESZFArbaZiOKH</literal>.
|
|
|
- We suggest you use CAS' <literal>ProxyTicketReceptor</literal>
|
|
|
- servlet to receive these proxy-granting tickets, if they are
|
|
|
- required.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The <literal>CasProxyTicketValidator</literal> will parse
|
|
|
- the XML received from the CAS server. It will return to the
|
|
|
- <literal>CasAuthenticationProvider</literal> a
|
|
|
- <literal>TicketResponse</literal>, which includes the username
|
|
|
- (mandatory), proxy list (if any were involved), and proxy-granting
|
|
|
- ticket IOU (if the proxy callback was requested).</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Next <literal>CasAuthenticationProvider</literal> will call
|
|
|
- a configured <literal>CasProxyDecider</literal>. The
|
|
|
- <literal>CasProxyDecider</literal> indicates whether the proxy
|
|
|
- list in the <literal>TicketResponse</literal> is acceptable to the
|
|
|
- service. Several implementations are provided with Acegi Security
|
|
|
- System: <literal>RejectProxyTickets</literal>,
|
|
|
- <literal>AcceptAnyCasProxy</literal> and
|
|
|
- <literal>NamedCasProxyDecider</literal>. These names are largely
|
|
|
- self-explanatory, except <literal>NamedCasProxyDecider</literal>
|
|
|
- which allows a <literal>List</literal> of trusted proxies to be
|
|
|
- provided.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>CasAuthenticationProvider</literal> will next
|
|
|
- request a <literal>CasAuthoritiesPopulator</literal> to advise the
|
|
|
- <literal>GrantedAuthority</literal> objects that apply to the user
|
|
|
- contained in the <literal>TicketResponse</literal>. Acegi Security
|
|
|
- includes a <literal>DaoCasAuthoritiesPopulator</literal> which
|
|
|
- simply uses the <literal>UserDetailsService</literal>
|
|
|
- infrastructure to find the <literal>UserDetails</literal> and
|
|
|
- their associated <literal>GrantedAuthority</literal>s. Note that
|
|
|
- the password and enabled/disabled status of
|
|
|
- <literal>UserDetails</literal> returned by the
|
|
|
- <literal>UserDetailsService</literal> are ignored, as the CAS
|
|
|
- server is responsible for authentication decisions.
|
|
|
- <literal>DaoCasAuthoritiesPopulator</literal> is only concerned
|
|
|
- with retrieving the <literal>GrantedAuthority</literal>s.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>If there were no problems,
|
|
|
- <literal>CasAuthenticationProvider</literal> constructs a
|
|
|
- <literal>CasAuthenticationToken</literal> including the details
|
|
|
- contained in the <literal>TicketResponse</literal> and the
|
|
|
- <literal>GrantedAuthority</literal>s. The
|
|
|
- <literal>CasAuthenticationToken</literal> contains the hash of a
|
|
|
- key, so that the <literal>CasAuthenticationProvider</literal>
|
|
|
- knows it created it.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Control then returns to
|
|
|
- <literal>CasProcessingFilter</literal>, which places the created
|
|
|
- <literal>CasAuthenticationToken</literal> into the
|
|
|
- <literal>HttpSession</literal> attribute named
|
|
|
- <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>The user's browser is redirected to the original page that
|
|
|
- caused the <literal>AuthenticationException</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>As the <literal>Authentication</literal> object is now in
|
|
|
- the well-known location, it is handled like any other
|
|
|
- authentication approach. Usually the
|
|
|
- <literal>HttpSessionIntegrationFilter</literal> will be used to
|
|
|
- associate the <literal>Authentication</literal> object with the
|
|
|
- <literal>SecurityContextHolder</literal> for the duration of each
|
|
|
- request.</para>
|
|
|
- </listitem>
|
|
|
- </orderedlist>
|
|
|
-
|
|
|
- <para>It's good that you're still here! It might sound involved, but
|
|
|
- you can relax as Acegi Security classes hide much of the complexity.
|
|
|
- Let's now look at how this is configured</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="cas-server">
|
|
|
- <title>Optional CAS Server Setup</title>
|
|
|
-
|
|
|
- <para>Acegi Security can even act as the backend which a CAS version
|
|
|
- 2.0 or 3.0 server utilises. The configuration approach is described
|
|
|
- below. Of course, if you have an existing CAS environment you might
|
|
|
- just like to use it instead.</para>
|
|
|
-
|
|
|
- <sect2 id="cas-server-2">
|
|
|
- <title>CAS Version 2.0</title>
|
|
|
-
|
|
|
- <para>As mentioned above, Acegi Security includes a
|
|
|
- <literal>PasswordHandler</literal> that bridges your existing
|
|
|
- <literal>AuthenticationManager</literal> into CAS 2.0. You do not
|
|
|
- need to use this <literal>PasswordHandler</literal> to use Acegi
|
|
|
- Security on the client side (any CAS
|
|
|
- <literal>PasswordHandler</literal> will do).</para>
|
|
|
-
|
|
|
- <para>To install, you will need to download and extract the CAS
|
|
|
- server archive. We used version 2.0.12. There will be a
|
|
|
- <literal>/web</literal> directory in the root of the deployment.
|
|
|
- Copy an <literal>applicationContext.xml</literal> containing your
|
|
|
- <literal>AuthenticationManager</literal> as well as the
|
|
|
- <literal>CasPasswordHandler</literal> into the
|
|
|
- <literal>/web/WEB-INF</literal> directory. A sample
|
|
|
- <literal>applicationContext.xml</literal> is included below:</para>
|
|
|
-
|
|
|
- <programlisting>
|
|
|
-<bean id="inMemoryDaoImpl" class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl">
|
|
|
- <property name="userMap">
|
|
|
- <value>
|
|
|
- marissa=koala,ROLES_IGNORED_BY_CAS
|
|
|
- dianne=emu,ROLES_IGNORED_BY_CAS
|
|
|
- scott=wombat,ROLES_IGNORED_BY_CAS
|
|
|
- peter=opal,disabled,ROLES_IGNORED_BY_CAS
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="daoAuthenticationProvider" class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
|
|
|
- <property name="userDetailsService"><ref bean="inMemoryDaoImpl"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="authenticationManager" class="org.acegisecurity.providers.ProviderManager">
|
|
|
- <property name="providers">
|
|
|
- <list>
|
|
|
- <ref bean="daoAuthenticationProvider"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="casPasswordHandler" class="org.acegisecurity.adapters.cas.CasPasswordHandler">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting>
|
|
|
-
|
|
|
- <para>Note the granted authorities are ignored by CAS because it has
|
|
|
- no way of communicating the granted authorities to calling
|
|
|
- applications. CAS is only concerned with username and passwords (and
|
|
|
- the enabled/disabled status).</para>
|
|
|
-
|
|
|
- <para>Next you will need to edit the existing
|
|
|
- <literal>/web/WEB-INF/web.xml</literal> file. Add (or edit in the
|
|
|
- case of the <literal>authHandler</literal> property) the following
|
|
|
- lines:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-
|
|
|
-<context-param>
|
|
|
- <param-name>edu.yale.its.tp.cas.authHandler</param-name>
|
|
|
- <param-value>org.acegisecurity.adapters.cas.CasPasswordHandlerProxy</param-value>
|
|
|
-</context-param>
|
|
|
-
|
|
|
-<context-param>
|
|
|
- <param-name>contextConfigLocation</param-name>
|
|
|
- <param-value>/WEB-INF/applicationContext.xml</param-value>
|
|
|
-</context-param>
|
|
|
-
|
|
|
-<listener>
|
|
|
- <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
|
|
|
-</listener>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>Copy the <literal>spring.jar</literal> and
|
|
|
- <literal>acegi-security.jar</literal> files into
|
|
|
- <literal>/web/WEB-INF/lib</literal>. Now use the <literal>ant
|
|
|
- dist</literal> task in the <literal>build.xml</literal> in the root
|
|
|
- of the directory structure. This will create
|
|
|
- <literal>/lib/cas.war</literal>, which is ready for deployment to
|
|
|
- your servlet container.</para>
|
|
|
-
|
|
|
- <para>Note CAS heavily relies on HTTPS. You can't even test the
|
|
|
- system without a HTTPS certificate. Whilst you should refer to your
|
|
|
- web container's documentation on setting up HTTPS, if you need some
|
|
|
- additional help or a test certificate you might like to check the
|
|
|
- <literal>samples/contacts/etc/ssl</literal> directory</para>
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="cas-server-3">
|
|
|
- <title>CAS Version 3.0</title>
|
|
|
-
|
|
|
- <para>As mentioned above, Acegi Security includes an
|
|
|
- <literal>AuthenticationHandler</literal> that bridges your existing
|
|
|
- <literal>AuthenticationManager</literal> into CAS 3.0. You do not
|
|
|
- need to use this <literal>AuthenticationHandler</literal> to use
|
|
|
- Acegi Security on the client side (any CAS
|
|
|
- <literal>AuthenticationHandler</literal> will do).</para>
|
|
|
-
|
|
|
- <para>To install, you will need to download and extract the CAS
|
|
|
- server archive. We used version 3.0.4. There will be a
|
|
|
- <literal>/webapp</literal> directory in the root of the deployment.
|
|
|
- Edit the an <literal>deployerConfigContext.xml</literal> so that it
|
|
|
- contains your <literal>AuthenticationManager</literal> as well as
|
|
|
- the <literal>CasAuthenticationHandler</literal>. A sample
|
|
|
- <literal>applicationContext.xml</literal> is included below:</para>
|
|
|
-
|
|
|
- <programlisting>
|
|
|
- <?xml version="1.0" encoding="UTF-8"?>
|
|
|
- <!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN" "http://www.springframework.org/dtd/spring-beans.dtd">
|
|
|
- <beans>
|
|
|
- <bean
|
|
|
- id="authenticationManager"
|
|
|
- class="org.jasig.cas.authentication.AuthenticationManagerImpl">
|
|
|
- <property name="credentialsToPrincipalResolvers">
|
|
|
- <list>
|
|
|
- <bean class="org.jasig.cas.authentication.principal.UsernamePasswordCredentialsToPrincipalResolver" />
|
|
|
- <bean class="org.jasig.cas.authentication.principal.HttpBasedServiceCredentialsToPrincipalResolver" />
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-
|
|
|
- <property name="authenticationHandlers">
|
|
|
- <list>
|
|
|
- <bean class="org.jasig.cas.authentication.handler.support.HttpBasedServiceCredentialsAuthenticationHandler" />
|
|
|
- <bean class="org.acegisecurity.adapters.cas3.CasAuthenticationHandler">
|
|
|
- <property name="authenticationManager" ref="acegiAuthenticationManager" />
|
|
|
- </bean>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
- </bean>
|
|
|
-
|
|
|
-
|
|
|
- <bean id="inMemoryDaoImpl" class="org.acegisecurity.userdetails.memory.InMemoryDaoImpl">
|
|
|
- <property name="userMap">
|
|
|
- <value>
|
|
|
- marissa=koala,ROLES_IGNORED_BY_CAS
|
|
|
- dianne=emu,ROLES_IGNORED_BY_CAS
|
|
|
- scott=wombat,ROLES_IGNORED_BY_CAS
|
|
|
- peter=opal,disabled,ROLES_IGNORED_BY_CAS
|
|
|
- </value>
|
|
|
- </property>
|
|
|
- </bean>
|
|
|
-
|
|
|
- <bean id="daoAuthenticationProvider" class="org.acegisecurity.providers.dao.DaoAuthenticationProvider">
|
|
|
- <property name="userDetailsService"><ref bean="inMemoryDaoImpl"/></property>
|
|
|
- </bean>
|
|
|
-
|
|
|
- <bean id="acegiAuthenticationManager" class="org.acegisecurity.providers.ProviderManager">
|
|
|
- <property name="providers">
|
|
|
- <list>
|
|
|
- <ref bean="daoAuthenticationProvider"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
- </bean>
|
|
|
- </beans>
|
|
|
-
|
|
|
- </programlisting>
|
|
|
-
|
|
|
- <para>Note the granted authorities are ignored by CAS because it has
|
|
|
- no way of communicating the granted authorities to calling
|
|
|
- applications. CAS is only concerned with username and passwords (and
|
|
|
- the enabled/disabled status).</para>
|
|
|
-
|
|
|
- <para>Copy <literal>acegi-security.jar</literal> and
|
|
|
- <literal>acegi-security-cas.jar</literal> files into
|
|
|
- <literal>/localPlugins/lib</literal>. Now use the <literal>ant
|
|
|
- war</literal> task in the <literal>build.xml</literal> in the
|
|
|
- /localPlugins directory. This will create
|
|
|
- <literal>/localPlugins/target/cas.war</literal>, which is ready for
|
|
|
- deployment to your servlet container.</para>
|
|
|
-
|
|
|
- <para>Note CAS heavily relies on HTTPS. You can't even test the
|
|
|
- system without a HTTPS certificate. Whilst you should refer to your
|
|
|
- web container's documentation on setting up HTTPS, if you need some
|
|
|
- additional help or a test certificate you might like to check the
|
|
|
- CAS documentation on setting up SSL:
|
|
|
- <literal>http://www.ja-sig.org/products/cas/server/ssl/index.html</literal></para>
|
|
|
- </sect2>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="cas-client">
|
|
|
- <title>Configuration of CAS Client</title>
|
|
|
-
|
|
|
- <para>The web application side of CAS is made easy due to Acegi
|
|
|
- Security. It is assumed you already know the basics of using Acegi
|
|
|
- Security, so these are not covered again below. Only the CAS-specific
|
|
|
- beans are mentioned.</para>
|
|
|
-
|
|
|
- <para>You will need to add a <literal>ServiceProperties</literal> bean
|
|
|
- to your application context. This represents your service:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-
|
|
|
-<bean id="serviceProperties" class="org.acegisecurity.ui.cas.ServiceProperties">
|
|
|
- <property name="service"><value>https://localhost:8443/contacts-cas/j_acegi_cas_security_check</value></property>
|
|
|
- <property name="sendRenew"><value>false</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>service</literal> must equal a URL that will be
|
|
|
- monitored by the <literal>CasProcessingFilter</literal>. The
|
|
|
- <literal>sendRenew</literal> defaults to false, but should be set to
|
|
|
- true if your application is particularly sensitive. What this
|
|
|
- parameter does is tell the CAS login service that a single sign on
|
|
|
- login is unacceptable. Instead, the user will need to re-enter their
|
|
|
- username and password in order to gain access to the service.</para>
|
|
|
-
|
|
|
- <para>The following beans should be configured to commence the CAS
|
|
|
- authentication process:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="casProcessingFilter" class="org.acegisecurity.ui.cas.CasProcessingFilter">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="authenticationFailureUrl"><value>/casfailed.jsp</value></property>
|
|
|
- <property name="defaultTargetUrl"><value>/</value></property>
|
|
|
- <property name="filterProcessesUrl"><value>/j_acegi_cas_security_check</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="exceptionTranslationFilter" class="org.acegisecurity.ui.ExceptionTranslationFilter">
|
|
|
- <property name="authenticationEntryPoint"><ref local="casProcessingFilterEntryPoint"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="casProcessingFilterEntryPoint" class="org.acegisecurity.ui.cas.CasProcessingFilterEntryPoint">
|
|
|
- <property name="loginUrl"><value>https://localhost:8443/cas/login</value></property>
|
|
|
- <property name="serviceProperties"><ref bean="serviceProperties"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>You will also need to add the
|
|
|
- <literal>CasProcessingFilter</literal> to web.xml:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<filter>
|
|
|
- <filter-name>Acegi CAS Processing Filter</filter-name>
|
|
|
- <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
|
|
|
- <init-param>
|
|
|
- <param-name>targetClass</param-name>
|
|
|
- <param-value>org.acegisecurity.ui.cas.CasProcessingFilter</param-value>
|
|
|
- </init-param>
|
|
|
-</filter>
|
|
|
-
|
|
|
-<filter-mapping>
|
|
|
- <filter-name>Acegi CAS Processing Filter</filter-name>
|
|
|
- <url-pattern>/*</url-pattern>
|
|
|
-</filter-mapping>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>CasProcessingFilter</literal> has very similar
|
|
|
- properties to the <literal>AuthenticationProcessingFilter</literal>
|
|
|
- (used for form-based logins). Each property is
|
|
|
- self-explanatory.</para>
|
|
|
-
|
|
|
- <para>For CAS to operate, the
|
|
|
- <literal>ExceptionTranslationFilter</literal> must have its
|
|
|
- <literal>authenticationEntryPoint</literal> property set to the
|
|
|
- <literal>CasProcessingFilterEntryPoint</literal> bean.</para>
|
|
|
-
|
|
|
- <para>The <literal>CasProcessingFilterEntryPoint</literal> must refer
|
|
|
- to the <literal>ServiceProperties</literal> bean (discussed above),
|
|
|
- which provides the URL to the enterprise's CAS login server. This is
|
|
|
- where the user's browser will be redirected.</para>
|
|
|
-
|
|
|
- <para>Next you need to add an <literal>AuthenticationManager</literal>
|
|
|
- that uses <literal>CasAuthenticationProvider</literal> and its
|
|
|
- collaborators:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<bean id="authenticationManager" class="org.acegisecurity.providers.ProviderManager">
|
|
|
- <property name="providers">
|
|
|
- <list>
|
|
|
- <ref bean="casAuthenticationProvider"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="casAuthenticationProvider" class="org.acegisecurity.providers.cas.CasAuthenticationProvider">
|
|
|
- <property name="casAuthoritiesPopulator"><ref bean="casAuthoritiesPopulator"/></property>
|
|
|
- <property name="casProxyDecider"><ref bean="casProxyDecider"/></property>
|
|
|
- <property name="ticketValidator"><ref bean="casProxyTicketValidator"/></property>
|
|
|
- <property name="statelessTicketCache"><ref bean="statelessTicketCache"/></property>
|
|
|
- <property name="key"><value>my_password_for_this_auth_provider_only</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="casProxyTicketValidator" class="org.acegisecurity.providers.cas.ticketvalidator.CasProxyTicketValidator">
|
|
|
- <property name="casValidate"><value>https://localhost:8443/cas/proxyValidate</value></property>
|
|
|
- <property name="proxyCallbackUrl"><value>https://localhost:8443/contacts-cas/casProxy/receptor</value></property>
|
|
|
- <property name="serviceProperties"><ref bean="serviceProperties"/></property>
|
|
|
- <!-- <property name="trustStore"><value>/some/path/to/your/lib/security/cacerts</value></property> -->
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="cacheManager" class="org.springframework.cache.ehcache.EhCacheManagerFactoryBean">
|
|
|
- <property name="configLocation">
|
|
|
- <value>classpath:/ehcache-failsafe.xml</value>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="ticketCacheBackend" class="org.springframework.cache.ehcache.EhCacheFactoryBean">
|
|
|
- <property name="cacheManager">
|
|
|
- <ref local="cacheManager"/>
|
|
|
- </property>
|
|
|
- <property name="cacheName">
|
|
|
- <value>ticketCache</value>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="statelessTicketCache" class="org.acegisecurity.providers.cas.cache.EhCacheBasedTicketCache">
|
|
|
- <property name="cache"><ref local="ticketCacheBackend"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="casAuthoritiesPopulator" class="org.acegisecurity.providers.cas.populator.DaoCasAuthoritiesPopulator">
|
|
|
- <property name="userDetailsService"><ref bean="inMemoryDaoImpl"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="casProxyDecider" class="org.acegisecurity.providers.cas.proxy.RejectProxyTickets"/>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>The beans are all reasonable self-explanatory if you refer back
|
|
|
- to the "How CAS Works" section. Careful readers might notice one
|
|
|
- surprise: the <literal>statelessTicketCache</literal> property of the
|
|
|
- <literal>CasAuthenticationProvider</literal>. This is discussed in
|
|
|
- detail in the "Advanced CAS Usage" section.</para>
|
|
|
-
|
|
|
- <para>Note the <literal>CasProxyTicketValidator</literal> has a
|
|
|
- remarked out <literal>trustStore</literal> property. This property
|
|
|
- might be helpful if you experience HTTPS certificate issues. Also note
|
|
|
- the <literal>proxyCallbackUrl</literal> is set so the service can
|
|
|
- receive a proxy-granting ticket. As mentioned above, this is optional
|
|
|
- and unnecessary if you do not require proxy-granting tickets. If you
|
|
|
- do use this feature, you will need to configure a suitable servlet to
|
|
|
- receive the proxy-granting tickets. We suggest you use CAS'
|
|
|
- <literal>ProxyTicketReceptor</literal> by adding the following to your
|
|
|
- web application's <literal>web.xml</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<servlet>
|
|
|
- <servlet-name>casproxy</servlet-name>
|
|
|
- <servlet-class>edu.yale.its.tp.cas.proxy.ProxyTicketReceptor</servlet-class>
|
|
|
-</servlet>
|
|
|
-
|
|
|
-<servlet-mapping>
|
|
|
- <servlet-name>casproxy</servlet-name>
|
|
|
- <url-pattern>/casProxy/*</url-pattern>
|
|
|
-</servlet-mapping>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>This completes the configuration of CAS. If you haven't made any
|
|
|
- mistakes, your web application should happily work within the
|
|
|
- framework of CAS single sign on. No other parts of Acegi Security need
|
|
|
- to be concerned about the fact CAS handled authentication.</para>
|
|
|
-
|
|
|
- <para>There is also a <literal>contacts-cas.war</literal> file in the
|
|
|
- sample applications directory. This sample application uses the above
|
|
|
- settings and can be deployed to see CAS in operation</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="cas-advanced">
|
|
|
- <title>Advanced Issues</title>
|
|
|
-
|
|
|
- <para>The <literal>CasAuthenticationProvider</literal> distinguishes
|
|
|
- between stateful and stateless clients. A stateful client is
|
|
|
- considered any that originates via the
|
|
|
- <literal>CasProcessingFilter</literal>. A stateless client is any that
|
|
|
- presents an authentication request via the
|
|
|
- <literal>UsernamePasswordAuthenticationToken</literal> with a
|
|
|
- principal equal to
|
|
|
- <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>.</para>
|
|
|
-
|
|
|
- <para>Stateless clients are likely to be via remoting protocols such
|
|
|
- as Hessian and Burlap. The <literal>BasicProcessingFilter</literal> is
|
|
|
- still used in this case, but the remoting protocol client is expected
|
|
|
- to present a username equal to the static string above, and a password
|
|
|
- equal to a CAS service ticket. Clients should acquire a CAS service
|
|
|
- ticket directly from the CAS server.</para>
|
|
|
-
|
|
|
- <para>Because remoting protocols have no way of presenting themselves
|
|
|
- within the context of a <literal>HttpSession</literal>, it isn't
|
|
|
- possible to rely on the <literal>HttpSession</literal>'s
|
|
|
- <literal>HttpSessionIntegrationFilter.ACEGI_SECURITY_AUTHENTICATION_KEY</literal>
|
|
|
- attribute to locate the <literal>CasAuthenticationToken</literal>.
|
|
|
- Furthermore, because the CAS server invalidates a service ticket after
|
|
|
- it has been validated by the <literal>TicketValidator</literal>,
|
|
|
- presenting the same service ticket on subsequent requests will not
|
|
|
- work. It is similarly very difficult to obtain a proxy-granting ticket
|
|
|
- for a remoting protocol client, as they are often deployed on client
|
|
|
- machines which rarely have HTTPS URLs that would be accessible to the
|
|
|
- CAS server.</para>
|
|
|
-
|
|
|
- <para>One obvious option is to not use CAS at all for remoting
|
|
|
- protocol clients. However, this would eliminate many of the desirable
|
|
|
- features of CAS.</para>
|
|
|
-
|
|
|
- <para>As a middle-ground, the
|
|
|
- <literal>CasAuthenticationProvider</literal> uses a
|
|
|
- <literal>StatelessTicketCache</literal>. This is used solely for
|
|
|
- requests with a principal equal to
|
|
|
- <literal>CasProcessingFilter.CAS_STATELESS_IDENTIFIER</literal>. What
|
|
|
- happens is the <literal>CasAuthenticationProvider</literal> will store
|
|
|
- the resulting <literal>CasAuthenticationToken</literal> in the
|
|
|
- <literal>StatelessTicketCache</literal>, keyed on the service ticket.
|
|
|
- Accordingly, remoting protocol clients can present the same service
|
|
|
- ticket and the <literal>CasAuthenticationProvider</literal> will not
|
|
|
- need to contact the CAS server for validation (aside from the first
|
|
|
- request).</para>
|
|
|
-
|
|
|
- <para>The other aspect of advanced CAS usage involves creating proxy
|
|
|
- tickets from the proxy-granting ticket. As indicated above, we
|
|
|
- recommend you use CAS' <literal>ProxyTicketReceptor</literal> to
|
|
|
- receive these tickets. The <literal>ProxyTicketReceptor</literal>
|
|
|
- provides a static method that enables you to obtain a proxy ticket by
|
|
|
- presenting the proxy-granting IOU ticket. You can obtain the
|
|
|
- proxy-granting IOU ticket by calling
|
|
|
- <literal>CasAuthenticationToken.getProxyGrantingTicketIou()</literal>.</para>
|
|
|
-
|
|
|
- <para>It is hoped you find CAS integration easy and useful with Acegi
|
|
|
- Security classes. Welcome to enterprise-wide single sign on!</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="ca">
|
|
|
- <title>Container Adapter Authentication</title>
|
|
|
-
|
|
|
- <sect1 id="ca-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>Very early versions of Acegi Security exclusively used Container
|
|
|
- Adapters for interfacing authentication with end users. Whilst this
|
|
|
- worked well, it required considerable time to support multiple
|
|
|
- container versions and the configuration itself was relatively
|
|
|
- time-consuming for developers. For this reason the HTTP Form
|
|
|
- Authentication and HTTP Basic Authentication approaches were
|
|
|
- developed, and are today recommended for almost all
|
|
|
- applications.</para>
|
|
|
-
|
|
|
- <para>Container Adapters enable Acegi Security to integrate directly
|
|
|
- with the containers used to host end user applications. This
|
|
|
- integration means that applications can continue to leverage the
|
|
|
- authentication and authorization capabilities built into containers
|
|
|
- (such as <literal>isUserInRole()</literal> and form-based or basic
|
|
|
- authentication), whilst benefiting from the enhanced security
|
|
|
- interception capabilities provided by Acegi Security (it should be
|
|
|
- noted that Acegi Security also offers
|
|
|
- <literal>ContextHolderAwareRequestWrapper</literal> to deliver
|
|
|
- <literal>isUserInRole()</literal> and similar Servlet Specification
|
|
|
- compatibility methods).</para>
|
|
|
-
|
|
|
- <para>The integration between a container and Acegi Security is
|
|
|
- achieved through an adapter. The adapter provides a
|
|
|
- container-compatible user authentication provider, and needs to return
|
|
|
- a container-compatible user object.</para>
|
|
|
-
|
|
|
- <para>The adapter is instantiated by the container and is defined in a
|
|
|
- container-specific configuration file. The adapter then loads a Spring
|
|
|
- application context which defines the normal authentication manager
|
|
|
- settings, such as the authentication providers that can be used to
|
|
|
- authenticate the request. The application context is usually named
|
|
|
- <literal>acegisecurity.xml</literal> and is placed in a
|
|
|
- container-specific location.</para>
|
|
|
-
|
|
|
- <para>Acegi Security currently supports Jetty, Catalina (Tomcat),
|
|
|
- JBoss and Resin. Additional container adapters can easily be
|
|
|
- written</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="ca-adapter">
|
|
|
- <title>Adapter Authentication Provider</title>
|
|
|
-
|
|
|
- <para>As is always the case, the container adapter generated
|
|
|
- <literal>Authentication</literal> object still needs to be
|
|
|
- authenticated by an <literal>AuthenticationManager</literal> when
|
|
|
- requested to do so by the
|
|
|
- <literal>AbstractSecurityInterceptor</literal>. The
|
|
|
- <literal>AuthenticationManager</literal> needs to be certain the
|
|
|
- adapter-provided <literal>Authentication</literal> object is valid and
|
|
|
- was actually authenticated by a trusted adapter.</para>
|
|
|
-
|
|
|
- <para>Adapters create <literal>Authentication</literal> objects which
|
|
|
- are immutable and implement the <literal>AuthByAdapter</literal>
|
|
|
- interface. These objects store the hash of a key that is defined by
|
|
|
- the adapter. This allows the <literal>Authentication</literal> object
|
|
|
- to be validated by the <literal>AuthByAdapterProvider</literal>. This
|
|
|
- authentication provider is defined as follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="authByAdapterProvider" class="org.acegisecurity.adapters.AuthByAdapterProvider">
|
|
|
- <property name="key"><value>my_password</value></property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>The key must match the key that is defined in the
|
|
|
- container-specific configuration file that starts the adapter. The
|
|
|
- <literal>AuthByAdapterProvider</literal> automatically accepts as
|
|
|
- valid any <literal>AuthByAdapter</literal> implementation that returns
|
|
|
- the expected hash of the key.</para>
|
|
|
-
|
|
|
- <para>To reiterate, this means the adapter will perform the initial
|
|
|
- authentication using providers such as
|
|
|
- <literal>DaoAuthenticationProvider</literal>, returning an
|
|
|
- <literal>AuthByAdapter</literal> instance that contains a hash code of
|
|
|
- the key. Later, when an application calls a security interceptor
|
|
|
- managed resource, the <literal>AuthByAdapter</literal> instance in the
|
|
|
- <literal>SecurityContext</literal> in the
|
|
|
- <literal>SecurityContextHolder</literal> will be tested by the
|
|
|
- application's <literal>AuthByAdapterProvider</literal>. There is no
|
|
|
- requirement for additional authentication providers such as
|
|
|
- <literal>DaoAuthenticationProvider</literal> within the
|
|
|
- application-specific application context, as the only type of
|
|
|
- <literal>Authentication</literal> instance that will be presented by
|
|
|
- the application is from the container adapter.</para>
|
|
|
-
|
|
|
- <para>Classloader issues are frequent with containers and the use of
|
|
|
- container adapters illustrates this further. Each container requires a
|
|
|
- very specific configuration. The installation instructions are
|
|
|
- provided below. Once installed, please take the time to try the sample
|
|
|
- application to ensure your container adapter is properly
|
|
|
- configured.</para>
|
|
|
-
|
|
|
- <para>When using container adapters with the
|
|
|
- <literal>DaoAuthenticationProvider</literal>, ensure you set its
|
|
|
- <literal>forcePrincipalAsString</literal> property to
|
|
|
- <literal>true</literal>.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="ca-jetty">
|
|
|
- <title>Jetty</title>
|
|
|
-
|
|
|
- <para>The following was tested with Jetty 4.2.18.</para>
|
|
|
-
|
|
|
- <para><literal>$JETTY_HOME</literal> refers to the root of your Jetty
|
|
|
- installation.</para>
|
|
|
-
|
|
|
- <para>Edit your <literal>$JETTY_HOME/etc/jetty.xml</literal> file so
|
|
|
- the <literal><Configure class></literal> section has a new
|
|
|
- <literal>addRealm</literal> call:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
- <Call name="addRealm">
|
|
|
- <Arg>
|
|
|
- <New class="org.acegisecurity.adapters.jetty.JettyAcegiUserRealm">
|
|
|
- <Arg>Spring Powered Realm</Arg>
|
|
|
- <Arg>my_password</Arg>
|
|
|
- <Arg>etc/acegisecurity.xml</Arg>
|
|
|
- </New>
|
|
|
- </Arg>
|
|
|
- </Call>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>Copy <literal>acegisecurity.xml</literal> into
|
|
|
- <literal>$JETTY_HOME/etc</literal>.</para>
|
|
|
-
|
|
|
- <para>Copy the following files into
|
|
|
- <literal>$JETTY_HOME/ext</literal>:<itemizedlist>
|
|
|
- <listitem>
|
|
|
- <para><literal>aopalliance.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>commons-logging.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>spring.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>acegi-security-jetty-XX.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>commons-codec.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>burlap.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>hessian.jar</literal></para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist></para>
|
|
|
-
|
|
|
- <para>None of the above JAR files (or
|
|
|
- <literal>acegi-security-XX.jar</literal>) should be in your
|
|
|
- application's <literal>WEB-INF/lib</literal>. The realm name indicated
|
|
|
- in your <literal>web.xml</literal> does matter with Jetty. The
|
|
|
- <literal>web.xml</literal> must express the same
|
|
|
- <literal><realm-name></literal> as your
|
|
|
- <literal>jetty.xml</literal> (in the example above, "Spring Powered
|
|
|
- Realm").</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="ca-jboss">
|
|
|
- <title>JBoss</title>
|
|
|
-
|
|
|
- <para>The following was tested with JBoss 3.2.6.</para>
|
|
|
-
|
|
|
- <para><literal>$JBOSS_HOME</literal> refers to the root of your JBoss
|
|
|
- installation.</para>
|
|
|
-
|
|
|
- <para>There are two different ways of making spring context available
|
|
|
- to the Jboss integration classes.</para>
|
|
|
-
|
|
|
- <para>The first approach is by editing your
|
|
|
- <literal>$JBOSS_HOME/server/your_config/conf/login-config.xml</literal>
|
|
|
- file so that it contains a new entry under the
|
|
|
- <literal><Policy></literal> section:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<application-policy name = "SpringPoweredRealm">
|
|
|
- <authentication>
|
|
|
- <login-module code = "org.acegisecurity.adapters.jboss.JbossAcegiLoginModule"
|
|
|
- flag = "required">
|
|
|
- <module-option name = "appContextLocation">acegisecurity.xml</module-option>
|
|
|
- <module-option name = "key">my_password</module-option>
|
|
|
- </login-module>
|
|
|
- </authentication>
|
|
|
-</application-policy>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>Copy <literal>acegisecurity.xml</literal> into
|
|
|
- <literal>$JBOSS_HOME/server/your_config/conf</literal>.</para>
|
|
|
-
|
|
|
- <para>In this configuration <literal>acegisecurity.xml</literal>
|
|
|
- contains the spring context definition including all the
|
|
|
- authentication manager beans. You have to bear in mind though, that
|
|
|
- <literal>SecurityContext</literal> is created and destroyed on each
|
|
|
- login request, so the login operation might become costly.
|
|
|
- Alternatively, the second approach is to use Spring singleton
|
|
|
- capabilities through
|
|
|
- <literal>org.springframework.beans.factory.access.SingletonBeanFactoryLocator</literal>.
|
|
|
- The required configuration for this approach is:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<application-policy name = "SpringPoweredRealm">
|
|
|
- <authentication>
|
|
|
- <login-module code = "org.acegisecurity.adapters.jboss.JbossAcegiLoginModule"
|
|
|
- flag = "required">
|
|
|
- <module-option name = "singletonId">springRealm</module-option>
|
|
|
- <module-option name = "key">my_password</module-option>
|
|
|
- <module-option name = "authenticationManager">authenticationManager</module-option>
|
|
|
- </login-module>
|
|
|
- </authentication>
|
|
|
-</application-policy>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>In the above code fragment,
|
|
|
- <literal>authenticationManager</literal> is a helper property that
|
|
|
- defines the expected name of the
|
|
|
- <literal>AuthenticationManager</literal> in case you have several
|
|
|
- defined in the IoC container. The <literal>singletonId</literal>
|
|
|
- property references a bean defined in a
|
|
|
- <literal>beanRefFactory.xml</literal> file. This file needs to be
|
|
|
- available from anywhere on the JBoss classpath, including
|
|
|
- <literal>$JBOSS_HOME/server/your_config/conf</literal>. The
|
|
|
- <literal>beanRefFactory.xml</literal> contains the following
|
|
|
- declaration:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<beans>
|
|
|
- <bean id="springRealm" singleton="true" lazy-init="true" class="org.springframework.context.support.ClassPathXmlApplicationContext">
|
|
|
- <constructor-arg>
|
|
|
- <list>
|
|
|
- <value>acegisecurity.xml</value>
|
|
|
- </list>
|
|
|
- </constructor-arg>
|
|
|
- </bean>
|
|
|
-</beans>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>Finally, irrespective of the configuration approach you need to
|
|
|
- copy the following files into
|
|
|
- <literal>$JBOSS_HOME/server/your_config/lib</literal>:<itemizedlist>
|
|
|
- <listitem>
|
|
|
- <para><literal>aopalliance.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>spring.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>acegi-security-jboss-XX.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>commons-codec.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>burlap.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>hessian.jar</literal></para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist></para>
|
|
|
-
|
|
|
- <para>None of the above JAR files (or
|
|
|
- <literal>acegi-security-XX.jar</literal>) should be in your
|
|
|
- application's <literal>WEB-INF/lib</literal>. The realm name indicated
|
|
|
- in your <literal>web.xml</literal> does not matter with JBoss.
|
|
|
- However, your web application's
|
|
|
- <literal>WEB-INF/jboss-web.xml</literal> must express the same
|
|
|
- <literal><security-domain></literal> as your
|
|
|
- <literal>login-config.xml</literal>. For example, to match the above
|
|
|
- example, your <literal>jboss-web.xml</literal> would look like
|
|
|
- this:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<jboss-web>
|
|
|
- <security-domain>java:/jaas/SpringPoweredRealm</security-domain>
|
|
|
-</jboss-web></programlisting></para>
|
|
|
-
|
|
|
- <para>JBoss is a widely-used container adapter (mostly due to the need
|
|
|
- to support legacy EJBs), so please let us know if you have any
|
|
|
- difficulties.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="ca-resin">
|
|
|
- <title>Resin</title>
|
|
|
-
|
|
|
- <para>The following was tested with Resin 3.0.6.</para>
|
|
|
-
|
|
|
- <para><literal>$RESIN_HOME</literal> refers to the root of your Resin
|
|
|
- installation.</para>
|
|
|
-
|
|
|
- <para>Resin provides several ways to support the container adapter. In
|
|
|
- the instructions below we have elected to maximise consistency with
|
|
|
- other container adapter configurations. This will allow Resin users to
|
|
|
- simply deploy the sample application and confirm correct
|
|
|
- configuration. Developers comfortable with Resin are naturally able to
|
|
|
- use its capabilities to package the JARs with the web application
|
|
|
- itself, and/or support single sign-on.</para>
|
|
|
-
|
|
|
- <para>Copy the following files into
|
|
|
- <literal>$RESIN_HOME/lib</literal>:<itemizedlist>
|
|
|
- <listitem>
|
|
|
- <para><literal>aopalliance.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>commons-logging.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>spring.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>acegi-security-resin-XX.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>commons-codec.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>burlap.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>hessian.jar</literal></para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist></para>
|
|
|
-
|
|
|
- <para>Unlike the container-wide <literal>acegisecurity.xml</literal>
|
|
|
- files used by other container adapters, each Resin web application
|
|
|
- will contain its own
|
|
|
- <literal>WEB-INF/resin-acegisecurity.xml</literal> file. Each web
|
|
|
- application will also contain a <literal>resin-web.xml</literal> file
|
|
|
- which Resin uses to start the container adapter:</para>
|
|
|
-
|
|
|
- <para><programlisting>
|
|
|
-<web-app>
|
|
|
- <authenticator>
|
|
|
- <type>org.acegisecurity.adapters.resin.ResinAcegiAuthenticator</type>
|
|
|
- <init>
|
|
|
- <app-context-location>WEB-INF/resin-acegisecurity.xml</app-context-location>
|
|
|
- <key>my_password</key>
|
|
|
- </init>
|
|
|
- </authenticator>
|
|
|
-</web-app>
|
|
|
-
|
|
|
- </programlisting></para>
|
|
|
-
|
|
|
- <para>With the basic configuration provided above, none of the JAR
|
|
|
- files listed (or <literal>acegi-security-XX.jar</literal>) should be
|
|
|
- in your application's <literal>WEB-INF/lib</literal>. The realm name
|
|
|
- indicated in your <literal>web.xml</literal> does not matter with
|
|
|
- Resin, as the relevant authentication class is indicated by the
|
|
|
- <literal><authenticator></literal> setting</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="ca-tomcat">
|
|
|
- <title>Tomcat</title>
|
|
|
-
|
|
|
- <para>The following was tested with Jakarta Tomcat 4.1.30 and
|
|
|
- 5.0.19.</para>
|
|
|
-
|
|
|
- <para><literal>$CATALINA_HOME</literal> refers to the root of your
|
|
|
- Catalina (Tomcat) installation.</para>
|
|
|
-
|
|
|
- <para>Edit your <literal>$CATALINA_HOME/conf/server.xml</literal> file
|
|
|
- so the <literal><Engine></literal> section contains only one
|
|
|
- active <literal><Realm></literal> entry. An example realm
|
|
|
- entry:</para>
|
|
|
-
|
|
|
- <para><programlisting> <Realm className="org.acegisecurity.adapters.catalina.CatalinaAcegiUserRealm"
|
|
|
- appContextLocation="conf/acegisecurity.xml"
|
|
|
- key="my_password" /></programlisting></para>
|
|
|
-
|
|
|
- <para>Be sure to remove any other <literal><Realm></literal>
|
|
|
- entry from your <literal><Engine></literal> section.</para>
|
|
|
-
|
|
|
- <para>Copy <literal>acegisecurity.xml</literal> into
|
|
|
- <literal>$CATALINA_HOME/conf</literal>.</para>
|
|
|
-
|
|
|
- <para>Copy <literal>acegi-security-catalina-XX.jar</literal> into
|
|
|
- <literal>$CATALINA_HOME/server/lib</literal>.</para>
|
|
|
-
|
|
|
- <para>Copy the following files into
|
|
|
- <literal>$CATALINA_HOME/common/lib</literal>:</para>
|
|
|
-
|
|
|
- <itemizedlist>
|
|
|
- <listitem>
|
|
|
- <para><literal>aopalliance.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>spring.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>commons-codec.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>burlap.jar</literal></para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>hessian.jar</literal></para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist>
|
|
|
-
|
|
|
- <para>None of the above JAR files (or
|
|
|
- <literal>acegi-security-XX.jar</literal>) should be in your
|
|
|
- application's <literal>WEB-INF/lib</literal>. The realm name indicated
|
|
|
- in your <literal>web.xml</literal> does not matter with
|
|
|
- Catalina.</para>
|
|
|
-
|
|
|
- <para>We have received reports of problems using this Container
|
|
|
- Adapter with Mac OS X. A work-around is to use a script such as
|
|
|
- follows:</para>
|
|
|
-
|
|
|
- <para><programlisting>#!/bin/sh
|
|
|
-export CATALINA_HOME="/Library/Tomcat"
|
|
|
-export JAVA_HOME="/Library/Java/Home"
|
|
|
-cd /
|
|
|
-$CATALINA_HOME/bin/startup.sh</programlisting></para>
|
|
|
-
|
|
|
- <para>Finally, restart Tomcat.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
- </part>
|
|
|
-
|
|
|
- <part id="authorization">
|
|
|
- <title>Authorization</title>
|
|
|
-
|
|
|
- <partintro>
|
|
|
- <para>The advanced authorization capabilities within Acegi Security
|
|
|
- represent one of the most compelling reasons for its popularity.
|
|
|
- Irrespective of how you choose to authenticate - whether using an Acegi
|
|
|
- Security-provided mechanism and provider, or integrating with a
|
|
|
- container or other non-Acegi Security authentication authority - you
|
|
|
- will find the authorization services can be used within your application
|
|
|
- in a consistent and simple way.</para>
|
|
|
-
|
|
|
- <para>In this part we'll explore the different
|
|
|
- <literal>AbstractSecurityInterceptor</literal> implementations, which
|
|
|
- were introduced in Part I. We then move on to explore how to fine-tune
|
|
|
- authorization through use of domain access control lists.</para>
|
|
|
- </partintro>
|
|
|
-
|
|
|
- <chapter id="authorization-common">
|
|
|
- <title>Common Authorization Concepts</title>
|
|
|
-
|
|
|
- <sect1 id="authorities">
|
|
|
- <title>Authorities</title>
|
|
|
-
|
|
|
- <para>As briefly mentioned in the Authentication section, all
|
|
|
- <literal>Authentication</literal> implementations are required to
|
|
|
- store an array of <literal>GrantedAuthority</literal> objects. These
|
|
|
- represent the authorities that have been granted to the principal. The
|
|
|
- <literal>GrantedAuthority</literal> objects are inserted into the
|
|
|
- <literal>Authentication</literal> object by the
|
|
|
- <literal>AuthenticationManager</literal> and are later read by
|
|
|
- <literal>AccessDecisionManager</literal>s when making authorization
|
|
|
- decisions.</para>
|
|
|
-
|
|
|
- <para><literal>GrantedAuthority</literal> is an interface with only
|
|
|
- one method:</para>
|
|
|
-
|
|
|
- <para><programlisting>public String getAuthority();</programlisting></para>
|
|
|
-
|
|
|
- <para>This method allows <literal>AccessDecisionManager</literal>s to
|
|
|
- obtain a precise <literal>String</literal> representation of the
|
|
|
- <literal>GrantedAuthority</literal>. By returning a representation as
|
|
|
- a <literal>String</literal>, a <literal>GrantedAuthority</literal> can
|
|
|
- be easily "read" by most <literal>AccessDecisionManager</literal>s. If
|
|
|
- a <literal>GrantedAuthority</literal> cannot be precisely represented
|
|
|
- as a <literal>String</literal>, the
|
|
|
- <literal>GrantedAuthority</literal> is considered "complex" and
|
|
|
- <literal>getAuthority()</literal> must return
|
|
|
- <literal>null</literal>.</para>
|
|
|
-
|
|
|
- <para>An example of a "complex" <literal>GrantedAuthority</literal>
|
|
|
- would be an implementation that stores a list of operations and
|
|
|
- authority thresholds that apply to different customer account numbers.
|
|
|
- Representing this complex <literal>GrantedAuthority</literal> as a
|
|
|
- <literal>String</literal> would be quite complex, and as a result the
|
|
|
- <literal>getAuthority()</literal> method should return
|
|
|
- <literal>null</literal>. This will indicate to any
|
|
|
- <literal>AccessDecisionManager</literal> that it will need to
|
|
|
- specifically support the <literal>GrantedAuthority</literal>
|
|
|
- implementation in order to understand its contents.</para>
|
|
|
-
|
|
|
- <para>Acegi Security includes one concrete
|
|
|
- <literal>GrantedAuthority</literal> implementation,
|
|
|
- <literal>GrantedAuthorityImpl</literal>. This allows any
|
|
|
- user-specified <literal>String</literal> to be converted into a
|
|
|
- <literal>GrantedAuthority</literal>. All
|
|
|
- <literal>AuthenticationProvider</literal>s included with the security
|
|
|
- architecture use <literal>GrantedAuthorityImpl</literal> to populate
|
|
|
- the <literal>Authentication</literal> object.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="pre-invocation">
|
|
|
- <title>Pre-Invocation Handling</title>
|
|
|
-
|
|
|
- <para>The <literal>AccessDecisionManager</literal> is called by the
|
|
|
- <literal>AbstractSecurityInterceptor</literal> and is responsible for
|
|
|
- making final access control decisions. The
|
|
|
- <literal>AccessDecisionManager</literal> interface contains three
|
|
|
- methods:</para>
|
|
|
-
|
|
|
- <para><programlisting>public void decide(Authentication authentication, Object object, ConfigAttributeDefinition config) throws AccessDeniedException;
|
|
|
-public boolean supports(ConfigAttribute attribute);
|
|
|
-public boolean supports(Class clazz);</programlisting></para>
|
|
|
-
|
|
|
- <para>As can be seen from the first method, the
|
|
|
- <literal>AccessDecisionManager</literal> is passed via method
|
|
|
- parameters all information that is likely to be of value in assessing
|
|
|
- an authorization decision. In particular, passing the secure
|
|
|
- <literal>Object</literal> enables those arguments contained in the
|
|
|
- actual secure object invocation to be inspected. For example, let's
|
|
|
- assume the secure object was a <literal>MethodInvocation</literal>. It
|
|
|
- would be easy to query the <literal>MethodInvocation</literal> for any
|
|
|
- <literal>Customer</literal> argument, and then implement some sort of
|
|
|
- security logic in the <literal>AccessDecisionManager</literal> to
|
|
|
- ensure the principal is permitted to operate on that customer.
|
|
|
- Implementations are expected to throw an
|
|
|
- <literal>AccessDeniedException</literal> if access is denied.</para>
|
|
|
-
|
|
|
- <para>The <literal>supports(ConfigAttribute)</literal> method is
|
|
|
- called by the <literal>AbstractSecurityInterceptor</literal> at
|
|
|
- startup time to determine if the
|
|
|
- <literal>AccessDecisionManager</literal> can process the passed
|
|
|
- <literal>ConfigAttribute</literal>. The
|
|
|
- <literal>supports(Class)</literal> method is called by a security
|
|
|
- interceptor implementation to ensure the configured
|
|
|
- <literal>AccessDecisionManager</literal> supports the type of secure
|
|
|
- object that the security interceptor will present.</para>
|
|
|
-
|
|
|
- <para>Whilst users can implement their own
|
|
|
- <literal>AccessDecisionManager</literal> to control all aspects of
|
|
|
- authorization, Acegi Security includes several
|
|
|
- <literal>AccessDecisionManager</literal> implementations that are
|
|
|
- based on voting. Figure 4 illustrates the relevant classes.</para>
|
|
|
-
|
|
|
- <para><mediaobject>
|
|
|
- <imageobject role="html">
|
|
|
- <imagedata align="center"
|
|
|
- fileref="images/AccessDecisionVoting.gif"
|
|
|
- format="GIF" />
|
|
|
- </imageobject>
|
|
|
-
|
|
|
- <caption>
|
|
|
- <para>Figure 4: Voting Decision Manager</para>
|
|
|
- </caption>
|
|
|
- </mediaobject></para>
|
|
|
-
|
|
|
- <para>Using this approach, a series of
|
|
|
- <literal>AccessDecisionVoter</literal> implementations are polled on
|
|
|
- an authorization decision. The
|
|
|
- <literal>AccessDecisionManager</literal> then decides whether or not
|
|
|
- to throw an <literal>AccessDeniedException</literal> based on its
|
|
|
- assessment of the votes.</para>
|
|
|
-
|
|
|
- <para>The <literal>AccessDecisionVoter</literal> interface has three
|
|
|
- methods:</para>
|
|
|
-
|
|
|
- <para><programlisting>public int vote(Authentication authentication, Object object, ConfigAttributeDefinition config);
|
|
|
-public boolean supports(ConfigAttribute attribute);
|
|
|
-public boolean supports(Class clazz);</programlisting></para>
|
|
|
-
|
|
|
- <para>Concrete implementations return an <literal>int</literal>, with
|
|
|
- possible values being reflected in the
|
|
|
- <literal>AccessDecisionVoter</literal> static fields
|
|
|
- <literal>ACCESS_ABSTAIN</literal>, <literal>ACCESS_DENIED</literal>
|
|
|
- and <literal>ACCESS_GRANTED</literal>. A voting implementation will
|
|
|
- return <literal>ACCESS_ABSTAIN</literal> if it has no opinion on an
|
|
|
- authorization decision. If it does have an opinion, it must return
|
|
|
- either <literal>ACCESS_DENIED</literal> or
|
|
|
- <literal>ACCESS_GRANTED</literal>.</para>
|
|
|
-
|
|
|
- <para>There are three concrete
|
|
|
- <literal>AccessDecisionManager</literal>s provided with Acegi Security
|
|
|
- that tally the votes. The <literal>ConsensusBased</literal>
|
|
|
- implementation will grant or deny access based on the consensus of
|
|
|
- non-abstain votes. Properties are provided to control behavior in the
|
|
|
- event of an equality of votes or if all votes are abstain. The
|
|
|
- <literal>AffirmativeBased</literal> implementation will grant access
|
|
|
- if one or more <literal>ACCESS_GRANTED</literal> votes were received
|
|
|
- (ie a deny vote will be ignored, provided there was at least one grant
|
|
|
- vote). Like the <literal>ConsensusBased</literal> implementation,
|
|
|
- there is a parameter that controls the behavior if all voters abstain.
|
|
|
- The <literal>UnanimousBased</literal> provider expects unanimous
|
|
|
- <literal>ACCESS_GRANTED</literal> votes in order to grant access,
|
|
|
- ignoring abstains. It will deny access if there is any
|
|
|
- <literal>ACCESS_DENIED</literal> vote. Like the other implementations,
|
|
|
- there is a parameter that controls the behaviour if all voters
|
|
|
- abstain.</para>
|
|
|
-
|
|
|
- <para>It is possible to implement a custom
|
|
|
- <literal>AccessDecisionManager</literal> that tallies votes
|
|
|
- differently. For example, votes from a particular
|
|
|
- <literal>AccessDecisionVoter</literal> might receive additional
|
|
|
- weighting, whilst a deny vote from a particular voter may have a veto
|
|
|
- effect.</para>
|
|
|
-
|
|
|
- <para>There are two concrete <literal>AccessDecisionVoter</literal>
|
|
|
- implementations provided with Acegi Security. The
|
|
|
- <literal>RoleVoter</literal> class will vote if any ConfigAttribute
|
|
|
- begins with <literal>ROLE_</literal>. It will vote to grant access if
|
|
|
- there is a <literal>GrantedAuthority</literal> which returns a
|
|
|
- <literal>String</literal> representation (via the
|
|
|
- <literal>getAuthority()</literal> method) exactly equal to one or more
|
|
|
- <literal>ConfigAttributes</literal> starting with
|
|
|
- <literal>ROLE_</literal>. If there is no exact match of any
|
|
|
- <literal>ConfigAttribute</literal> starting with
|
|
|
- <literal>ROLE_</literal>, the <literal>RoleVoter</literal> will vote
|
|
|
- to deny access. If no <literal>ConfigAttribute</literal> begins with
|
|
|
- <literal>ROLE_</literal>, the voter will abstain.
|
|
|
- <literal>RoleVoter</literal> is case sensitive on comparisons as well
|
|
|
- as the <literal>ROLE_</literal> prefix.</para>
|
|
|
-
|
|
|
- <para><literal>BasicAclEntryVoter</literal> is the other concrete
|
|
|
- voter included with Acegi Security. It integrates with Acegi
|
|
|
- Security's <literal>AclManager</literal> (discussed later). This voter
|
|
|
- is designed to have multiple instances in the same application
|
|
|
- context, such as:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="aclContactReadVoter" class="org.acegisecurity.vote.BasicAclEntryVoter">
|
|
|
- <property name="processConfigAttribute"><value>ACL_CONTACT_READ</value></property>
|
|
|
- <property name="processDomainObjectClass"><value>sample.contact.Contact</value></property>
|
|
|
- <property name="aclManager"><ref local="aclManager"/></property>
|
|
|
- <property name="requirePermission">
|
|
|
- <list>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.READ"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="aclContactDeleteVoter" class="org.acegisecurity.vote.BasicAclEntryVoter">
|
|
|
- <property name="processConfigAttribute"><value>ACL_CONTACT_DELETE</value></property>
|
|
|
- <property name="processDomainObjectClass"><value>sample.contact.Contact</value></property>
|
|
|
- <property name="aclManager"><ref local="aclManager"/></property>
|
|
|
- <property name="requirePermission">
|
|
|
- <list>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.DELETE"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>In the above example, you'd define
|
|
|
- <literal>ACL_CONTACT_READ</literal> or
|
|
|
- <literal>ACL_CONTACT_DELETE</literal> against some methods on a
|
|
|
- <literal>MethodSecurityInterceptor</literal> or
|
|
|
- <literal>AspectJSecurityInterceptor</literal>. When those methods are
|
|
|
- invoked, the above applicable voter defined above would vote to grant
|
|
|
- or deny access. The voter would look at the method invocation to
|
|
|
- locate the first argument of type
|
|
|
- <literal>sample.contact.Contact</literal>, and then pass that
|
|
|
- <literal>Contact</literal> to the <literal>AclManager</literal>. The
|
|
|
- <literal>AclManager</literal> will then return an access control list
|
|
|
- (ACL) that applies to the current <literal>Authentication</literal>.
|
|
|
- Assuming that ACL contains one of the listed
|
|
|
- <literal>requirePermission</literal>s, the voter will vote to grant
|
|
|
- access. If the ACL does not contain one of the permissions defined
|
|
|
- against the voter, the voter will vote to deny access.
|
|
|
- <literal>BasicAclEntryVoter</literal> is an important class as it
|
|
|
- allows you to build truly complex applications with domain object
|
|
|
- security entirely defined in the application context. If you're
|
|
|
- interested in learning more about Acegi Security's ACL capabilities
|
|
|
- and how best to apply them, please see the ACL and "After Invocation"
|
|
|
- sections of this reference guide, and the Contacts sample
|
|
|
- application.</para>
|
|
|
-
|
|
|
- <para>It is also possible to implement a custom
|
|
|
- <literal>AccessDecisionVoter</literal>. Several examples are provided
|
|
|
- in Acegi Security unit tests, including
|
|
|
- <literal>ContactSecurityVoter</literal> and
|
|
|
- <literal>DenyVoter</literal>. The
|
|
|
- <literal>ContactSecurityVoter</literal> abstains from voting decisions
|
|
|
- where a <literal>CONTACT_OWNED_BY_CURRENT_USER</literal>
|
|
|
- <literal>ConfigAttribute</literal> is not found. If voting, it queries
|
|
|
- the <literal>MethodInvocation</literal> to extract the owner of the
|
|
|
- <literal>Contact</literal> object that is subject of the method call.
|
|
|
- It votes to grant access if the <literal>Contact</literal> owner
|
|
|
- matches the principal presented in the
|
|
|
- <literal>Authentication</literal> object. It could have just as easily
|
|
|
- compared the <literal>Contact</literal> owner with some
|
|
|
- <literal>GrantedAuthority</literal> the
|
|
|
- <literal>Authentication</literal> object presented. All of this is
|
|
|
- achieved with relatively few lines of code and demonstrates the
|
|
|
- flexibility of the authorization model.</para>
|
|
|
-
|
|
|
- <para>TODO: Remove references to the old ACL package when it's
|
|
|
- deprecated, and have all references to the replacement package limited
|
|
|
- to the chapter describing the new ACL implementation.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="after-invocation">
|
|
|
- <title>After Invocation Handling</title>
|
|
|
-
|
|
|
- <para>Whilst the <literal>AccessDecisionManager</literal> is called by
|
|
|
- the <literal>AbstractSecurityInterceptor</literal> before proceeding
|
|
|
- with the secure object invocation, some applications need a way of
|
|
|
- modifying the object actually returned by the secure object
|
|
|
- invocation. Whilst you could easily implement your own AOP concern to
|
|
|
- achieve this, Acegi Security provides a convenient hook that has
|
|
|
- several concrete implementations that integrate with its ACL
|
|
|
- capabilities.</para>
|
|
|
-
|
|
|
- <para>Figure 5 illustrates Acegi Security's
|
|
|
- <literal>AfterInvocationManager</literal> and its concrete
|
|
|
- implementations.</para>
|
|
|
-
|
|
|
- <para><mediaobject>
|
|
|
- <imageobject role="html">
|
|
|
- <imagedata align="center" fileref="images/AfterInvocation.gif"
|
|
|
- format="GIF" />
|
|
|
- </imageobject>
|
|
|
-
|
|
|
- <caption>
|
|
|
- <para>Figure 5: After Invocation Implementation</para>
|
|
|
- </caption>
|
|
|
- </mediaobject></para>
|
|
|
-
|
|
|
- <para>Like many other parts of Acegi Security,
|
|
|
- <literal>AfterInvocationManager</literal> has a single concrete
|
|
|
- implementation, <literal>AfterInvocationProvider</literal>, which
|
|
|
- polls a list of <literal>AfterInvocationProvider</literal>s. Each
|
|
|
- <literal>AfterInvocationProvider</literal> is allowed to modify the
|
|
|
- return object or throw an <literal>AccessDeniedException</literal>.
|
|
|
- Indeed multiple providers can modify the object, as the result of the
|
|
|
- previous provider is passed to the next in the list. Let's now
|
|
|
- consider our ACL-aware implementations of
|
|
|
- <literal>AfterInvocationProvider</literal>.</para>
|
|
|
-
|
|
|
- <para>Please be aware that if you're using
|
|
|
- <literal>AfterInvocationManager</literal>, you will still need
|
|
|
- configuration attributes that allow the
|
|
|
- <literal>MethodSecurityInterceptor</literal>'s
|
|
|
- <literal>AccessDecisionManager</literal> to allow an operation. If
|
|
|
- you're using the typical Acegi Security included
|
|
|
- <literal>AccessDecisionManager</literal> implementations, having no
|
|
|
- configuration attributes defined for a particular secure method
|
|
|
- invocation will cause each <literal>AccessDecisionVoter</literal> to
|
|
|
- abstain from voting. In turn, if the
|
|
|
- <literal>AccessDecisionManager</literal> property
|
|
|
- "<literal>allowIfAllAbstainDecisions</literal>" is
|
|
|
- <literal>false</literal>, an <literal>AccessDeniedException</literal>
|
|
|
- will be thrown. You may avoid this potential issue by either (i)
|
|
|
- setting "<literal>allowIfAllAbstainDecisions</literal>" to
|
|
|
- <literal>true</literal> (although this is generally not recommended)
|
|
|
- or (ii) simply ensure that there is at least one configuration
|
|
|
- attribute that an <literal>AccessDecisionVoter</literal> will vote to
|
|
|
- grant access for. This latter (recommended) approach is usually
|
|
|
- achieved through a <literal>ROLE_USER</literal> or
|
|
|
- <literal>ROLE_AUTHENTICATED</literal> configuration attribute</para>
|
|
|
-
|
|
|
- <sect2 id="after-invocation-acl-aware">
|
|
|
- <title>ACL-Aware AfterInvocationProviders</title>
|
|
|
-
|
|
|
- <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
|
|
|
- ACL module. The new ACL module is a significant rewrite of the
|
|
|
- existing ACL module. The new module can be found under the
|
|
|
- <literal>org.acegisecurity.acls</literal> package, with the old ACL
|
|
|
- module under <literal>org.acegisecurity.acl</literal>. We encourage
|
|
|
- users to consider testing with the new ACL module and build
|
|
|
- applications with it. The old ACL module should be considered
|
|
|
- deprecated and may be removed from a future release. The following
|
|
|
- information relates to the new ACL package, and is thus
|
|
|
- recommended.</para>
|
|
|
-
|
|
|
- <para>A common services layer method we've all written at one stage
|
|
|
- or another looks like this:</para>
|
|
|
-
|
|
|
- <para><programlisting>public Contact getById(Integer id);</programlisting></para>
|
|
|
-
|
|
|
- <para>Quite often, only principals with permission to read the
|
|
|
- <literal>Contact</literal> should be allowed to obtain it. In this
|
|
|
- situation the <literal>AccessDecisionManager</literal> approach
|
|
|
- provided by the <literal>AbstractSecurityInterceptor</literal> will
|
|
|
- not suffice. This is because the identity of the
|
|
|
- <literal>Contact</literal> is all that is available before the
|
|
|
- secure object is invoked. The
|
|
|
- <literal>AclAfterInvocationProvider</literal> delivers a solution,
|
|
|
- and is configured as follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="afterAclRead" class="org.acegisecurity.afterinvocation.AclEntryAfterInvocationProvider">
|
|
|
- <constructor-arg>
|
|
|
- <ref bean="aclService"/>
|
|
|
- </constructor-arg>
|
|
|
- <constructor-arg>
|
|
|
- <list>
|
|
|
- <ref local="org.acegisecurity.acls.domain.BasePermission.ADMINISTRATION"/>
|
|
|
- <ref local="org.acegisecurity.acls.domain.BasePermission.READ"/>
|
|
|
- </list>
|
|
|
- </constructor-arg>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>In the above example, the <literal>Contact</literal> will be
|
|
|
- retrieved and passed to the
|
|
|
- <literal>AclEntryAfterInvocationProvider</literal>. The provider
|
|
|
- will thrown an <literal>AccessDeniedException</literal> if one of
|
|
|
- the listed <literal>requirePermission</literal>s is not held by the
|
|
|
- <literal>Authentication</literal>. The
|
|
|
- <literal>AclEntryAfterInvocationProvider</literal> queries the
|
|
|
- <literal>Acl</literal>Service to determine the ACL that applies for
|
|
|
- this domain object to this <literal>Authentication</literal>.</para>
|
|
|
-
|
|
|
- <para>Similar to the
|
|
|
- <literal>AclEntryAfterInvocationProvider</literal> is
|
|
|
- <literal>AclEntryAfterInvocationCollectionFilteringProvider</literal>.
|
|
|
- It is designed to remove <literal>Collection</literal> or array
|
|
|
- elements for which a principal does not have access. It never thrown
|
|
|
- an <literal>AccessDeniedException</literal> - simply silently
|
|
|
- removes the offending elements. The provider is configured as
|
|
|
- follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="afterAclCollectionRead" class="org.acegisecurity.afterinvocation.AclEntryAfterInvocationCollectionFilteringProvider">
|
|
|
- <constructor-arg>
|
|
|
- <ref bean="aclService"/>
|
|
|
- </constructor-arg>
|
|
|
- <constructor-arg>
|
|
|
- <list>
|
|
|
- <ref local="org.acegisecurity.acls.domain.BasePermission.ADMINISTRATION"/>
|
|
|
- <ref local="org.acegisecurity.acls.domain.BasePermission.READ"/>
|
|
|
- </list>
|
|
|
- </constructor-arg>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>As you can imagine, the returned <literal>Object</literal>
|
|
|
- must be a <literal>Collection</literal> or array for this provider
|
|
|
- to operate. It will remove any element if the
|
|
|
- <literal>AclManager</literal> indicates the
|
|
|
- <literal>Authentication</literal> does not hold one of the listed
|
|
|
- <literal>requirePermission</literal>s.</para>
|
|
|
-
|
|
|
- <para>The Contacts sample application demonstrates these two
|
|
|
- <literal>AfterInvocationProvider</literal>s.</para>
|
|
|
- </sect2>
|
|
|
-
|
|
|
- <sect2 id="after-invocation-acl-aware-old">
|
|
|
- <title>ACL-Aware AfterInvocationProviders (old ACL module)</title>
|
|
|
-
|
|
|
- <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
|
|
|
- ACL module. The new ACL module is a significant rewrite of the
|
|
|
- existing ACL module. The new module can be found under the
|
|
|
- <literal>org.acegisecurity.acls</literal> package, with the old ACL
|
|
|
- module under <literal>org.acegisecurity.acl</literal>. We encourage
|
|
|
- users to consider testing with the new ACL module and build
|
|
|
- applications with it. The old ACL module should be considered
|
|
|
- deprecated and may be removed from a future release.</para>
|
|
|
-
|
|
|
- <para>A common services layer method we've all written at one stage
|
|
|
- or another looks like this:</para>
|
|
|
-
|
|
|
- <para><programlisting>public Contact getById(Integer id);</programlisting></para>
|
|
|
-
|
|
|
- <para>Quite often, only principals with permission to read the
|
|
|
- <literal>Contact</literal> should be allowed to obtain it. In this
|
|
|
- situation the <literal>AccessDecisionManager</literal> approach
|
|
|
- provided by the <literal>AbstractSecurityInterceptor</literal> will
|
|
|
- not suffice. This is because the identity of the
|
|
|
- <literal>Contact</literal> is all that is available before the
|
|
|
- secure object is invoked. The
|
|
|
- <literal>BasicAclAfterInvocationProvider</literal> delivers a
|
|
|
- solution, and is configured as follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="afterAclRead" class="org.acegisecurity.afterinvocation.BasicAclEntryAfterInvocationProvider">
|
|
|
- <property name="aclManager"><ref local="aclManager"/></property>
|
|
|
- <property name="requirePermission">
|
|
|
- <list>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.READ"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>In the above example, the <literal>Contact</literal> will be
|
|
|
- retrieved and passed to the
|
|
|
- <literal>BasicAclEntryAfterInvocationProvider</literal>. The
|
|
|
- provider will thrown an <literal>AccessDeniedException</literal> if
|
|
|
- one of the listed <literal>requirePermission</literal>s is not held
|
|
|
- by the <literal>Authentication</literal>. The
|
|
|
- <literal>BasicAclEntryAfterInvocationProvider</literal> queries the
|
|
|
- <literal>AclManager</literal> to determine the ACL that applies for
|
|
|
- this domain object to this <literal>Authentication</literal>.</para>
|
|
|
-
|
|
|
- <para>Similar to the
|
|
|
- <literal>BasicAclEntryAfterInvocationProvider</literal> is
|
|
|
- <literal>BasicAclEntryAfterInvocationCollectionFilteringProvider</literal>.
|
|
|
- It is designed to remove <literal>Collection</literal> or array
|
|
|
- elements for which a principal does not have access. It never thrown
|
|
|
- an <literal>AccessDeniedException</literal> - simply silently
|
|
|
- removes the offending elements. The provider is configured as
|
|
|
- follows:</para>
|
|
|
-
|
|
|
- <para><programlisting><bean id="afterAclCollectionRead" class="org.acegisecurity.afterinvocation.BasicAclEntryAfterInvocationCollectionFilteringProvider">
|
|
|
- <property name="aclManager"><ref local="aclManager"/></property>
|
|
|
- <property name="requirePermission">
|
|
|
- <list>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.ADMINISTRATION"/>
|
|
|
- <ref local="org.acegisecurity.acl.basic.SimpleAclEntry.READ"/>
|
|
|
- </list>
|
|
|
- </property>
|
|
|
-</bean> </programlisting></para>
|
|
|
-
|
|
|
- <para>As you can imagine, the returned <literal>Object</literal>
|
|
|
- must be a <literal>Collection</literal> or array for this provider
|
|
|
- to operate. It will remove any element if the
|
|
|
- <literal>AclManager</literal> indicates the
|
|
|
- <literal>Authentication</literal> does not hold one of the listed
|
|
|
- <literal>requirePermission</literal>s.</para>
|
|
|
-
|
|
|
- <para>The Contacts sample application demonstrates these two
|
|
|
- <literal>AfterInvocationProvider</literal>s.</para>
|
|
|
- </sect2>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="authorization-taglibs">
|
|
|
- <title>Authorization Tag Libraries</title>
|
|
|
-
|
|
|
- <para><literal>AuthorizeTag</literal> is used to include content if
|
|
|
- the current principal holds certain
|
|
|
- <literal>GrantedAuthority</literal>s.</para>
|
|
|
-
|
|
|
- <para>The following JSP fragment illustrates how to use the
|
|
|
- <literal>AuthorizeTag</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting><authz:authorize ifAllGranted="ROLE_SUPERVISOR">
|
|
|
- <td>
|
|
|
- <A HREF="del.htm?id=<c:out value="${contact.id}"/>">Del</A>
|
|
|
- </td>
|
|
|
-</authz:authorize> </programlisting></para>
|
|
|
-
|
|
|
- <para>This tag would cause the tag's body to be output if the
|
|
|
- principal has been granted ROLE_SUPERVISOR.</para>
|
|
|
-
|
|
|
- <para>The <literal>authz:authorize</literal> tag declares the
|
|
|
- following attributes:</para>
|
|
|
-
|
|
|
- <para><itemizedlist spacing="compact">
|
|
|
- <listitem>
|
|
|
- <para><literal>ifAllGranted</literal>: All the listed roles must
|
|
|
- be granted for the tag to output its body.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>ifAnyGranted</literal>: Any of the listed roles
|
|
|
- must be granted for the tag to output its body.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>ifNotGranted</literal>: None of the listed roles
|
|
|
- must be granted for the tag to output its body.</para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist></para>
|
|
|
-
|
|
|
- <para>You'll note that in each attribute you can list multiple roles.
|
|
|
- Simply separate the roles using a comma. The
|
|
|
- <literal>authorize</literal> tag ignores whitespace in
|
|
|
- attributes.</para>
|
|
|
-
|
|
|
- <para>The tag library logically ANDs all of it's parameters together.
|
|
|
- This means that if you combine two or more attributes, all attributes
|
|
|
- must be true for the tag to output it's body. Don't add an
|
|
|
- <literal>ifAllGranted="ROLE_SUPERVISOR"</literal>, followed by an
|
|
|
- <literal>ifNotGranted="ROLE_SUPERVISOR"</literal>, or you'll be
|
|
|
- surprised to never see the tag's body.</para>
|
|
|
-
|
|
|
- <para>By requiring all attributes to return true, the authorize tag
|
|
|
- allows you to create more complex authorization scenarios. For
|
|
|
- example, you could declare an
|
|
|
- <literal>ifAllGranted="ROLE_SUPERVISOR"</literal> and an
|
|
|
- <literal>ifNotGranted="ROLE_NEWBIE_SUPERVISOR"</literal> in the same
|
|
|
- tag, in order to prevent new supervisors from seeing the tag body.
|
|
|
- However it would no doubt be simpler to use
|
|
|
- <literal>ifAllGranted="ROLE_EXPERIENCED_SUPERVISOR"</literal> rather
|
|
|
- than inserting NOT conditions into your design.</para>
|
|
|
-
|
|
|
- <para>One last item: the tag verifies the authorizations in a specific
|
|
|
- order: first <literal>ifNotGranted</literal>, then
|
|
|
- <literal>ifAllGranted</literal>, and finally, <literal>if
|
|
|
- AnyGranted</literal>.</para>
|
|
|
-
|
|
|
- <para><literal>AccessControlListTag</literal> is used to include
|
|
|
- content if the current principal has an ACL to the indicated domain
|
|
|
- object.</para>
|
|
|
-
|
|
|
- <para>The following JSP fragment illustrates how to use the
|
|
|
- <literal>AccessControlListTag</literal>:</para>
|
|
|
-
|
|
|
- <para><programlisting><authz:accesscontrollist domainObject="${contact}" hasPermission="8,16">
|
|
|
- <td><A HREF="<c:url value="del.htm"><c:param name="contactId" value="${contact.id}"/></c:url>">Del</A></td>
|
|
|
-</authz:accesscontrollist></programlisting></para>
|
|
|
-
|
|
|
- <para>This tag would cause the tag's body to be output if the
|
|
|
- principal holds either permission 16 or permission 1 for the "contact"
|
|
|
- domain object. The numbers are actually integers that are used with
|
|
|
- <literal>BasePermission</literal> bit masking. Please refer to the ACL
|
|
|
- section of this reference guide to understand more about the ACL
|
|
|
- capabilities of Acegi Security.</para>
|
|
|
-
|
|
|
- <para><literal>AclTag</literal> is part of the old ACL module and
|
|
|
- should be considered deprecated. For the sake of historical reference,
|
|
|
- works exactly the samae as
|
|
|
- <literal>AccessControlListTag</literal>.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="secure-object-impls">
|
|
|
- <title>Secure Object Implementations</title>
|
|
|
-
|
|
|
- <sect1 id="aop-alliance">
|
|
|
- <title>AOP Alliance (MethodInvocation) Security Interceptor</title>
|
|
|
-
|
|
|
- <para>To secure <literal>MethodInvocation</literal>s, developers
|
|
|
- simply add a properly configured
|
|
|
- <literal>MethodSecurityInterceptor</literal> into the application
|
|
|
- context. Next the beans requiring security are chained into the
|
|
|
- interceptor. This chaining is accomplished using Spring’s
|
|
|
- <literal>ProxyFactoryBean</literal> or
|
|
|
- <literal>BeanNameAutoProxyCreator</literal>, as commonly used by many
|
|
|
- other parts of Spring (refer to the sample application for examples).
|
|
|
- Alternatively, Acegi Security provides a
|
|
|
- <literal>MethodDefinitionSourceAdvisor</literal> which may be used
|
|
|
- with Spring's <literal>DefaultAdvisorAutoProxyCreator</literal> to
|
|
|
- automatically chain the security interceptor in front of any beans
|
|
|
- defined against the <literal>MethodSecurityInterceptor</literal>. The
|
|
|
- <literal>MethodSecurityInterceptor</literal> itself is configured as
|
|
|
- follows:</para>
|
|
|
-
|
|
|
- <programlisting><bean id="bankManagerSecurity" class="org.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor">
|
|
|
- <property name="validateConfigAttributes"><value>true</value></property>
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
|
|
|
- <property name="runAsManager"><ref bean="runAsManager"/></property>
|
|
|
- <property name="afterInvocationManager"><ref bean="afterInvocationManager"/></property>
|
|
|
- <property name="objectDefinitionSource">
|
|
|
- <value>
|
|
|
- org.acegisecurity.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
|
|
|
- org.acegisecurity.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean> </programlisting>
|
|
|
-
|
|
|
- <para>As shown above, the <literal>MethodSecurityInterceptor</literal>
|
|
|
- is configured with a reference to an
|
|
|
- <literal>AuthenticationManager</literal>,
|
|
|
- <literal>AccessDecisionManager</literal> and
|
|
|
- <literal>RunAsManager</literal>, which are each discussed in separate
|
|
|
- sections below. In this case we've also defined an
|
|
|
- <literal>AfterInvocationManager</literal>, although this is entirely
|
|
|
- optional. The <literal>MethodSecurityInterceptor</literal> is also
|
|
|
- configured with configuration attributes that apply to different
|
|
|
- method signatures. A full discussion of configuration attributes is
|
|
|
- provided in the High Level Design section of this document.</para>
|
|
|
-
|
|
|
- <para>The <literal>MethodSecurityInterceptor</literal> can be
|
|
|
- configured with configuration attributes in three ways. The first is
|
|
|
- via a property editor and the application context, which is shown
|
|
|
- above. The second is via defining the configuration attributes in your
|
|
|
- source code using Jakarta Commons Attributes or Java 5 Annotations.
|
|
|
- The third is via writing your own
|
|
|
- <literal>ObjectDefinitionSource</literal>, although this is beyond the
|
|
|
- scope of this document. Irrespective of the approach used, the
|
|
|
- <literal>ObjectDefinitionSource</literal> is responsible for returning
|
|
|
- a <literal>ConfigAttributeDefinition</literal> object that contains
|
|
|
- all of the configuration attributes associated with a single secure
|
|
|
- method.</para>
|
|
|
-
|
|
|
- <para>It should be noted that the
|
|
|
- <literal>MethodSecurityInterceptor.setObjectDefinitionSource()</literal>
|
|
|
- method actually expects an instance of
|
|
|
- <literal>MethodDefinitionSource</literal>. This is a marker interface
|
|
|
- which subclasses <literal>ObjectDefinitionSource</literal>. It simply
|
|
|
- denotes the <literal>ObjectDefinitionSource</literal> understands
|
|
|
- <literal>MethodInvocation</literal>s. In the interests of simplicity
|
|
|
- we'll continue to refer to the
|
|
|
- <literal>MethodDefinitionSource</literal> as an
|
|
|
- <literal>ObjectDefinitionSource</literal>, as the distinction is of
|
|
|
- little relevance to most users of the
|
|
|
- <literal>MethodSecurityInterceptor</literal>.</para>
|
|
|
-
|
|
|
- <para>If using the application context property editor approach (as
|
|
|
- shown above), commas are used to delimit the different configuration
|
|
|
- attributes that apply to a given method pattern. Each configuration
|
|
|
- attribute is assigned into its own <literal>SecurityConfig</literal>
|
|
|
- object. The <literal>SecurityConfig</literal> object is discussed in
|
|
|
- the High Level Design section.</para>
|
|
|
-
|
|
|
- <para>If you are using the Jakarta Commons Attributes approach, your
|
|
|
- bean context will be configured differently:</para>
|
|
|
-
|
|
|
- <programlisting><bean id="attributes" class="org.springframework.metadata.commons.CommonsAttributes"/>
|
|
|
-<bean id="objectDefinitionSource" class="org.acegisecurity.intercept.method.MethodDefinitionAttributes">
|
|
|
- <property name="attributes"><ref local="attributes"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="bankManagerSecurity" class="org.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor">
|
|
|
- <property name="validateConfigAttributes"><value>false</value></property>
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
|
|
|
- <property name="runAsManager"><ref bean="runAsManager"/></property>
|
|
|
- <property name="objectDefinitionSource"><ref bean="objectDefinitionSource"/></property>
|
|
|
-</bean> </programlisting>
|
|
|
-
|
|
|
- <para>In addition, your source code will contain Jakarta Commons
|
|
|
- Attributes tags that refer to a concrete implementation of
|
|
|
- <literal>ConfigAttribute</literal>. The following example uses the
|
|
|
- <literal>SecurityConfig</literal> implementation to represent the
|
|
|
- configuration attributes, and results in the same security
|
|
|
- configuration as provided by the property editor approach
|
|
|
- above:</para>
|
|
|
-
|
|
|
- <programlisting>public interface BankManager {
|
|
|
-
|
|
|
- /**
|
|
|
- * @@SecurityConfig("ROLE_SUPERVISOR")
|
|
|
- * @@SecurityConfig("RUN_AS_SERVER")
|
|
|
- */
|
|
|
- public void deleteSomething(int id);
|
|
|
-
|
|
|
- /**
|
|
|
- * @@SecurityConfig("ROLE_SUPERVISOR")
|
|
|
- * @@SecurityConfig("RUN_AS_SERVER")
|
|
|
- */
|
|
|
- public void deleteAnother(int id);
|
|
|
-
|
|
|
- /**
|
|
|
- * @@SecurityConfig("ROLE_TELLER")
|
|
|
- * @@SecurityConfig("ROLE_SUPERVISOR")
|
|
|
- * @@SecurityConfig("BANKSECURITY_CUSTOMER")
|
|
|
- * @@SecurityConfig("RUN_AS_SERVER")
|
|
|
- */
|
|
|
- public float getBalance(int id);
|
|
|
-}</programlisting>
|
|
|
-
|
|
|
- <para>If you are using the Acegi Security Java 5 Annotations approach,
|
|
|
- your bean context will be configured as follows:</para>
|
|
|
-
|
|
|
- <programlisting><bean id="attributes" class="org.acegisecurity.annotation.SecurityAnnotationAttributes"/>
|
|
|
-<bean id="objectDefinitionSource" class="org.acegisecurity.intercept.method.MethodDefinitionAttributes">
|
|
|
- <property name="attributes"><ref local="attributes"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="bankManagerSecurity" class="org.acegisecurity.intercept.method.aopalliance.MethodSecurityInterceptor">
|
|
|
- <property name="validateConfigAttributes"><value>false</value></property>
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
|
|
|
- <property name="runAsManager"><ref bean="runAsManager"/></property>
|
|
|
- <property name="objectDefinitionSource"><ref bean="objectDefinitionSource"/></property>
|
|
|
-</bean> </programlisting>
|
|
|
-
|
|
|
- <para>In addition, your source code will contain Acegi Java 5 Security
|
|
|
- Annotations that represent the <literal>ConfigAttribute</literal>. The
|
|
|
- following example uses the <literal>@Secured</literal> annotations to
|
|
|
- represent the configuration attributes, and results in the same
|
|
|
- security configuration as provided by the property editor
|
|
|
- approach:</para>
|
|
|
-
|
|
|
- <programlisting>import org.acegisecurity.annotation.Secured;
|
|
|
-
|
|
|
-public interface BankManager {
|
|
|
-
|
|
|
- /**
|
|
|
- * Delete something
|
|
|
- */
|
|
|
- @Secured({"ROLE_SUPERVISOR","RUN_AS_SERVER" })
|
|
|
- public void deleteSomething(int id);
|
|
|
-
|
|
|
- /**
|
|
|
- * Delete another
|
|
|
- */
|
|
|
- @Secured({"ROLE_SUPERVISOR","RUN_AS_SERVER" })
|
|
|
- public void deleteAnother(int id);
|
|
|
-
|
|
|
- /**
|
|
|
- * Get balance
|
|
|
- */
|
|
|
- @Secured({"ROLE_TELLER","ROLE_SUPERVISOR","BANKSECURITY_CUSTOMER","RUN_AS_SERVER" })
|
|
|
- public float getBalance(int id);
|
|
|
-}</programlisting>
|
|
|
-
|
|
|
- <para>You might have noticed the
|
|
|
- <literal>validateConfigAttributes</literal> property in the above
|
|
|
- <literal>MethodSecurityInterceptor</literal> examples. When set to
|
|
|
- <literal>true</literal> (the default), at startup time the
|
|
|
- <literal>MethodSecurityInterceptor</literal> will evaluate if the
|
|
|
- provided configuration attributes are valid. It does this by checking
|
|
|
- each configuration attribute can be processed by either the
|
|
|
- <literal>AccessDecisionManager</literal> or the
|
|
|
- <literal>RunAsManager</literal>. If neither of these can process a
|
|
|
- given configuration attribute, an exception is thrown. If using the
|
|
|
- Jakarta Commons Attributes method of configuration, you should set
|
|
|
- <literal>validateConfigAttributes</literal> to
|
|
|
- <literal>false</literal>.</para>
|
|
|
-
|
|
|
- <para>Please note that when using
|
|
|
- <literal>BeanNameAutoProxyCreator</literal> to create the required
|
|
|
- proxy for security, the configuration must contain the property
|
|
|
- <literal>proxyTargetClass</literal> set to <literal>true</literal>.
|
|
|
- Otherwise, the method passed to
|
|
|
- <literal>MethodSecurityInterceptor.invoke</literal> is the proxy's
|
|
|
- caller, not the proxy's target. Note that this introduces a
|
|
|
- requirement on CGLIB. See an example of using
|
|
|
- <literal>BeanNameAutoProxyCreator</literal> below:</para>
|
|
|
-
|
|
|
- <programlisting><bean id="autoProxyCreator" class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator">
|
|
|
- <property name="interceptorNames">
|
|
|
- <list><value>methodSecurityInterceptor</value></list>
|
|
|
- </property>
|
|
|
- <property name="beanNames">
|
|
|
- <list><value>targetObjectName</value></list>
|
|
|
- </property>
|
|
|
- <property name="proxyTargetClass" value="true"/>
|
|
|
-</bean> </programlisting>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="aspectj">
|
|
|
- <title>AspectJ (JoinPoint) Security Interceptor</title>
|
|
|
-
|
|
|
- <para>The AspectJ security interceptor is very similar to the AOP
|
|
|
- Alliance security interceptor discussed in the previous section.
|
|
|
- Indeed we will only discuss the differences in this section.</para>
|
|
|
-
|
|
|
- <para>The AspectJ interceptor is named
|
|
|
- <literal>AspectJSecurityInterceptor</literal>. Unlike the AOP Alliance
|
|
|
- security interceptor, which relies on the Spring application context
|
|
|
- to weave in the security interceptor via proxying, the
|
|
|
- <literal>AspectJSecurityInterceptor</literal> is weaved in via the
|
|
|
- AspectJ compiler. It would not be uncommon to use both types of
|
|
|
- security interceptors in the same application, with
|
|
|
- <literal>AspectJSecurityInterceptor</literal> being used for domain
|
|
|
- object instance security and the AOP Alliance
|
|
|
- <literal>MethodSecurityInterceptor</literal> being used for services
|
|
|
- layer security.</para>
|
|
|
-
|
|
|
- <para>Let's first consider how the
|
|
|
- <literal>AspectJSecurityInterceptor</literal> is configured in the
|
|
|
- Spring application context:</para>
|
|
|
-
|
|
|
- <programlisting><bean id="bankManagerSecurity" class="org.acegisecurity.intercept.method.aspectj.AspectJSecurityInterceptor">
|
|
|
- <property name="validateConfigAttributes"><value>true</value></property>
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
|
|
|
- <property name="runAsManager"><ref bean="runAsManager"/></property>
|
|
|
- <property name="afterInvocationManager"><ref bean="afterInvocationManager"/></property>
|
|
|
- <property name="objectDefinitionSource">
|
|
|
- <value>
|
|
|
- org.acegisecurity.context.BankManager.delete*=ROLE_SUPERVISOR,RUN_AS_SERVER
|
|
|
- org.acegisecurity.context.BankManager.getBalance=ROLE_TELLER,ROLE_SUPERVISOR,BANKSECURITY_CUSTOMER,RUN_AS_SERVER
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean> </programlisting>
|
|
|
-
|
|
|
- <para>As you can see, aside from the class name, the
|
|
|
- <literal>AspectJSecurityInterceptor</literal> is exactly the same as
|
|
|
- the AOP Alliance security interceptor. Indeed the two interceptors can
|
|
|
- share the same <literal>objectDefinitionSource</literal>, as the
|
|
|
- <literal>ObjectDefinitionSource</literal> works with
|
|
|
- <literal>java.lang.reflect.Method</literal>s rather than an AOP
|
|
|
- library-specific class. Of course, your access decisions have access
|
|
|
- to the relevant AOP library-specific invocation (ie
|
|
|
- <literal>MethodInvocation</literal> or <literal>JoinPoint</literal>)
|
|
|
- and as such can consider a range of addition criteria when making
|
|
|
- access decisions (such as method arguments).</para>
|
|
|
-
|
|
|
- <para>Next you'll need to define an AspectJ <literal>aspect</literal>.
|
|
|
- For example:</para>
|
|
|
-
|
|
|
- <programlisting>package org.acegisecurity.samples.aspectj;
|
|
|
-
|
|
|
-import org.acegisecurity.intercept.method.aspectj.AspectJSecurityInterceptor;
|
|
|
-import org.acegisecurity.intercept.method.aspectj.AspectJCallback;
|
|
|
-import org.springframework.beans.factory.InitializingBean;
|
|
|
-
|
|
|
-public aspect DomainObjectInstanceSecurityAspect implements InitializingBean {
|
|
|
-
|
|
|
- private AspectJSecurityInterceptor securityInterceptor;
|
|
|
-
|
|
|
- pointcut domainObjectInstanceExecution(): target(PersistableEntity)
|
|
|
- && execution(public * *(..)) && !within(DomainObjectInstanceSecurityAspect);
|
|
|
-
|
|
|
- Object around(): domainObjectInstanceExecution() {
|
|
|
- if (this.securityInterceptor != null) {
|
|
|
- AspectJCallback callback = new AspectJCallback() {
|
|
|
- public Object proceedWithObject() {
|
|
|
- return proceed();
|
|
|
- }
|
|
|
- };
|
|
|
- return this.securityInterceptor.invoke(thisJoinPoint, callback);
|
|
|
- } else {
|
|
|
- return proceed();
|
|
|
- }
|
|
|
- }
|
|
|
-
|
|
|
- public AspectJSecurityInterceptor getSecurityInterceptor() {
|
|
|
- return securityInterceptor;
|
|
|
- }
|
|
|
-
|
|
|
- public void setSecurityInterceptor(AspectJSecurityInterceptor securityInterceptor) {
|
|
|
- this.securityInterceptor = securityInterceptor;
|
|
|
- }
|
|
|
-
|
|
|
- public void afterPropertiesSet() throws Exception {
|
|
|
- if (this.securityInterceptor == null)
|
|
|
- throw new IllegalArgumentException("securityInterceptor required");
|
|
|
- }
|
|
|
-}</programlisting>
|
|
|
-
|
|
|
- <para>In the above example, the security interceptor will be applied
|
|
|
- to every instance of <literal>PersistableEntity</literal>, which is an
|
|
|
- abstract class not shown (you can use any other class or
|
|
|
- <literal>pointcut</literal> expression you like). For those curious,
|
|
|
- <literal>AspectJCallback</literal> is needed because the
|
|
|
- <literal>proceed();</literal> statement has special meaning only
|
|
|
- within an <literal>around()</literal> body. The
|
|
|
- <literal>AspectJSecurityInterceptor</literal> calls this anonymous
|
|
|
- <literal>AspectJCallback</literal> class when it wants the target
|
|
|
- object to continue.</para>
|
|
|
-
|
|
|
- <para>You will need to configure Spring to load the aspect and wire it
|
|
|
- with the <literal>AspectJSecurityInterceptor</literal>. A bean
|
|
|
- declaration which achieves this is shown below:</para>
|
|
|
-
|
|
|
- <programlisting>
|
|
|
-<bean id="domainObjectInstanceSecurityAspect"
|
|
|
- class="org.acegisecurity.samples.aspectj.DomainObjectInstanceSecurityAspect"
|
|
|
- factory-method="aspectOf">
|
|
|
- <property name="securityInterceptor"><ref bean="aspectJSecurityInterceptor"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
- </programlisting>
|
|
|
-
|
|
|
- <para>That's it! Now you can create your beans from anywhere within
|
|
|
- your application, using whatever means you think fit (eg <literal>new
|
|
|
- Person();</literal>) and they will have the security interceptor
|
|
|
- applied.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="filter-invocation-authorization">
|
|
|
- <title>FilterInvocation Security Interceptor</title>
|
|
|
-
|
|
|
- <para>To secure <literal>FilterInvocation</literal>s, developers need
|
|
|
- to add a filter to their <literal>web.xml</literal> that delegates to
|
|
|
- the <literal>FilterSecurityInterceptor</literal>. A typical
|
|
|
- configuration example is provided below:</para>
|
|
|
-
|
|
|
- <programlisting><filter>
|
|
|
- <filter-name>Acegi HTTP Request Security Filter</filter-name>
|
|
|
- <filter-class>org.acegisecurity.util.FilterToBeanProxy</filter-class>
|
|
|
- <init-param>
|
|
|
- <param-name>targetClass</param-name>
|
|
|
- <param-value>org.acegisecurity.intercept.web.FilterSecurityInterceptor</param-value>
|
|
|
- </init-param>
|
|
|
-</filter>
|
|
|
-
|
|
|
-<filter-mapping>
|
|
|
- <filter-name>Acegi HTTP Request Security Filter</filter-name>
|
|
|
- <url-pattern>/*</url-pattern>
|
|
|
-</filter-mapping></programlisting>
|
|
|
-
|
|
|
- <para>Notice that the filter is actually a
|
|
|
- <literal>FilterToBeanProxy</literal>. Most of the filters used by
|
|
|
- Acegi Security use this class. Refer to the Filters section to learn
|
|
|
- more about this bean.</para>
|
|
|
-
|
|
|
- <para>In the application context you will need to configure three
|
|
|
- beans:</para>
|
|
|
-
|
|
|
- <programlisting><bean id="exceptionTranslationFilter" class="org.acegisecurity.ui.ExceptionTranslationFilter">
|
|
|
- <property name="authenticationEntryPoint"><ref local="authenticationEntryPoint"/></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="authenticationEntryPoint" class="org.acegisecurity.ui.webapp.AuthenticationProcessingFilterEntryPoint">
|
|
|
- <property name="loginFormUrl"><value>/acegilogin.jsp</value></property>
|
|
|
- <property name="forceHttps"><value>false</value></property>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<bean id="filterSecurityInterceptor" class="org.acegisecurity.intercept.web.FilterSecurityInterceptor">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
|
|
|
- <property name="objectDefinitionSource">
|
|
|
- <value>
|
|
|
- CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
|
|
|
- \A/secure/super/.*\Z=ROLE_WE_DONT_HAVE
|
|
|
- \A/secure/.*\Z=ROLE_SUPERVISOR,ROLE_TELLER
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean> </programlisting>
|
|
|
-
|
|
|
- <para>The <classname>ExceptionTranslationFilter</classname> provides
|
|
|
- the bridge between Java exceptions and HTTP responses. It is solely
|
|
|
- concerned with maintaining the user interface. This filter does not do
|
|
|
- any actual security enforcement. If an
|
|
|
- <exceptionname>AuthenticationException</exceptionname> is detected,
|
|
|
- the filter will call the AuthenticationEntryPoint to commence the
|
|
|
- authentication process (e.g. a user login).</para>
|
|
|
-
|
|
|
- <para>The <literal>AuthenticationEntryPoint</literal> will be called
|
|
|
- if the user requests a secure HTTP resource but they are not
|
|
|
- authenticated. The class handles presenting the appropriate response
|
|
|
- to the user so that authentication can begin. Three concrete
|
|
|
- implementations are provided with Acegi Security:
|
|
|
- <literal>AuthenticationProcessingFilterEntryPoint</literal> for
|
|
|
- commencing a form-based authentication,
|
|
|
- <literal>BasicProcessingFilterEntryPoint</literal> for commencing a
|
|
|
- HTTP Basic authentication process, and
|
|
|
- <literal>CasProcessingFilterEntryPoint</literal> for commencing a
|
|
|
- JA-SIG Central Authentication Service (CAS) login. The
|
|
|
- <literal>AuthenticationProcessingFilterEntryPoint</literal> and
|
|
|
- <literal>CasProcessingFilterEntryPoint</literal> have optional
|
|
|
- properties related to forcing the use of HTTPS, so please refer to the
|
|
|
- JavaDocs if you require this.</para>
|
|
|
-
|
|
|
- <para><literal>FilterSecurityInterceptor</literal> is responsible for
|
|
|
- handling the security of HTTP resources. Like any other security
|
|
|
- interceptor, it requires a reference to an
|
|
|
- <literal>AuthenticationManager</literal> and an
|
|
|
- <literal>AccessDecisionManager</literal>, which are both discussed in
|
|
|
- separate sections below. The
|
|
|
- <literal>FilterSecurityInterceptor</literal> is also configured with
|
|
|
- configuration attributes that apply to different HTTP URL requests. A
|
|
|
- full discussion of configuration attributes is provided in the High
|
|
|
- Level Design section of this document.</para>
|
|
|
-
|
|
|
- <para>The <literal>FilterSecurityInterceptor</literal> can be
|
|
|
- configured with configuration attributes in two ways. The first is via
|
|
|
- a property editor and the application context, which is shown above.
|
|
|
- The second is via writing your own
|
|
|
- <literal>ObjectDefinitionSource</literal>, although this is beyond the
|
|
|
- scope of this document. Irrespective of the approach used, the
|
|
|
- <literal>ObjectDefinitionSource</literal> is responsible for returning
|
|
|
- a <literal>ConfigAttributeDefinition</literal> object that contains
|
|
|
- all of the configuration attributes associated with a single secure
|
|
|
- HTTP URL.</para>
|
|
|
-
|
|
|
- <para>It should be noted that the
|
|
|
- <literal>FilterSecurityInterceptor.setObjectDefinitionSource()</literal>
|
|
|
- method actually expects an instance of
|
|
|
- <literal>FilterInvocationDefinitionSource</literal>. This is a marker
|
|
|
- interface which subclasses <literal>ObjectDefinitionSource</literal>.
|
|
|
- It simply denotes the <literal>ObjectDefinitionSource</literal>
|
|
|
- understands <literal>FilterInvocation</literal>s. In the interests of
|
|
|
- simplicity we'll continue to refer to the
|
|
|
- <literal>FilterInvocationDefinitionSource</literal> as an
|
|
|
- <literal>ObjectDefinitionSource</literal>, as the distinction is of
|
|
|
- little relevance to most users of the
|
|
|
- <literal>FilterSecurityInterceptor</literal>.</para>
|
|
|
-
|
|
|
- <para>If using the application context property editor approach (as
|
|
|
- shown above), commas are used to delimit the different configuration
|
|
|
- attributes that apply to each HTTP URL. Each configuration attribute
|
|
|
- is assigned into its own <literal>SecurityConfig</literal> object. The
|
|
|
- <literal>SecurityConfig</literal> object is discussed in the High
|
|
|
- Level Design section. The <literal>ObjectDefinitionSource</literal>
|
|
|
- created by the property editor,
|
|
|
- <literal>FilterInvocationDefinitionSource</literal>, matches
|
|
|
- configuration attributes against <literal>FilterInvocations</literal>
|
|
|
- based on expression evaluation of the request URL. Two standard
|
|
|
- expression syntaxes are supported. The default is to treat all
|
|
|
- expressions as regular expressions. Alternatively, the presence of a
|
|
|
- <literal>PATTERN_TYPE_APACHE_ANT</literal> directive will cause all
|
|
|
- expressions to be treated as Apache Ant paths. It is not possible to
|
|
|
- mix expression syntaxes within the same definition. For example, the
|
|
|
- earlier configuration could be generated using Apache Ant paths as
|
|
|
- follows:</para>
|
|
|
-
|
|
|
- <programlisting><bean id="filterInvocationInterceptor" class="org.acegisecurity.intercept.web.FilterSecurityInterceptor">
|
|
|
- <property name="authenticationManager"><ref bean="authenticationManager"/></property>
|
|
|
- <property name="accessDecisionManager"><ref bean="accessDecisionManager"/></property>
|
|
|
- <property name="runAsManager"><ref bean="runAsManager"/></property>
|
|
|
- <property name="objectDefinitionSource">
|
|
|
- <value>
|
|
|
- CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON
|
|
|
- PATTERN_TYPE_APACHE_ANT
|
|
|
- /secure/super/**=ROLE_WE_DONT_HAVE
|
|
|
- /secure/**=ROLE_SUPERVISOR,ROLE_TELLER
|
|
|
- </value>
|
|
|
- </property>
|
|
|
-</bean> </programlisting>
|
|
|
-
|
|
|
- <para>Irrespective of the type of expression syntax used, expressions
|
|
|
- are always evaluated in the order they are defined. Thus it is
|
|
|
- important that more specific expressions are defined higher in the
|
|
|
- list than less specific expressions. This is reflected in our example
|
|
|
- above, where the more specific <literal>/secure/super/</literal>
|
|
|
- pattern appears higher than the less specific
|
|
|
- <literal>/secure/</literal> pattern. If they were reversed, the
|
|
|
- <literal>/secure/</literal> pattern would always match and the
|
|
|
- <literal>/secure/super/</literal> pattern would never be
|
|
|
- evaluated.</para>
|
|
|
-
|
|
|
- <para>The special keyword
|
|
|
- <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> causes
|
|
|
- the <literal>FilterInvocationDefinitionSource</literal> to
|
|
|
- automatically convert a request URL to lowercase before comparison
|
|
|
- against the expressions. Whilst by default the case of the request URL
|
|
|
- is not converted, it is generally recommended to use
|
|
|
- <literal>CONVERT_URL_TO_LOWERCASE_BEFORE_COMPARISON</literal> and
|
|
|
- write each expression assuming lowercase.</para>
|
|
|
-
|
|
|
- <para>As with other security interceptors, the
|
|
|
- <literal>validateConfigAttributes</literal> property is observed. When
|
|
|
- set to <literal>true</literal> (the default), at startup time the
|
|
|
- <literal>FilterSecurityInterceptor</literal> will evaluate if the
|
|
|
- provided configuration attributes are valid. It does this by checking
|
|
|
- each configuration attribute can be processed by either the
|
|
|
- <literal>AccessDecisionManager</literal> or the
|
|
|
- <literal>RunAsManager</literal>. If neither of these can process a
|
|
|
- given configuration attribute, an exception is thrown.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="domain-acls">
|
|
|
- <title>Domain Object Security</title>
|
|
|
-
|
|
|
- <section id="domain-acls-overview">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
|
|
|
- ACL module. The new ACL module is a significant rewrite of the
|
|
|
- existing ACL module. The new module can be found under the
|
|
|
- <literal>org.acegisecurity.acls</literal> package, with the old ACL
|
|
|
- module under <literal>org.acegisecurity.acl</literal>. We encourage
|
|
|
- users to consider testing with the new ACL module and build
|
|
|
- applications with it. The old ACL module should be considered
|
|
|
- deprecated and may be removed from a future release.</para>
|
|
|
-
|
|
|
- <para>Complex applications often will find the need to define access
|
|
|
- permissions not simply at a web request or method invocation level.
|
|
|
- Instead, security decisions need to comprise both who
|
|
|
- (<literal>Authentication</literal>), where
|
|
|
- (<literal>MethodInvocation</literal>) and what
|
|
|
- (<literal>SomeDomainObject</literal>). In other words, authorization
|
|
|
- decisions also need to consider the actual domain object instance
|
|
|
- subject of a method invocation.</para>
|
|
|
-
|
|
|
- <para>Imagine you're designing an application for a pet clinic. There
|
|
|
- will be two main groups of users of your Spring-based application:
|
|
|
- staff of the pet clinic, as well as the pet clinic's customers. The
|
|
|
- staff will have access to all of the data, whilst your customers will
|
|
|
- only be able to see their own customer records. To make it a little
|
|
|
- more interesting, your customers can allow other users to see their
|
|
|
- customer records, such as their "puppy preschool "mentor or president
|
|
|
- of their local "Pony Club". Using Acegi Security as the foundation,
|
|
|
- you have several approaches that can be used:<orderedlist>
|
|
|
- <listitem>
|
|
|
- <para>Write your business methods to enforce the security. You
|
|
|
- could consult a collection within the
|
|
|
- <literal>Customer</literal> domain object instance to determine
|
|
|
- which users have access. By using the
|
|
|
- <literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
|
|
|
- you'll be able to access the <literal>Authentication</literal>
|
|
|
- object.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Write an <literal>AccessDecisionVoter</literal> to enforce
|
|
|
- the security from the <literal>GrantedAuthority[]</literal>s
|
|
|
- stored in the <literal>Authentication</literal> object. This
|
|
|
- would mean your <literal>AuthenticationManager</literal> would
|
|
|
- need to populate the <literal>Authentication</literal> with
|
|
|
- custom <literal>GrantedAuthority</literal>[]s representing each
|
|
|
- of the <literal>Customer</literal> domain object instances the
|
|
|
- principal has access to.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Write an <literal>AccessDecisionVoter</literal> to enforce
|
|
|
- the security and open the target <literal>Customer</literal>
|
|
|
- domain object directly. This would mean your voter needs access
|
|
|
- to a DAO that allows it to retrieve the
|
|
|
- <literal>Customer</literal> object. It would then access the
|
|
|
- <literal>Customer</literal> object's collection of approved
|
|
|
- users and make the appropriate decision.</para>
|
|
|
- </listitem>
|
|
|
- </orderedlist></para>
|
|
|
-
|
|
|
- <para>Each one of these approaches is perfectly legitimate. However,
|
|
|
- the first couples your authorization checking to your business code.
|
|
|
- The main problems with this include the enhanced difficulty of unit
|
|
|
- testing and the fact it would be more difficult to reuse the
|
|
|
- <literal>Customer</literal> authorization logic elsewhere. Obtaining
|
|
|
- the <literal>GrantedAuthority[]</literal>s from the
|
|
|
- <literal>Authentication</literal> object is also fine, but will not
|
|
|
- scale to large numbers of <literal>Customer</literal>s. If a user
|
|
|
- might be able to access 5,000 <literal>Customer</literal>s (unlikely
|
|
|
- in this case, but imagine if it were a popular vet for a large Pony
|
|
|
- Club!) the amount of memory consumed and time required to construct
|
|
|
- the <literal>Authentication</literal> object would be undesirable. The
|
|
|
- final method, opening the <literal>Customer</literal> directly from
|
|
|
- external code, is probably the best of the three. It achieves
|
|
|
- separation of concerns, and doesn't misuse memory or CPU cycles, but
|
|
|
- it is still inefficient in that both the
|
|
|
- <literal>AccessDecisionVoter</literal> and the eventual business
|
|
|
- method itself will perform a call to the DAO responsible for
|
|
|
- retrieving the <literal>Customer</literal> object. Two accesses per
|
|
|
- method invocation is clearly undesirable. In addition, with every
|
|
|
- approach listed you'll need to write your own access control list
|
|
|
- (ACL) persistence and business logic from scratch.</para>
|
|
|
-
|
|
|
- <para>Fortunately, there is another alternative, which we'll talk
|
|
|
- about below.</para>
|
|
|
- </section>
|
|
|
-
|
|
|
- <section id="domain-acls-key-concepts">
|
|
|
- <title>Key Concepts</title>
|
|
|
-
|
|
|
- <para>The org.acegisecurity.acls package should be consulted for its
|
|
|
- major interfaces. The key interfaces are:</para>
|
|
|
-
|
|
|
- <itemizedlist spacing="compact">
|
|
|
- <listitem>
|
|
|
- <para><literal>Acl</literal>: Every domain object has one and only
|
|
|
- one <literal>Acl</literal> object, which internally holds the
|
|
|
- <literal>AccessControlEntry</literal>s as well as knows the owner
|
|
|
- of the <literal>Acl</literal>. An Acl does not refer directly to
|
|
|
- the domain object, but instead to an
|
|
|
- <literal>ObjectIdentity</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal><literal>AccessControlEntry</literal></literal>: An
|
|
|
- Acl holds multiple <literal>AccessControlEntry</literal>s, which
|
|
|
- are often abbreviated as ACEs in the framework. Each ACE refers to
|
|
|
- a specific tuple of <literal>Permission</literal>,
|
|
|
- <literal>Sid</literal> and <literal>Acl</literal>. An ACE can also
|
|
|
- be granting or non-granting and contain audit settings.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>Permission</literal>: A permission represents an
|
|
|
- immutable particular bit mask, and offers convenience functions
|
|
|
- for bit masking and outputting information.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>Sid</literal>: The ACL module needs to refer to
|
|
|
- principals and <literal>GrantedAuthority[]</literal>s. A level of
|
|
|
- indirection is provided by the <literal>Sid</literal> interface.
|
|
|
- Common classes include <literal>PrincipalSid</literal> (to
|
|
|
- represent the principal inside an
|
|
|
- <literal>Authentication</literal> object) and
|
|
|
- <literal>GrantedAuthoritySid</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>ObjectIdentity</literal>: Each domain object is
|
|
|
- represented internally within the ACL module by an
|
|
|
- <literal>ObjectIdentity</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>AclService</literal>: Retrieves the
|
|
|
- <literal>Acl</literal> applicable for a given
|
|
|
- <literal>ObjectIdentity</literal>.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para><literal>MutableAclService</literal>: Allows a modified
|
|
|
- <literal>Acl</literal> to be presented for persistence. It is not
|
|
|
- essential to use this interface if you do not wish.</para>
|
|
|
- </listitem>
|
|
|
- </itemizedlist>
|
|
|
-
|
|
|
- <para>The ACL module was based on extensive feedback from the user
|
|
|
- community following real-world use of the original ACL module. This
|
|
|
- feedback resulted in a rearchitecture of the ACL module to offer
|
|
|
- significantly enhanced performance (particularly in the area of
|
|
|
- database retrieval), significantly better encapsulation, higher
|
|
|
- cohesion, and enhanced customisation points.</para>
|
|
|
-
|
|
|
- <para>The Contacts Sample that ships with Acegi Security 1.0.3 offers
|
|
|
- a demonstration of the new ACL module. Converting Contacts from using
|
|
|
- the old module to the new module was relatively simple, and users of
|
|
|
- the old ACL module will likely find their applications can be modified
|
|
|
- with relatively little work.</para>
|
|
|
-
|
|
|
- <para>We will document the new ACL module more fully with a subsequent
|
|
|
- release. Please note that the new ACL module should be considered a
|
|
|
- preview only (ie do not use in production without proper prior
|
|
|
- testing), and there is a small chance there may be changes between
|
|
|
- 1.0.3 and 1.1.0 when it will become final. Nevertheless,
|
|
|
- compatibility-affecting changes are considered quite unlikely,
|
|
|
- especially given the module is already based on several years of
|
|
|
- feedback from users of the original ACL module.</para>
|
|
|
- </section>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="domain-acls-old">
|
|
|
- <title>Domain Object Security (old ACL module)</title>
|
|
|
-
|
|
|
- <section id="domain-acls-overview-old">
|
|
|
- <title>Overview</title>
|
|
|
-
|
|
|
- <para>PLEASE NOTE: Acegi Security 1.0.3 contains a preview of a new
|
|
|
- ACL module. The new ACL module is a significant rewrite of the
|
|
|
- existing ACL module. The new module can be found under the
|
|
|
- <literal>org.acegisecurity.acls</literal> package, with the old ACL
|
|
|
- module under <literal>org.acegisecurity.acl</literal>. We encourage
|
|
|
- users to consider testing with the new ACL module and build
|
|
|
- applications with it. The old ACL module should be considered
|
|
|
- deprecated and may be removed from a future release.</para>
|
|
|
-
|
|
|
- <para>Complex applications often will find the need to define access
|
|
|
- permissions not simply at a web request or method invocation level.
|
|
|
- Instead, security decisions need to comprise both who
|
|
|
- (<literal>Authentication</literal>), where
|
|
|
- (<literal>MethodInvocation</literal>) and what
|
|
|
- (<literal>SomeDomainObject</literal>). In other words, authorization
|
|
|
- decisions also need to consider the actual domain object instance
|
|
|
- subject of a method invocation.</para>
|
|
|
-
|
|
|
- <para>Imagine you're designing an application for a pet clinic. There
|
|
|
- will be two main groups of users of your Spring-based application:
|
|
|
- staff of the pet clinic, as well as the pet clinic's customers. The
|
|
|
- staff will have access to all of the data, whilst your customers will
|
|
|
- only be able to see their own customer records. To make it a little
|
|
|
- more interesting, your customers can allow other users to see their
|
|
|
- customer records, such as their "puppy preschool "mentor or president
|
|
|
- of their local "Pony Club". Using Acegi Security as the foundation,
|
|
|
- you have several approaches that can be used:<orderedlist>
|
|
|
- <listitem>
|
|
|
- <para>Write your business methods to enforce the security. You
|
|
|
- could consult a collection within the
|
|
|
- <literal>Customer</literal> domain object instance to determine
|
|
|
- which users have access. By using the
|
|
|
- <literal>SecurityContextHolder.getContext().getAuthentication()</literal>,
|
|
|
- you'll be able to access the <literal>Authentication</literal>
|
|
|
- object.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Write an <literal>AccessDecisionVoter</literal> to enforce
|
|
|
- the security from the <literal>GrantedAuthority[]</literal>s
|
|
|
- stored in the <literal>Authentication</literal> object. This
|
|
|
- would mean your <literal>AuthenticationManager</literal> would
|
|
|
- need to populate the <literal>Authentication</literal> with
|
|
|
- custom <literal>GrantedAuthority</literal>[]s representing each
|
|
|
- of the <literal>Customer</literal> domain object instances the
|
|
|
- principal has access to.</para>
|
|
|
- </listitem>
|
|
|
-
|
|
|
- <listitem>
|
|
|
- <para>Write an <literal>AccessDecisionVoter</literal> to enforce
|
|
|
- the security and open the target <literal>Customer</literal>
|
|
|
- domain object directly. This would mean your voter needs access
|
|
|
- to a DAO that allows it to retrieve the
|
|
|
- <literal>Customer</literal> object. It would then access the
|
|
|
- <literal>Customer</literal> object's collection of approved
|
|
|
- users and make the appropriate decision.</para>
|
|
|
- </listitem>
|
|
|
- </orderedlist></para>
|
|
|
-
|
|
|
- <para>Each one of these approaches is perfectly legitimate. However,
|
|
|
- the first couples your authorization checking to your business code.
|
|
|
- The main problems with this include the enhanced difficulty of unit
|
|
|
- testing and the fact it would be more difficult to reuse the
|
|
|
- <literal>Customer</literal> authorization logic elsewhere. Obtaining
|
|
|
- the <literal>GrantedAuthority[]</literal>s from the
|
|
|
- <literal>Authentication</literal> object is also fine, but will not
|
|
|
- scale to large numbers of <literal>Customer</literal>s. If a user
|
|
|
- might be able to access 5,000 <literal>Customer</literal>s (unlikely
|
|
|
- in this case, but imagine if it were a popular vet for a large Pony
|
|
|
- Club!) the amount of memory consumed and time required to construct
|
|
|
- the <literal>Authentication</literal> object would be undesirable. The
|
|
|
- final method, opening the <literal>Customer</literal> directly from
|
|
|
- external code, is probably the best of the three. It achieves
|
|
|
- separation of concerns, and doesn't misuse memory or CPU cycles, but
|
|
|
- it is still inefficient in that both the
|
|
|
- <literal>AccessDecisionVoter</literal> and the eventual business
|
|
|
- method itself will perform a call to the DAO responsible for
|
|
|
- retrieving the <literal>Customer</literal> object. Two accesses per
|
|
|
- method invocation is clearly undesirable. In addition, with every
|
|
|
- approach listed you'll need to write your own access control list
|
|
|
- (ACL) persistence and business logic from scratch.</para>
|
|
|
-
|
|
|
- <para>Fortunately, there is another alternative, which we'll talk
|
|
|
- about below.</para>
|
|
|
- </section>
|
|
|
-
|
|
|
- <section id="domain-acls-basic-old">
|
|
|
- <title>Basic ACL Package</title>
|
|
|
-
|
|
|
- <para>Please note that our Basic ACL services are currently being
|
|
|
- refactored. We expect release 1.1.0 will contain this new code.
|
|
|
- Planned code is already in the Acegi Security Subversion sandbox, so
|
|
|
- please check there if you have a new application requiring ACLs or are
|
|
|
- in the planning stages. The Basic ACL services will be deprecated from
|
|
|
- release 1.1.0.</para>
|
|
|
-
|
|
|
- <para>The <literal>org.acegisecurity.acl</literal> package is very
|
|
|
- simple, comprising only a handful of interfaces and a single class, as
|
|
|
- shown in Figure 6. It provides the basic foundation for access control
|
|
|
- list (ACL) lookups.</para>
|
|
|
-
|
|
|
- <para><mediaobject>
|
|
|
- <imageobject role="html">
|
|
|
- <imagedata align="center" fileref="images/ACLSecurity.gif"
|
|
|
- format="GIF" />
|
|
|
- </imageobject>
|
|
|
-
|
|
|
- <caption>
|
|
|
- <para>Figure 6: Access Control List Manager</para>
|
|
|
- </caption>
|
|
|
- </mediaobject></para>
|
|
|
-
|
|
|
- <para>The central interface is <literal>AclManager</literal>, which is
|
|
|
- defined by two methods:</para>
|
|
|
-
|
|
|
- <para><programlisting>public AclEntry[] getAcls(java.lang.Object domainInstance);
|
|
|
-public AclEntry[] getAcls(java.lang.Object domainInstance, Authentication authentication);</programlisting></para>
|
|
|
-
|
|
|
- <para><literal>AclManager</literal> is intended to be used as a
|
|
|
- collaborator against your business objects, or, more desirably,
|
|
|
- <literal>AccessDecisionVoter</literal>s. This means you use Spring's
|
|
|
- normal <literal>ApplicationContext</literal> features to wire up your
|
|
|
- <literal>AccessDecisionVoter</literal> (or business method) with an
|
|
|
- <literal>AclManager</literal>. Consideration was given to placing the
|
|
|
- ACL information in the <literal>ContextHolder</literal>, but it was
|
|
|
- felt this would be inefficient both in terms of memory usage as well
|
|
|
- as the time spent loading potentially unused ACL information. The
|
|
|
- trade-off of needing to wire up a collaborator for those objects
|
|
|
- requiring ACL information is rather minor, particularly in a
|
|
|
- Spring-managed application.</para>
|
|
|
-
|
|
|
- <para>The first method of the <literal>AclManager</literal> will
|
|
|
- return all ACLs applying to the domain object instance passed to it.
|
|
|
- The second method does the same, but only returns those ACLs which
|
|
|
- apply to the passed <literal>Authentication</literal> object.</para>
|
|
|
-
|
|
|
- <para>The <literal>AclEntry</literal> interface returned by
|
|
|
- <literal>AclManager</literal> is merely a marker interface. You will
|
|
|
- need to provide an implementation that reflects that ACL permissions
|
|
|
- for your application.</para>
|
|
|
-
|
|
|
- <para>Rounding out the <literal>org.acegisecurity.acl</literal>
|
|
|
- package is an <literal>AclProviderManager</literal> class, with a
|
|
|
- corresponding <literal>AclProvider</literal> interface.
|
|
|
- <literal>AclProviderManager</literal> is a concrete implementation of
|
|
|
- <literal>AclManager</literal>, which iterates through registered
|
|
|
- <literal>AclProvider</literal>s. The first
|
|
|
- <literal>AclProvider</literal> that indicates it can authoritatively
|
|
|
- provide ACL information for the presented domain object instance will
|
|
|
- be used. This is very similar to the
|
|
|
- <literal>AuthenticationProvider</literal> interface used for
|
|
|
- authentication.</para>
|
|
|
-
|
|
|
- <para>With this background, let's now look at a usable ACL
|
|
|
- implementation.</para>
|
|
|
-
|
|
|
- <para>Acegi Security includes a production-quality ACL provider
|
|
|
- implementation, which is shown in Figure 7.</para>
|
|
|
-
|
|
|
- <para><mediaobject>
|
|
|
- <imageobject role="html">
|
|
|
- <imagedata align="center" fileref="images/BasicAclProvider.gif"
|
|
|
- format="GIF" />
|
|
|
- </imageobject>
|
|
|
-
|
|
|
- <caption>
|
|
|
- <para>Figure 7: Basic ACL Manager</para>
|
|
|
- </caption>
|
|
|
- </mediaobject></para>
|
|
|
-
|
|
|
- <para>The implementation is based on integer masking, which is
|
|
|
- commonly used for ACL permissions given its flexibility and speed.
|
|
|
- Anyone who has used Unix's <literal>chmod</literal> command will know
|
|
|
- all about this type of permission masking (eg <literal>chmod
|
|
|
- 777</literal>). You'll find the classes and interfaces for the integer
|
|
|
- masking ACL package under
|
|
|
- <literal>org.acegisecurity.acl.basic</literal>.</para>
|
|
|
-
|
|
|
- <para>Extending the <literal>AclEntry</literal> interface is a
|
|
|
- <literal>BasicAclEntry</literal> interface, with the main methods
|
|
|
- shown below:</para>
|
|
|
-
|
|
|
- <para><programlisting>public AclObjectIdentity getAclObjectIdentity();
|
|
|
-public AclObjectIdentity getAclObjectParentIdentity();
|
|
|
-public int getMask();
|
|
|
-public java.lang.Object getRecipient();</programlisting></para>
|
|
|
-
|
|
|
- <para>As shown, each <literal>BasicAclEntry</literal> has four main
|
|
|
- properties. The <literal>mask</literal> is the integer that represents
|
|
|
- the permissions granted to the <literal>recipient</literal>. The
|
|
|
- <literal>aclObjectIdentity</literal> is able to identify the domain
|
|
|
- object instance for which the ACL applies, and the
|
|
|
- <literal>aclObjectParentIdentity</literal> optionally specifies the
|
|
|
- parent of the domain object instance. Multiple
|
|
|
- <literal>BasicAclEntry</literal>s usually exist against a single
|
|
|
- domain object instance, and as suggested by the parent identity
|
|
|
- property, permissions granted higher in the object hierarchy will
|
|
|
- trickle down and be inherited (unless blocked by integer zero).</para>
|
|
|
-
|
|
|
- <para><literal>BasicAclEntry</literal> implementations typically
|
|
|
- provide convenience methods, such as
|
|
|
- <literal>isReadAllowed()</literal>, to avoid application classes
|
|
|
- needing to perform bit masking themselves. The
|
|
|
- <literal>SimpleAclEntry</literal> and
|
|
|
- <literal>AbstractBasicAclEntry</literal> demonstrate and provide much
|
|
|
- of this bit masking logic.</para>
|
|
|
-
|
|
|
- <para>The <literal>AclObjectIdentity</literal> itself is merely a
|
|
|
- marker interface, so you need to provide implementations for your
|
|
|
- domain objects. However, the package does include a
|
|
|
- <literal>NamedEntityObjectIdentity</literal> implementation which will
|
|
|
- suit many needs. The <literal>NamedEntityObjectIdentity</literal>
|
|
|
- identifies a given domain object instance by the classname of the
|
|
|
- instance and the identity of the instance. A
|
|
|
- <literal>NamedEntityObjectIdentity</literal> can be constructed
|
|
|
- manually (by calling the constructor and providing the classname and
|
|
|
- identity <literal>String</literal>s), or by passing in any domain
|
|
|
- object that contains a <literal>getId()</literal> method.</para>
|
|
|
-
|
|
|
- <para>The actual <literal>AclProvider</literal> implementation is
|
|
|
- named <literal>BasicAclProvider</literal>. It has adopted a similar
|
|
|
- design to that used by the authentication-related
|
|
|
- <literal>DaoAuthenticationProvder</literal>. Specifically, you define
|
|
|
- a <literal>BasicAclDao</literal> against the provider, so different
|
|
|
- ACL repository types can be accessed in a pluggable manner. The
|
|
|
- <literal>BasicAclProvider</literal> also supports pluggable cache
|
|
|
- providers (with Acegi Security including an implementation that fronts
|
|
|
- EH-CACHE).</para>
|
|
|
-
|
|
|
- <para>The <literal>BasicAclDao</literal> interface is very simple to
|
|
|
- implement:</para>
|
|
|
-
|
|
|
- <para><programlisting>public BasicAclEntry[] getAcls(AclObjectIdentity aclObjectIdentity);</programlisting></para>
|
|
|
-
|
|
|
- <para>A <literal>BasicAclDao</literal> implementation needs to
|
|
|
- understand the presented <literal>AclObjectIdentity</literal> and how
|
|
|
- it maps to a storage repository, find the relevant records, and create
|
|
|
- appropriate <literal>BasicAclEntry</literal> objects and return
|
|
|
- them.</para>
|
|
|
-
|
|
|
- <para>Acegi Security includes a single <literal>BasicAclDao</literal>
|
|
|
- implementation called <literal>JdbcDaoImpl</literal>. As implied by
|
|
|
- the name, <literal>JdbcDaoImpl</literal> accesses ACL information from
|
|
|
- a JDBC database. There is also an extended version of this DAO,
|
|
|
- <literal>JdbcExtendedDaoImpl</literal>, which provides CRUD operations
|
|
|
- on the JDBC database, although we won't discuss these features here.
|
|
|
- The default database schema and some sample data will aid in
|
|
|
- understanding its function:</para>
|
|
|
-
|
|
|
- <para><programlisting>CREATE TABLE acl_object_identity (
|
|
|
- id IDENTITY NOT NULL,
|
|
|
- object_identity VARCHAR_IGNORECASE(250) NOT NULL,
|
|
|
- parent_object INTEGER,
|
|
|
- acl_class VARCHAR_IGNORECASE(250) NOT NULL,
|
|
|
- CONSTRAINT unique_object_identity UNIQUE(object_identity),
|
|
|
- FOREIGN KEY (parent_object) REFERENCES acl_object_identity(id)
|
|
|
-);
|
|
|
-
|
|
|
-CREATE TABLE acl_permission (
|
|
|
- id IDENTITY NOT NULL,
|
|
|
- acl_object_identity INTEGER NOT NULL,
|
|
|
- recipient VARCHAR_IGNORECASE(100) NOT NULL,
|
|
|
- mask INTEGER NOT NULL,
|
|
|
- CONSTRAINT unique_recipient UNIQUE(acl_object_identity, recipient),
|
|
|
- FOREIGN KEY (acl_object_identity) REFERENCES acl_object_identity(id)
|
|
|
-);
|
|
|
-
|
|
|
-INSERT INTO acl_object_identity VALUES (1, 'corp.DomainObject:1', null, 'org.acegisecurity.acl.basic.SimpleAclEntry');
|
|
|
-INSERT INTO acl_object_identity VALUES (2, 'corp.DomainObject:2', 1, 'org.acegisecurity.acl.basic.SimpleAclEntry');
|
|
|
-INSERT INTO acl_object_identity VALUES (3, 'corp.DomainObject:3', 1, 'org.acegisecurity.acl.basic.SimpleAclEntry');
|
|
|
-INSERT INTO acl_object_identity VALUES (4, 'corp.DomainObject:4', 1, 'org.acegisecurity.acl.basic.SimpleAclEntry');
|
|
|
-INSERT INTO acl_object_identity VALUES (5, 'corp.DomainObject:5', 3, 'org.acegisecurity.acl.basic.SimpleAclEntry');
|
|
|
-INSERT INTO acl_object_identity VALUES (6, 'corp.DomainObject:6', 3, 'org.acegisecurity.acl.basic.SimpleAclEntry');
|
|
|
-
|
|
|
-INSERT INTO acl_permission VALUES (null, 1, 'ROLE_SUPERVISOR', 1);
|
|
|
-INSERT INTO acl_permission VALUES (null, 2, 'ROLE_SUPERVISOR', 0);
|
|
|
-INSERT INTO acl_permission VALUES (null, 2, 'marissa', 2);
|
|
|
-INSERT INTO acl_permission VALUES (null, 3, 'scott', 14);
|
|
|
-INSERT INTO acl_permission VALUES (null, 6, 'scott', 1);</programlisting></para>
|
|
|
-
|
|
|
- <para>As can be seen, database-specific constraints are used
|
|
|
- extensively to ensure the integrity of the ACL information. If you
|
|
|
- need to use a different database (Hypersonic SQL statements are shown
|
|
|
- above), you should try to implement equivalent constraints. The
|
|
|
- equivalent Oracle configuration is:</para>
|
|
|
-
|
|
|
- <para><programlisting>CREATE TABLE ACL_OBJECT_IDENTITY (
|
|
|
- ID number(19,0) not null,
|
|
|
- OBJECT_IDENTITY varchar2(255) NOT NULL,
|
|
|
- PARENT_OBJECT number(19,0),
|
|
|
- ACL_CLASS varchar2(255) NOT NULL,
|
|
|
- primary key (ID)
|
|
|
-);
|
|
|
-ALTER TABLE ACL_OBJECT_IDENTITY ADD CONTRAINT FK_PARENT_OBJECT foreign key (ID) references ACL_OBJECT_IDENTITY
|
|
|
-
|
|
|
-CREATE SEQUENCE ACL_OBJECT_IDENTITY_SEQ;
|
|
|
-
|
|
|
-CREATE OR REPLACE TRIGGER ACL_OBJECT_IDENTITY_ID
|
|
|
-BEFORE INSERT ON ACL_OBJECT_IDENTITY
|
|
|
-FOR EACH ROW
|
|
|
-BEGIN
|
|
|
- SELECT ACL_OBJECT_IDENTITY_SEQ.NEXTVAL INTO :new.id FROM dual;
|
|
|
-END;
|
|
|
-
|
|
|
-CREATE TABLE ACL_PERMISSION (
|
|
|
- ID number(19,0) not null,
|
|
|
- ACL_OBJECT_IDENTITY number(19,0) NOT NULL,
|
|
|
- RECIPIENT varchar2(255) NOT NULL,
|
|
|
- MASK number(19,0) NOT NULL,
|
|
|
- primary key (ID)
|
|
|
-);
|
|
|
-
|
|
|
-ALTER TABLE ACL_PERMISSION ADD CONTRAINT UNIQUE_ID_RECIPIENT unique (acl_object_identity, recipient);
|
|
|
-
|
|
|
-CREATE SEQUENCE ACL_PERMISSION_SEQ;
|
|
|
-
|
|
|
-CREATE OR REPLACE TRIGGER ACL_PERMISSION_ID
|
|
|
-BEFORE INSERT ON ACL_PERMISSION
|
|
|
-FOR EACH ROW
|
|
|
-BEGIN
|
|
|
- SELECT ACL_PERMISSION_SEQ.NEXTVAL INTO :new.id FROM dual;
|
|
|
-END;
|
|
|
-
|
|
|
-<bean id="basicAclExtendedDao" class="org.acegisecurity.acl.basic.jdbc.JdbcExtendedDaoImpl">
|
|
|
- <property name="dataSource">
|
|
|
- <ref bean="dataSource"/>
|
|
|
- </property>
|
|
|
- <property name="objectPropertiesQuery" value="${acegi.objectPropertiesQuery}"/>
|
|
|
-</bean>
|
|
|
-
|
|
|
-<prop key="acegi.objectPropertiesQuery">SELECT CHILD.ID, CHILD.OBJECT_IDENTITY, CHILD.ACL_CLASS, PARENT.OBJECT_IDENTITY as PARENT_OBJECT_IDENTITY FROM acl_object_identity as CHILD LEFT OUTER JOIN acl_object_identity as PARENT ON CHILD.parent_object=PARENT.id WHERE CHILD.object_identity = ?</prop> </programlisting></para>
|
|
|
-
|
|
|
- <para>The <literal>JdbcDaoImpl</literal> will only respond to requests
|
|
|
- for <literal>NamedEntityObjectIdentity</literal>s. It converts such
|
|
|
- identities into a single <literal>String</literal>, comprising
|
|
|
- the<literal> NamedEntityObjectIdentity.getClassname()</literal> +
|
|
|
- <literal>":"</literal> +
|
|
|
- <literal>NamedEntityObjectIdentity.getId()</literal>. This yields the
|
|
|
- type of <literal>object_identity</literal> values shown above. As
|
|
|
- indicated by the sample data, each database row corresponds to a
|
|
|
- single <literal>BasicAclEntry</literal>. As stated earlier and
|
|
|
- demonstrated by <literal>corp.DomainObject:2</literal> in the above
|
|
|
- sample data, each domain object instance will often have multiple
|
|
|
- <literal>BasicAclEntry</literal>[]s.</para>
|
|
|
-
|
|
|
- <para>As <literal>JdbcDaoImpl</literal> is required to return concrete
|
|
|
- <literal>BasicAclEntry</literal> classes, it needs to know which
|
|
|
- <literal>BasicAclEntry</literal> implementation it is to create and
|
|
|
- populate. This is the role of the <literal>acl_class</literal> column.
|
|
|
- <literal>JdbcDaoImpl</literal> will create the indicated class and set
|
|
|
- its <literal>mask</literal>, <literal>recipient</literal>,
|
|
|
- <literal>aclObjectIdentity</literal> and
|
|
|
- <literal>aclObjectParentIdentity</literal> properties.</para>
|
|
|
-
|
|
|
- <para>As you can probably tell from the sample data, the
|
|
|
- <literal>parent_object_identity</literal> value can either be null or
|
|
|
- in the same format as the <literal>object_identity</literal>. If
|
|
|
- non-null, <literal>JdbcDaoImpl</literal> will create a
|
|
|
- <literal>NamedEntityObjectIdentity</literal> to place inside the
|
|
|
- returned <literal>BasicAclEntry</literal> class.</para>
|
|
|
-
|
|
|
- <para>Returning to the <literal>BasicAclProvider</literal>, before it
|
|
|
- can poll the <literal>BasicAclDao</literal> implementation it needs to
|
|
|
- convert the domain object instance it was passed into an
|
|
|
- <literal>AclObjectIdentity</literal>.
|
|
|
- <literal>BasicAclProvider</literal> has a <literal>protected
|
|
|
- AclObjectIdentity obtainIdentity(Object domainInstance)</literal>
|
|
|
- method that is responsible for this. As a protected method, it enables
|
|
|
- subclasses to easily override. The normal implementation checks
|
|
|
- whether the passed domain object instance implements the
|
|
|
- <literal>AclObjectIdentityAware</literal> interface, which is merely a
|
|
|
- getter for an <literal>AclObjectIdentity</literal>. If the domain
|
|
|
- object does implement this interface, that is the identity returned.
|
|
|
- If the domain object does not implement this interface, the method
|
|
|
- will attempt to create an <literal>AclObjectIdentity</literal> by
|
|
|
- passing the domain object instance to the constructor of a class
|
|
|
- defined by the
|
|
|
- <literal>BasicAclProvider.getDefaultAclObjectIdentity()</literal>
|
|
|
- method. By default the defined class is
|
|
|
- <literal>NamedEntityObjectIdentity</literal>, which was described in
|
|
|
- more detail above. Therefore, you will need to either (i) provide a
|
|
|
- <literal>getId()</literal> method on your domain objects, (ii)
|
|
|
- implement <literal>AclObjectIdentityAware</literal> on your domain
|
|
|
- objects, (iii) provide an alternative
|
|
|
- <literal>AclObjectIdentity</literal> implementation that will accept
|
|
|
- your domain object in its constructor, or (iv) override the
|
|
|
- <literal>obtainIdentity(Object)</literal> method.</para>
|
|
|
-
|
|
|
- <para>Once the <literal>AclObjectIdentity</literal> of the domain
|
|
|
- object instance is determined, the <literal>BasicAclProvider</literal>
|
|
|
- will poll the DAO to obtain its <literal>BasicAclEntry</literal>[]s.
|
|
|
- If any of the entries returned by the DAO indicate there is a parent,
|
|
|
- that parent will be polled, and the process will repeat until there is
|
|
|
- no further parent. The permissions assigned to a
|
|
|
- <literal>recipient</literal> closest to the domain object instance
|
|
|
- will always take priority and override any inherited permissions. From
|
|
|
- the sample data above, the following inherited permissions would
|
|
|
- apply:</para>
|
|
|
-
|
|
|
- <para><programlisting>--- Mask integer 0 = no permissions
|
|
|
---- Mask integer 1 = administer
|
|
|
---- Mask integer 2 = read
|
|
|
---- Mask integer 6 = read and write permissions
|
|
|
---- Mask integer 14 = read and write and create permissions
|
|
|
-
|
|
|
----------------------------------------------------------------------
|
|
|
---- *** INHERITED RIGHTS FOR DIFFERENT INSTANCES AND RECIPIENTS ***
|
|
|
---- INSTANCE RECIPIENT PERMISSION(S) (COMMENT #INSTANCE)
|
|
|
----------------------------------------------------------------------
|
|
|
---- 1 ROLE_SUPERVISOR Administer
|
|
|
---- 2 ROLE_SUPERVISOR None (overrides parent #1)
|
|
|
---- marissa Read
|
|
|
---- 3 ROLE_SUPERVISOR Administer (from parent #1)
|
|
|
---- scott Read, Write, Create
|
|
|
---- 4 ROLE_SUPERVISOR Administer (from parent #1)
|
|
|
---- 5 ROLE_SUPERVISOR Administer (from parent #3)
|
|
|
---- scott Read, Write, Create (from parent #3)
|
|
|
---- 6 ROLE_SUPERVISOR Administer (from parent #3)
|
|
|
---- scott Administer (overrides parent #3)</programlisting></para>
|
|
|
-
|
|
|
- <para>So the above explains how a domain object instance has its
|
|
|
- <literal>AclObjectIdentity</literal> discovered, and the
|
|
|
- <literal>BasicAclDao</literal> will be polled successively until an
|
|
|
- array of inherited permissions is constructed for the domain object
|
|
|
- instance. The final step is to determine the
|
|
|
- <literal>BasicAclEntry</literal>[]s that are actually applicable to a
|
|
|
- given <literal>Authentication</literal> object.</para>
|
|
|
-
|
|
|
- <para>As you would recall, the <literal>AclManager</literal> (and all
|
|
|
- delegates, up to and including <literal>BasicAclProvider</literal>)
|
|
|
- provides a method which returns only those
|
|
|
- <literal>BasicAclEntry</literal>[]s applying to a passed
|
|
|
- <literal>Authentication</literal> object.
|
|
|
- <literal>BasicAclProvider</literal> delivers this functionality by
|
|
|
- delegating the filtering operation to an
|
|
|
- <literal>EffectiveAclsResolver</literal> implementation. The default
|
|
|
- implementation,
|
|
|
- <literal>GrantedAuthorityEffectiveAclsResolver</literal>, will iterate
|
|
|
- through the <literal>BasicAclEntry</literal>[]s and include only those
|
|
|
- where the <literal>recipient</literal> is equal to either the
|
|
|
- <literal>Authentication</literal>'s <literal>principal</literal> or
|
|
|
- any of the <literal>Authentication</literal>'s
|
|
|
- <literal>GrantedAuthority</literal>[]s. Please refer to the JavaDocs
|
|
|
- for more information.</para>
|
|
|
-
|
|
|
- <mediaobject>
|
|
|
- <imageobject role="html">
|
|
|
- <imagedata align="center" fileref="images/Permissions.gif"
|
|
|
- format="GIF" />
|
|
|
- </imageobject>
|
|
|
-
|
|
|
- <caption>
|
|
|
- <para>Figure 8: ACL Instantiation Approach</para>
|
|
|
- </caption>
|
|
|
- </mediaobject>
|
|
|
-
|
|
|
- <para>The above figure explains the key relationships between objects
|
|
|
- in the Basic ACL package.</para>
|
|
|
- </section>
|
|
|
- </chapter>
|
|
|
- </part>
|
|
|
-
|
|
|
- <part id="resources">
|
|
|
- <title>Other Resources</title>
|
|
|
-
|
|
|
- <partintro>
|
|
|
- <para>In addition to this reference guide, a number of other resources
|
|
|
- exist to help you learn how to use Acegi Security. These resources are
|
|
|
- discussed in this section.</para>
|
|
|
- </partintro>
|
|
|
-
|
|
|
- <chapter id="sample-apps">
|
|
|
- <title id="samples">Sample Applications</title>
|
|
|
-
|
|
|
- <sect1 id="contacts-sample">
|
|
|
- <title id="contacts">Contacts</title>
|
|
|
-
|
|
|
- <para>Included with Acegi Security is a very simple application that
|
|
|
- can demonstrate the basic security facilities provided by the system
|
|
|
- (and confirm your Container Adapter is properly configured if you're
|
|
|
- using one).</para>
|
|
|
-
|
|
|
- <para>If you build from Subversion, the Contacts sample application
|
|
|
- includes three deployable versions:
|
|
|
- <literal>acegi-security-sample-contacts-filter.war</literal> is
|
|
|
- configured with the HTTP Session Authentication approach.
|
|
|
- Acegi<literal><literal>-security-sample-contacts-ca.war</literal></literal>
|
|
|
- is configured to use a Container Adapter. Finally,
|
|
|
- <literal>acegi-security-sample-contacts-cas.war</literal> is designed
|
|
|
- to work with a JA-SIG CAS server. If you're just wanting to see how
|
|
|
- the sample application works, please use
|
|
|
- <literal><literal>acegi-security-sample-contacts-filter.war</literal></literal>
|
|
|
- as it does not require special configuration of your container. This
|
|
|
- is also the artifact included in official release ZIPs.</para>
|
|
|
-
|
|
|
- <para>To deploy, simply copy the relevant WAR file from Acegi Security
|
|
|
- distribution into your container’s <literal>webapps</literal>
|
|
|
- directory.</para>
|
|
|
-
|
|
|
- <para>After starting your container, check the application can load.
|
|
|
- Visit
|
|
|
- <literal>http://localhost:</literal><literal><literal>8080/</literal>acegi-security-sample-contacts-filter</literal>
|
|
|
- (or whichever URL is appropriate for your web container and the WAR
|
|
|
- you deployed). A random contact should be displayed. Click "Refresh"
|
|
|
- several times and you will see different contacts. The business method
|
|
|
- that provides this random contact is not secured.</para>
|
|
|
-
|
|
|
- <para>Next, click "Debug". You will be prompted to authenticate, and a
|
|
|
- series of usernames and passwords are suggested on that page. Simply
|
|
|
- authenticate with any of these and view the resulting page. It should
|
|
|
- contain a success message similar to the following:</para>
|
|
|
-
|
|
|
- <blockquote>
|
|
|
- <para>Context on SecurityContextHolder is of type:
|
|
|
- org.acegisecurity.context.SecurityContextImpl</para>
|
|
|
-
|
|
|
- <para>The Context implements SecurityContext.</para>
|
|
|
-
|
|
|
- <para>Authentication object is of type:
|
|
|
- org.acegisecurity.adapters.PrincipalAcegiUserToken</para>
|
|
|
-
|
|
|
- <para>Authentication object as a String:
|
|
|
- org.acegisecurity.adapters.PrincipalAcegiUserToken@e9a7c2: Username:
|
|
|
- marissa; Password: [PROTECTED]; Authenticated: true; Granted
|
|
|
- Authorities: ROLE_TELLER, ROLE_SUPERVISOR</para>
|
|
|
-
|
|
|
- <para>Authentication object holds the following granted
|
|
|
- authorities:</para>
|
|
|
-
|
|
|
- <para>ROLE_TELLER (getAuthority(): ROLE_TELLER)</para>
|
|
|
-
|
|
|
- <para>ROLE_SUPERVISOR (getAuthority(): ROLE_SUPERVISOR)</para>
|
|
|
-
|
|
|
- <para>SUCCESS! Your [container adapter|web filter] appears to be
|
|
|
- properly configured!</para>
|
|
|
- </blockquote>
|
|
|
-
|
|
|
- <para>If you receive a different message, and deployed
|
|
|
- <literal>acegi-security-sample-contacts-ca.war</literal>, check you
|
|
|
- have properly configured your Container Adapter as described elsewhere
|
|
|
- in this reference guide.</para>
|
|
|
-
|
|
|
- <para>Once you successfully receive the above message, return to the
|
|
|
- sample application's home page and click "Manage". You can then try
|
|
|
- out the application. Notice that only the contacts available to the
|
|
|
- currently logged on user are displayed, and only users with
|
|
|
- <literal>ROLE_SUPERVISOR</literal> are granted access to delete their
|
|
|
- contacts. Behind the scenes, the
|
|
|
- <literal>MethodSecurityInterceptor</literal> is securing the business
|
|
|
- objects. If you're using
|
|
|
- <literal><literal>acegi-security-sample-contacts-filter.war</literal></literal>
|
|
|
- or <literal>acegi-security-sample-contacts-cas.war</literal>, the
|
|
|
- <literal>FilterSecurityInterceptor</literal> is also securing the HTTP
|
|
|
- requests. If using either of these WARs, be sure to try visiting
|
|
|
- <literal>http://localhost:8080/contacts/secure/super</literal>, which
|
|
|
- will demonstrate access being denied by the
|
|
|
- <literal>FilterSecurityInterceptor</literal>. Note the sample
|
|
|
- application enables you to modify the access control lists associated
|
|
|
- with different contacts. Be sure to give this a try and understand how
|
|
|
- it works by reviewing the sample application's application context XML
|
|
|
- files.</para>
|
|
|
-
|
|
|
- <para>The Contacts sample application also include a
|
|
|
- <literal>client</literal> directory. Inside you will find a small
|
|
|
- application that queries the backend business objects using several
|
|
|
- web services protocols. This demonstrates how to use Acegi Security
|
|
|
- for authentication with Spring remoting protocols. To try this client,
|
|
|
- ensure your servlet container is still running the Contacts sample
|
|
|
- application, and then execute <literal>client marissa koala</literal>.
|
|
|
- The command-line parameters respectively represent the username to
|
|
|
- use, and the password to use. Note that you may need to edit
|
|
|
- <literal>client.properties</literal> to use a different target
|
|
|
- URL.</para>
|
|
|
-
|
|
|
- <para>Please note the sample application's <literal>client</literal>
|
|
|
- does not currently support CAS. You can still give it a try, though,
|
|
|
- if you're ambitious: try <literal>client _cas_stateless_
|
|
|
- YOUR-SERVICE-TICKET-ID</literal>.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="tutorial-sample">
|
|
|
- <title>Tutorial Sample</title>
|
|
|
-
|
|
|
- <para>Whilst the <link linkend="contacts-sample">Contacts
|
|
|
- Sample</link> is quite advanced in that it illustrates the more
|
|
|
- powerful features of domain object access control lists and so on,
|
|
|
- sometimes you just want to start with a nice basic example. The
|
|
|
- tutorial sample is intended to provide this for you.</para>
|
|
|
-
|
|
|
- <para>The compiled tutorial is included in the distribution ZIP file,
|
|
|
- ready to be deployed into your web container. Authentication is
|
|
|
- handled by the <link
|
|
|
- linkend="dao-provider">DaoAuthenticationProvider</link>, using the
|
|
|
- <link linkend="in-memory-service">in-memory</link>
|
|
|
- <literal>UserDetailsService</literal> that sources information from
|
|
|
- the <literal>users.properties</literal> file located in the WAR's
|
|
|
- <literal>/WEB-INF</literal> directory. The <link
|
|
|
- linkend="form">form-based</link> authentication mechanism is used,
|
|
|
- with the commonly-used <link linkend="remember-me">remember-me</link>
|
|
|
- authentication provider used to automatically remember the login using
|
|
|
- cookies.</para>
|
|
|
-
|
|
|
- <para>In terms of authorization, to keep things simple we've
|
|
|
- configured the tutorial to only perform some basic <link
|
|
|
- linkend="filter-invocation-authorization">web filter
|
|
|
- authorization</link>. We've wired two common <link
|
|
|
- linkend="pre-invocation">pre-invocation access decision voters</link>,
|
|
|
- being the <literal>RoleVoter</literal> and
|
|
|
- <literal>AuthenticatedVoter</literal>, such that
|
|
|
- <literal>ROLE_*</literal> configuration attributes and
|
|
|
- <literal>IS_AUTHENTICATED_*</literal> configuration attributes may be
|
|
|
- used. Of course, it's extremely easy to add in other providers, with
|
|
|
- most users probably starting with some services-layer security using
|
|
|
- <link linkend="aop-alliance">MethodSecurityInterceptor</link>.</para>
|
|
|
-
|
|
|
- <para>We recommend you start with the tutorial sample, as the XML is
|
|
|
- minimal and easy to follow. All of the needed <link
|
|
|
- linkend="filters">filters</link> are configured properly, and using
|
|
|
- best practise. Most importantly, you can easily this one XML file (and
|
|
|
- its corresponding <literal>web.xml</literal> entries) to your existing
|
|
|
- application. Only when this basic integration is achieved do we
|
|
|
- suggest you attempt adding in method authorization or domain object
|
|
|
- security.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
-
|
|
|
- <chapter id="community">
|
|
|
- <title>Community Support</title>
|
|
|
-
|
|
|
- <sect1 id="jira">
|
|
|
- <title>Use JIRA for Issue Tracking</title>
|
|
|
-
|
|
|
- <para>Acegi Security uses JIRA to manage bug reports and enhancement
|
|
|
- requests. If you find a bug, please log a report using JIRA. Do not
|
|
|
- log it on the support forum, mailing list or by emailing the project's
|
|
|
- developers. Such approaches are ad-hoc and we prefer to manage bugs
|
|
|
- using a more formal process.</para>
|
|
|
-
|
|
|
- <para>If possible, in your JIRA report please provide a JUnit test
|
|
|
- that demonstrates any incorrect behaviour. Or, better yet, provide a
|
|
|
- patch that corrects the issue. Similarly, enhancements are welcome to
|
|
|
- be logged in JIRA, although we only accept commit enhancement requests
|
|
|
- if you include corresponding unit tests. This is necessary to ensure
|
|
|
- project test coverage is adequately maintained.</para>
|
|
|
-
|
|
|
- <para>You can access JIRA at <ulink
|
|
|
- url="http://opensource.atlassian.com/projects/spring/secure/BrowseProject.jspa?id=10040"></ulink>.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="becoming-involved">
|
|
|
- <title>Becoming Involved</title>
|
|
|
-
|
|
|
- <para>We welcome you to become involved in Acegi Security project.
|
|
|
- There are many ways of contributing, including reading the mailing
|
|
|
- list and responding to questions from other people, writing new code,
|
|
|
- improving existing code, assisting with documentation, developing
|
|
|
- samples or tutorials, or simply making suggestions.</para>
|
|
|
-
|
|
|
- <para>Please read our project policies web page that is available on
|
|
|
- Acegi Security home page. This explains the path to become a
|
|
|
- committer, and the administration approaches we use within the
|
|
|
- project.</para>
|
|
|
- </sect1>
|
|
|
-
|
|
|
- <sect1 id="further-info">
|
|
|
- <title>Further Information</title>
|
|
|
-
|
|
|
- <para>Questions and comments on Acegi Security are welcome. Please use
|
|
|
- the Spring Community Forum web site at <ulink
|
|
|
- url="http://forum.springframework.org"></ulink> for all support
|
|
|
- issues. Remember to use JIRA for bug reports, as explained above.
|
|
|
- Everyone is also welcome to join the Acegisecurity-developer mailing
|
|
|
- list and participate in design discussions. It's also a good way of
|
|
|
- finding out what's happening with regard to release timing, and the
|
|
|
- traffic volume is quite light. Finally, our project home page (where
|
|
|
- you can obtain the latest release of the project and convenient links
|
|
|
- to Subversion, JIRA, mailing lists, forums etc) is at <ulink
|
|
|
- url="http://acegisecurity.org"></ulink>.</para>
|
|
|
- </sect1>
|
|
|
- </chapter>
|
|
|
- </part>
|
|
|
-</book>
|
Luke Taylor
