diff --git a/doc/docbook/acegi.xml b/doc/docbook/acegi.xml index bd443d2fad..945940c31c 100644 --- a/doc/docbook/acegi.xml +++ b/doc/docbook/acegi.xml @@ -95,27 +95,23 @@ although equivalent functionality is fully accommodated by Acegi Security. - - Current Status + + Release Numbering - The Acegi Security System for Spring is widely used by members - of the Spring Community. The APIs are considered stable and only minor - changes are expected. Having said that, like many other projects we - need to strike a balance between backward compatibility and - improvement. Effective version 0.6.1, Acegi Security uses the Apache - Portable Runtime Project versioning guidelines, available from - http://apr.apache.org/versioning.html. + It is useful to understand how the 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 + http://apr.apache.org/versioning.html. We quote the + introduction contained on that page for your convenience: - We are now at release 0.9.0, and a lot of effort has been made - to implement all non-backward compatible changes either in or before - this release. Some minor improvements are currently intended to the - 1.0.0 release, although they will in no way modify the project's - central interfaces or classes. Users of Acegi Security System for - Spring should therefore be comfortable depending on the current - version of the project in their applications. Please note that we will - be changing the package name prefix in the 1.0.0 release, but this - should be a simple "find and replace" type operation in your - code. + 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. @@ -4070,8 +4066,6 @@ $CATALINA_HOME/bin/startup.sh 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 - - The X509ProcessingFilter extracts the certificate from the request and uses it as the credentials @@ -4080,8 +4074,6 @@ $CATALINA_HOME/bin/startup.sh The request is passed to the authentication manager. - - The X509AuthenticationProvider receives the token. Its main concern is to obtain the user @@ -4109,8 +4101,6 @@ $CATALINA_HOME/bin/startup.sh load the user information. - - If everything has gone smoothly then there should be a valid Authentication object in the secure @@ -4120,7 +4110,6 @@ $CATALINA_HOME/bin/startup.sh X509ProcessingFilterEntryPoint which returns a 403 error (forbidden) to the user. - @@ -4176,218 +4165,252 @@ $CATALINA_HOME/bin/startup.sh Overview - 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. - There are many different scenarios for how an LDAP server may be configured so the - 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. - 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: . 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. + + 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. + + There are many different scenarios for how an LDAP server may be + configured so the 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. + + 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: . 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. LDAP with Acegi Security - + The main LDAP provider class is - org.acegisecurity.providers.ldap.LdapAuthenticationProvider. This - bean doesn't actually do much itself other than implement the - retrieveUser method required by its base class, - AbstractUserDetailsAuthenticationProvider. It delegates the work - to two other beans, an LdapAuthenticator and an - LdapAuthoritiesPopulator which are responsible for - authenticating the user and retrieving the user's set of - GrantedAuthoritys respectively. - + org.acegisecurity.providers.ldap.LdapAuthenticationProvider. + This bean doesn't actually do much itself other than implement the + retrieveUser method required by its base + class, + AbstractUserDetailsAuthenticationProvider. It + delegates the work to two other beans, an + LdapAuthenticator and an + LdapAuthoritiesPopulator which are + responsible for authenticating the user and retrieving the user's + set of GrantedAuthoritys + respectively. - - + - LdapAuthenticator Implementations - 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. - There are currently two authentication strategies supplied with Acegi Security: - - - Authentication directly to the LDAP server ("bind" authentication). - - - 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. - - - - - Common Functionality - 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 - setUserDnPatterns array property) or by setting the - userSearch property. For the DN pattern-matching approach, a - standard Java pattern format is used, and the login name will be substituted for the - parameter {0}. The pattern should be relative to the DN that - the configured InitialDirContextFactory will bind to - (see the section on connecting to the - LDAP server for more information on this). For example, if you are using an - LDAP server specified by the URL - ldap://monkeymachine.co.uk/dc=acegisecurity,dc=org, and have a - pattern uid={0},ou=greatapes, then a login name of "gorilla" will - map to a DN uid=gorilla,ou=greatapes,dc=acegisecurity,dc=org. Each - configured DN pattern will be tried in turn until a match is found. For information on - using a search, see the section on search - objects 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. - - - BindAuthenticator - The class - org.acegisecurity.providers.ldap.authenticator.BindAuthenticator - implements the bind authentication strategy. It simply attempts to bind as the user. - - - - PasswordComparisonAuthenticator - The class - org.acegisecurity.providers.ldap.authenticator.PasswordComparisonAuthenticator - implements the password comparison authentication strategy. - - - Active Directory Authentication - In addition to standard LDAP authentication (binding with a DN), Active Directory - has its own non-standard syntax for user authentication. - - - + LdapAuthenticator Implementations + + 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. + + There are currently two authentication strategies supplied with + Acegi Security: + + Authentication directly to the LDAP server ("bind" + authentication). + + + + 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. + + + + + Common Functionality + + 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 + setUserDnPatterns array property) or by setting + the userSearch property. For the DN + pattern-matching approach, a standard Java pattern format is used, + and the login name will be substituted for the parameter + {0}. The pattern should be relative to the DN + that the configured + InitialDirContextFactory will bind to + (see the section on connecting to the LDAP + server for more information on this). For example, if you are + using an LDAP server specified by the URL + ldap://monkeymachine.co.uk/dc=acegisecurity,dc=org, + and have a pattern uid={0},ou=greatapes, then a + login name of "gorilla" will map to a DN + uid=gorilla,ou=greatapes,dc=acegisecurity,dc=org. + Each configured DN pattern will be tried in turn until a match is + found. For information on using a search, see the section on search objects 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. + + + + BindAuthenticator + + The class + org.acegisecurity.providers.ldap.authenticator.BindAuthenticator + implements the bind authentication strategy. It simply attempts to + bind as the user. + + + + PasswordComparisonAuthenticator + + The class + org.acegisecurity.providers.ldap.authenticator.PasswordComparisonAuthenticator + implements the password comparison authentication strategy. + + + + Active Directory Authentication + + In addition to standard LDAP authentication (binding with a + DN), Active Directory has its own non-standard syntax for user + authentication. + - + Connecting to the LDAP Server - The beans discussed above have to be able to connect to the server. They both have - to be supplied with an InitialDirContextFactory instance. - Unless you have special requirements, this will usually be a - DefaultInitialDirContextFactory 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. - DefaultInitialDirContextFactory 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 useConnectionPool - property to false. - - See the class Javadoc and source for more information on this bean and its properties. - - - + + The beans discussed above have to be able to connect to the + server. They both have to be supplied with an + InitialDirContextFactory instance. + Unless you have special requirements, this will usually be a + DefaultInitialDirContextFactory 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. + + DefaultInitialDirContextFactory 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 + useConnectionPool property to false. + + See the class + Javadoc and source for more information on this bean and its + properties. + + LDAP Search Objects - 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 - LdapUserSearch instance which can be supplied to the - authenticator implementations, for example, to allow them to locate a user. The supplied - implementation is FilterBasedLdapUserSearch. - - + + 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 LdapUserSearch + instance which can be supplied to the authenticator implementations, + for example, to allow them to locate a user. The supplied + implementation is + FilterBasedLdapUserSearch. + <classname>FilterBasedLdapUserSearch</classname> - 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 - JDK - DirContext class. - As explained there, the search filter can be supplied with parameters. For this class, - the only valid parameter is {0} which will be replaced with - the user's login name. - + + 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 JDK + DirContext class. As explained there, the search filter can + be supplied with parameters. For this class, the only valid + parameter is {0} which will be replaced with + the user's login name. - + Configuring the LDAP Provider - There is a version of the - Contacts Sample Application which - uses LDAP. You can copy the beans and filter setup from this as a starting - point for configuring your own application. - - - A typical configuration, using some of the beans we've discussed above, might look like this: - - <bean id="initialDirContextFactory" - class="org.acegisecurity.providers.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> + There is a version of the Contacts Sample Application which + uses LDAP. You can copy the beans and filter setup from this as a + starting point for configuring your own application. + + A typical configuration, using some of the beans we've discussed + above, might look like this: + <bean id="initialDirContextFactory" + class="org.acegisecurity.providers.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.providers.ldap.search.FilterBasedLdapUserSearch"> - <constructor-arg index="0"> + <bean id="userSearch" + class="org.acegisecurity.providers.ldap.search.FilterBasedLdapUserSearch"> + <constructor-arg index="0"> <value></value> </constructor-arg> - <constructor-arg index="1"> + <constructor-arg index="1"> <value>(uid={0})</value> </constructor-arg> - <constructor-arg index="2"> - <ref local="initialDirContextFactory" /> + <constructor-arg index="2"> + <ref local="initialDirContextFactory" /> </constructor-arg> - <property name="searchSubtree"> + <property name="searchSubtree"> <value>true</value> </property> </bean> - <bean id="ldapAuthProvider" - class="org.acegisecurity.providers.ldap.LdapAuthenticationProvider"> + <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 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> + <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> + <property name="groupRoleAttribute"><value>ou</value></property> </bean> </constructor-arg> </bean> - + This would set up the provider to access an LDAP + server with URL + ldap://monkeymachine:389/dc=acegisecurity,dc=org. + Authentication will be performed by attempting to bind with the DN + uid=<user-login-name>,ou=people,dc=acegisecurity,dc=org. + After successful authentication, roles will be assigned to the user by + searching under the DN + ou=groups,dc=acegisecurity,dc=org with the default + filter (member=<user's-DN>). The role name + will be taken from the ou attribute of each + match. - This would set up the provider to access an LDAP server with URL - ldap://monkeymachine:389/dc=acegisecurity,dc=org. Authentication will be performed by - attempting to bind with the DN uid=<user-login-name>,ou=people,dc=acegisecurity,dc=org. - After successful authentication, roles will be assigned to the user by searching under the DN - ou=groups,dc=acegisecurity,dc=org with the default filter (member=<user's-DN>). - The role name will be taken from the ou attribute of each match. - - - We've also included the configuration for a user search object, which uses the filter - (uid=<user-login-name>). This could be used - instead of the DN-pattern (or in addition to it), by setting the authenticator's - userSearch property. The autheticator would then call the search - object to obtain the correct user's DN before attempting to bind as this user. - + We've also included the configuration for a user search object, + which uses the filter + (uid=<user-login-name>). This could be used + instead of the DN-pattern (or in addition to it), by setting the + authenticator's userSearch property. The + autheticator would then call the search object to obtain the correct + user's DN before attempting to bind as this user. + - - Channel Security @@ -5394,12 +5417,12 @@ INSERT INTO acl_permission VALUES (null, 6, 'scott', 1); Further Information Questions and comments on the Acegi Security System for Spring are - welcome. Please use the Spring Community Forum web site at - . You're also welcome - to join the acegisecurity-developer mailing list. Our project home page + welcome. Please use the Spring Community Forum web site at . You're also welcome to + join the acegisecurity-developer mailing list. Our project home page (where you can obtain the latest release of the project and access to - CVS, mailing lists, forums etc) is at - . + CVS, mailing lists, forums etc) is at . \ No newline at end of file