From 0d1ebfa85a0ecd772743515695395b74679b47db Mon Sep 17 00:00:00 2001 From: Luke Taylor Date: Wed, 6 May 2009 14:34:27 +0000 Subject: [PATCH] Updated contacts sample info and added information on ACL database schema and using it with Postgres. --- src/docbkx/appendix-db-schema.xml | 153 ++++++++++----- src/docbkx/samples.xml | 180 +++++++----------- src/docbkx/springsecurity.xml | 307 +++++++++++------------------- 3 files changed, 295 insertions(+), 345 deletions(-) diff --git a/src/docbkx/appendix-db-schema.xml b/src/docbkx/appendix-db-schema.xml index 6a19d4880a..da381000ee 100644 --- a/src/docbkx/appendix-db-schema.xml +++ b/src/docbkx/appendix-db-schema.xml @@ -1,27 +1,20 @@ - + xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> Security Database Schema - - There are various database schema used by the framework and this appendix - provides a single reference point to them all. You only need to - provide the tables for the areas of functonality you require. - - - DDL statements are given for the HSQLDB database. You can use these as a guideline for defining the - schema for the database you are using. - - + There are various database schema used by the framework and this appendix provides a single + reference point to them all. You only need to provide the tables for the areas of functonality + you require. + DDL statements are given for the HSQLDB database. You can use these as a guideline for + defining the schema for the database you are using.
User Schema - - The standard JDBC implementation of the UserDetailsService requires tables - to load the password, account status (enabled or disabled) and a list of authorities (roles) for the user. - + The standard JDBC implementation of the UserDetailsService + requires tables to load the password, account status (enabled or disabled) and a list of + authorities (roles) for the user. + create table users( username varchar_ignorecase(50) not null primary key, password varchar_ignorecase(50) not null, @@ -32,13 +25,10 @@ authority varchar_ignorecase(50) not null, constraint fk_authorities_users foreign key(username) references users(username)); create unique index ix_auth_username on authorities (username,authority);; - - - +
Group Authorities - - Spring Security 2.0 introduced support for group authorities + Spring Security 2.0 introduced support for group authorities create table groups ( id bigint generated by default as identity(start with 0) primary key, @@ -54,33 +44,56 @@ create table group_members ( username varchar(50) not null, group_id bigint not null, constraint fk_group_members_group foreign key(group_id) references groups(id)); - - +
-
Persistent Login (Remember-Me) Schema - - This table is used to store data used by the more secure - persistent token remember-me implementation. - If you are using JdbcTokenRepositoryImpl either directly or through the namespace, - then you will need this table. - + This table is used to store data used by the more secure persistent token remember-me + implementation. If you are using JdbcTokenRepositoryImpl either + directly or through the namespace, then you will need this table. + create table persistent_logins ( username varchar(64) not null, series varchar(64) primary key, token varchar(64) not null, last_used timestamp not null); - - +
- -
+
ACL Schema - - The tables used by the Spring Security ACL implementation. - + There are four tables used by the Spring Security ACL implementation. + + acl_sid stores the security identities recognised by the ACL + system. These can be unique principals or authorities which may apply to multiple + principals. + + + acl_class defines the domain object types to which ACLs apply. + The class column stores the Java class name of the object. + + + acl_object_identity stores the object identity definitions of + specific domai objects. + + + acl_entry stores the ACL permissions which apply to a specific + object identity and security identity. + + + It is assumed that the database will auto-generate the primary keys for each of the + identities. The JdbcMutableAclService has to be able to retrieve these when + it has created a new row in the acl_sid or acl_class + tables. It has two properties which define the SQL needed to retrieve these values + classIdentityQuery and sidIdentityQuery. Both of these + default to call identity() +
+ Hypersonic SQL + The default schema works with the embedded HSQLDB database that is used in unit tests + within the + framework. create table acl_sid ( id bigint generated by default as identity(start with 100) not null primary key, principal boolean not null, @@ -112,12 +125,60 @@ create table acl_entry ( constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), constraint foreign_fk_5 foreign key(sid) references acl_sid(id) ); - - - - + +
+ PostgreSQL + + create table acl_sid( + id bigserial not null primary key, + principal boolean not null, + sid varchar(100) not null, + constraint unique_uk_1 unique(sid,principal)); + +create table acl_class( + id bigserial not null primary key, + class varchar(100) not null, + constraint unique_uk_2 unique(class)); + +create table acl_object_identity( + id bigserial primary key, + object_id_class bigint not null, + object_id_identity bigint not null, + parent_object bigint, + owner_sid bigint, + entries_inheriting boolean not null, + constraint unique_uk_3 unique(object_id_class,object_id_identity), + constraint foreign_fk_1 foreign key(parent_object)references acl_object_identity(id), + constraint foreign_fk_2 foreign key(object_id_class)references acl_class(id), + constraint foreign_fk_3 foreign key(owner_sid)references acl_sid(id)); + +create table acl_entry( + id bigserial primary key, + acl_object_identity bigint not null, + ace_order int not null, + sid bigint not null, + mask integer not null, + granting boolean not null, + audit_success boolean not null, + audit_failure boolean not null, + constraint unique_uk_4 unique(acl_object_identity,ace_order), + constraint foreign_fk_4 foreign key(acl_object_identity) references acl_object_identity(id), + constraint foreign_fk_5 foreign key(sid) references acl_sid(id)); + + + You will have to set the classIdentityQuery and + sidIdentityQuery properties of + JdbcMutableAclService to the following values, respectively: + + select currval(pg_get_serial_sequence('acl_class', + 'id')) + + + select currval(pg_get_serial_sequence('acl_sid', + 'id')) + + +
+
- - - - \ No newline at end of file + diff --git a/src/docbkx/samples.xml b/src/docbkx/samples.xml index 20baa64aac..f96b3cdd39 100644 --- a/src/docbkx/samples.xml +++ b/src/docbkx/samples.xml @@ -1,70 +1,50 @@ - - - - Sample Applications - - - There are several sample web applications that are available with the - project. To avoid an overly large download, only the "tutorial" - and "contacts" samples are included in the distribution zip file. You can - either build the others yourself, or you can obtain the war files - individually from the central Maven repository. We'd recommend the former. - You can get the source as described in the introduction - and it's easy to build the project using Maven. There is more information - on the project web site at - - http://www.springframework.org/spring-security/ - if you need it. - All paths referred to in this chapter are relative to the source directory, once - you have checked it out from subversion. - + + + Sample Applications + + There are several sample web applications that are available with the project. To avoid + an overly large download, only the "tutorial" and "contacts" samples are included in the + distribution zip file. You can either build the others yourself, or you can obtain the war + files individually from the central Maven repository. We'd recommend the former. You can get + the source as described in the introduction and it's + easy to build the project using Maven. There is more information on the project web site at + + http://www.springframework.org/spring-security/ if you need it. All paths + referred to in this chapter are relative to the source directory, once you have checked it + out from subversion.
- Tutorial Sample - - The tutorial sample is a nice basic example to get you started. It uses - simple namespace configuration throughout. The compiled application is included in the - distribution zip file, ready to be deployed into your web container - (spring-security-samples-tutorial-2.0.x.war). - The form-based - authentication mechanism is used in combination with the commonly-used - remember-me - authentication provider to automatically remember the login using - cookies. - - We recommend you start with the tutorial sample, as the XML is - minimal and easy to follow. Most importantly, you can easily add - this one XML file (and its corresponding web.xml 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. + Tutorial Sample + The tutorial sample is a nice basic example to get you started. It uses simple + namespace configuration throughout. The compiled application is included in the + distribution zip file, ready to be deployed into your web container + (spring-security-samples-tutorial-3.0.x.war). The form-based authentication mechanism is used in combination + with the commonly-used remember-me authentication + provider to automatically remember the login using cookies. + We recommend you start with the tutorial sample, as the XML is minimal and easy to + follow. Most importantly, you can easily add this one XML file (and its corresponding + web.xml 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.
-
- Contacts - - - The Contacts Sample is quite an advanced example in that it - illustrates the more powerful features of domain object access control lists - in addition to basic application security. - - - To deploy, simply copy the WAR file from Spring - Security distribution into your container’s webapps - directory. The war should be called spring-security-samples-contacts-2.0.0.war - (the appended version number will vary depending on what release you are using). - - - After starting your container, check the application can load. - Visit - http://localhost:8080/contacts - (or whichever URL is appropriate for your web container and the WAR - you deployed). - - 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: - + Contacts + The Contacts Sample is an advanced example in that it illustrates the more powerful + features of domain object access control lists (ACLs) in addition to basic application + security. The application provides an interface with which the users are able to + administer a simple database of contacts (the domain objects). + To deploy, simply copy the WAR file from Spring Security distribution into your + container’s webapps directory. The war should be called + spring-security-samples-contacts-3.0.x.war (the appended + version number will vary depending on what release you are using). + After starting your container, check the application can load. Visit + http://localhost:8080/contacts (or whichever URL is appropriate + for your web container and the WAR you deployed). + 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: + Authentication object is of type: org.springframework.security.providers.UsernamePasswordAuthenticationToken Authentication object as a String: @@ -83,21 +63,17 @@ ROLE_USER (getAuthority(): ROLE_USER) SUCCESS! Your web filters appear to be properly configured! - - - - 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 - ROLE_SUPERVISOR are granted access to delete their - contacts. Behind the scenes, the - MethodSecurityInterceptor is securing the business - objects. - The application allows 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 application context XML files. - - +-->
-
LDAP Sample - - The LDAP sample application provides a basic configuration and sets up both a namespace configuration - and an equivalent configuration using traditional beans, both in the same application context file. - This means there are actually two identical authentication providers configured in this application. - + The LDAP sample application provides a basic configuration and sets up both a + namespace configuration and an equivalent configuration using traditional beans, both in + the same application context file. This means there are actually two identical + authentication providers configured in this application.
-
CAS Sample - - The CAS sample requires that you run both a CAS server and CAS client. It isn't included in the distribution so you should check out - the project code as described in the introduction. You'll find the relevant files under the - sample/cas directory. There's also a Readme.txt file in there which explains how to run - both the server and the client directly from the source tree, complete with SSL support. You have to download the CAS Server web application - (a war file) from the CAS site and drop it into the samples/cas/server directory. - + The CAS sample requires that you run both a CAS server and CAS client. It isn't + included in the distribution so you should check out the project code as described in + the introduction. You'll find the relevant + files under the sample/cas directory. There's also a + Readme.txt file in there which explains how to run both the + server and the client directly from the source tree, complete with SSL support. You have + to download the CAS Server web application (a war file) from the CAS site and drop it + into the samples/cas/server directory.
-
Pre-Authentication Sample - - This sample application demonstrates how to wire up beans from the pre-authentication - framework to make use of login information from a J2EE container. The user name and roles are those setup by the container. - - - The code is in samples/preauth . - + This sample application demonstrates how to wire up beans from the pre-authentication framework to make use of login + information from a J2EE container. The user name and roles are those setup by the + container. + The code is in samples/preauth .
- - - \ No newline at end of file + diff --git a/src/docbkx/springsecurity.xml b/src/docbkx/springsecurity.xml index d18eb205c0..29496b0b75 100644 --- a/src/docbkx/springsecurity.xml +++ b/src/docbkx/springsecurity.xml @@ -1,229 +1,150 @@ - - - Spring Security - - Reference Documentation - - - Ben Alex, Luke Taylor - - - 2.0.x - - - + xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"> + Spring SecurityReference Documentation + Ben Alex, Luke Taylor + + 2.0.x + - Preface - - Spring 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. - - 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. Spring Security makes this latter - area - application security - much easier. - - - 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. - - With Spring 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. - - - Please read , in - its entirety to begin with. This will introduce you to the framework and the namespace-based - configuration system with which you can get up and running quite quickly. To get more of an understanding - of an in-depth understaning of how Spring Security works, and some of the classes you might - need to use, you should then read . - The remaining parts of this guide are structured in a more traditional reference style, - designed to be read on an as-required basis. We'd also recommend that you read up as much as - possible on application security issues in general. Spring Security is not a panacea which will - solve all security issues. It is important that the application is designed with security in - mind from the start. Attempting to retrofit it is not a good idea. - In particular, if you are building a web application, you should be aware of the many potential - vulnerabilities such as cross-site scripting, request-forgery and session-hijacking which you should - be taking into account from the start. The OWASP web site (http://www.owasp.org/) maintains a - top ten list of web application vulnerabilities as well as a lot of useful reference information. - - - We hope that you find this reference guide useful, and we welcome - your feedback and suggestions. - - - Finally, welcome to the Spring Security community. + Spring 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. + 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. Spring Security makes this latter + area - application security - much easier. + 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. + With Spring 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. + Please read , in its entirety to begin with. This will + introduce you to the framework and the namespace-based configuration system with which you can + get up and running quite quickly. To get more of an understanding of an in-depth understaning + of how Spring Security works, and some of the classes you might need to use, you should then + read . The remaining parts of this guide are structured + in a more traditional reference style, designed to be read on an as-required basis. We'd also + recommend that you read up as much as possible on application security issues in general. + Spring Security is not a panacea which will solve all security issues. It is important that + the application is designed with security in mind from the start. Attempting to retrofit it is + not a good idea. In particular, if you are building a web application, you should be aware of + the many potential vulnerabilities such as cross-site scripting, request-forgery and + session-hijacking which you should be taking into account from the start. The OWASP web site + (http://www.owasp.org/) maintains a top ten list of web application vulnerabilities as well as + a lot of useful reference information. + We hope that you find this reference guide useful, and we welcome your feedback and suggestions. + Finally, welcome to the Spring Security community. - Getting Started - The later parts of this guide provide an in-depth discussion of the - framework architecture and implementation classes, an understanding of which is important - if you need to do any serious customization. In this part, we'll introduce Spring Security 2.0, - give a brief overview of the project's history and take a slightly - gentler look at how to get started using the framework. - In particular, we'll look at namespace configuration which provides a much simpler way of securing - your application compared to the traditional Spring bean approach where you had to wire up all the - implementation classes individually. - - - We'll also take a look at the sample applications that are available. It's worth trying to run - these and experimenting with them a bit even before you read the later sections - you can dip back into them - as your understanding of the framework increases. - + The later parts of this guide provide an in-depth discussion of the framework + architecture and implementation classes, an understanding of which is important if you need + to do any serious customization. In this part, we'll introduce Spring Security 2.0, give a + brief overview of the project's history and take a slightly gentler look at how to get + started using the framework. In particular, we'll look at namespace configuration which + provides a much simpler way of securing your application compared to the traditional Spring + bean approach where you had to wire up all the implementation classes individually. + We'll also take a look at the sample applications that are available. It's worth trying + to run these and experimenting with them a bit even before you read the later sections - you + can dip back into them as your understanding of the framework increases. - - - - - + + - - - + - Overall Architecture - - Like most software, Spring 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 Spring Security, before examining these central elements that - are necessary to successfully planning and executing a Spring Security - integration. + Like most software, Spring 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 Spring Security, before examining these central elements + that are necessary to successfully planning and executing a Spring Security + integration. - - - - - - - + + + - Authentication - - We've already introduced Spring Security's authentication architecture - in the Technical Overview chapter. - In this part of the reference guide we will examine individual - authentication mechanisms and their corresponding - AuthenticationProviders. We'll also look at how to - configure authentication more generally, including if you have several - authentication approaches that need to be chained together. - - With some exceptions, we will be discussing the full details of Spring Security - bean configuration rather than the shorthand - namespace syntax. You should review - the introduction to using namespace configuration and the options it provides - to see if they will meet your needs. As you come to use the framework more, - and need to customize the internal behaviour, you will probably want to understand - more about how the individual services are implemented, which classes to look at - extending and so on. This part is more targeted at providing this kind of information. - We'd recommend that you supplement the content by browsing the Javadoc and the source - itself Links to both Javadoc APIs and browsable source cross-reference - are available from the project web site.. - + We've already introduced Spring Security's authentication architecture in the Technical Overview chapter. In this part of the + reference guide we will examine individual authentication mechanisms and their corresponding + AuthenticationProviders. We'll also look at how to configure + authentication more generally, including if you have several authentication approaches that + need to be chained together. + With some exceptions, we will be discussing the full details of Spring Security bean + configuration rather than the shorthand namespace + syntax. You should review the introduction to using namespace configuration and the + options it provides to see if they will meet your needs. As you come to use the framework + more, and need to customize the internal behaviour, you will probably want to understand + more about how the individual services are implemented, which classes to look at extending + and so on. This part is more targeted at providing this kind of information. We'd recommend + that you supplement the content by browsing the Javadoc and the source itself + Links to both Javadoc APIs and browsable source cross-reference are available from + the project web site. + . - - - - - + + - - - - - - - - - - - - - - - + + + + + + + - - - - + - Authorization - - The advanced authorization capabilities within Spring Security - represent one of the most compelling reasons for its popularity. - Irrespective of how you choose to authenticate - whether using a Spring - Security-provided mechanism and provider, or integrating with a - container or other non-Spring Security authentication authority - you - will find the authorization services can be used within your application - in a consistent and simple way. - + The advanced authorization capabilities within Spring Security represent one of the most + compelling reasons for its popularity. Irrespective of how you choose to authenticate - + whether using a Spring Security-provided mechanism and provider, or integrating with a + container or other non-Spring Security authentication authority - you will find the + authorization services can be used within your application in a consistent and simple + way. In this part we'll explore the different - AbstractSecurityInterceptor 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. + AbstractSecurityInterceptor 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. - - - + - - - - - - \ No newline at end of file +