SEC-910: More updates to namespace appendix
This commit is contained in:
Luke Taylor
parent
ecd63cabda
commit
ff13df03ac
|
|
@ -8,13 +8,14 @@
|
||||||
</info>
|
</info>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This provides a reference to the elements available in the security namespace and information on
|
This appendix provides a reference to the elements available in the security namespace and information on
|
||||||
the underlying beans they create (a knowledge of the individual classes and how they work together is assumed -
|
the underlying beans they create (a knowledge of the individual classes and how they work together is assumed -
|
||||||
you can find more information in the project Javadoc and elsewhere in this document).
|
you can find more information in the project Javadoc and elsewhere in this document).
|
||||||
If you haven't used the namespace before, please read the
|
If you haven't used the namespace before, please read the
|
||||||
<link xlink:href="#ns-config">introductory chapter</link>. Using a good quality XML editor while
|
<link xlink:href="#ns-config">introductory chapter</link> on namespace configuration,
|
||||||
editing a configuration based on the schema is recommended as this will provide contextual information on
|
as this is intended as a supplement to the information there. Using a good quality XML editor while editing a
|
||||||
which elements and attributes are available and comments explaining their purpose.
|
configuration based on the schema is recommended as this will provide contextual information on which elements
|
||||||
|
and attributes are available as well as comments explaining their purpose.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<section xml:id="nsa-http">
|
<section xml:id="nsa-http">
|
||||||
|
|
@ -31,6 +32,11 @@
|
||||||
filter chain explicitly in the<classname>FilterChainProxy</classname> bean. You can, of course, still do this
|
filter chain explicitly in the<classname>FilterChainProxy</classname> bean. You can, of course, still do this
|
||||||
if you need full control of the configuration.
|
if you need full control of the configuration.
|
||||||
</para>
|
</para>
|
||||||
|
<para>
|
||||||
|
All filters which require a reference to the <interfacename>AuthenticationManager</interfacename> will be automatically
|
||||||
|
injected with the internal instance created by the namespace configuration (see the
|
||||||
|
<link xlink:href="#ns-auth-manager"> introductory chapter</link> for more on the <interfacename>AuthenticationManager</interfacename>).
|
||||||
|
</para>
|
||||||
<para>
|
<para>
|
||||||
The <literal><http></literal> namespace block always creates an <classname>HttpSessionContextIntegrationFilter</classname>,
|
The <literal><http></literal> namespace block always creates an <classname>HttpSessionContextIntegrationFilter</classname>,
|
||||||
an <classname>ExceptionTranslationFilter</classname> and a <classname>FilterSecurityInterceptor</classname>. These are fixed
|
an <classname>ExceptionTranslationFilter</classname> and a <classname>FilterSecurityInterceptor</classname>. These are fixed
|
||||||
|
|
@ -111,7 +117,10 @@
|
||||||
<section xml:id="nsa-access-denied-page">
|
<section xml:id="nsa-access-denied-page">
|
||||||
<title><literal>access-denied-page</literal></title>
|
<title><literal>access-denied-page</literal></title>
|
||||||
<para>
|
<para>
|
||||||
Allows the access denied page to be set (the user will be redirected here if an AccessDeniedException is raised).
|
Allows the access denied page to be set (the user will be redirected here if an
|
||||||
|
<exceptionname>AccessDeniedException</exceptionname> is raised). Corresponds to the
|
||||||
|
<literal>errorPage</literal> property set on the <classname>AccessDeniedHandlerImpl</classname> which is
|
||||||
|
used by the <classname>ExceptionTranslationFilter</classname>.
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
@ -122,19 +131,225 @@
|
||||||
<classname>FilterSecurityInterceptor</classname>. Defaults to "true".
|
<classname>FilterSecurityInterceptor</classname>. Defaults to "true".
|
||||||
</para>
|
</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
<section>
|
<section>
|
||||||
<title>The <literal><intercept-url></literal> Element</title>
|
<title>The <literal><intercept-url></literal> Element</title>
|
||||||
<para></para>
|
<para>
|
||||||
|
This element is used to define the set of URL patterns that the application is interested in
|
||||||
|
and to configure how they should be handled. It is used to construct the
|
||||||
|
<interfacename>FilterInvocationDefinitionSource</interfacename> used by the <classname>FilterSecurityInterceptor</classname> and
|
||||||
|
to exclude particular patterns from the filter chain entirely (by setting the attribute <literal>filters="none"</literal>).
|
||||||
|
It is also responsible for configuring a <classname>ChannelProcessingFilter</classname> if particular URLs need to be accessed
|
||||||
|
by HTTPS, for example.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section xml:id="nsa-pattern">
|
||||||
|
<title><literal>pattern</literal></title>
|
||||||
|
<para>
|
||||||
|
The pattern which defines the URL path. The content will depend on the <literal>path-type</literal> attribute from the
|
||||||
|
containing http element, so will default to ant path syntax.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="nsa-method">
|
||||||
|
<title><literal>method</literal></title>
|
||||||
|
<para>
|
||||||
|
The HTTP Method which will be used in combination with the pattern to match an incoming request. If omitted, any method will match.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="nsa-access">
|
||||||
|
<title><literal>access</literal></title>
|
||||||
|
<para>
|
||||||
|
Lists the access attributes which will be stored in the <interfacename>FilterInvocationDefinitionSource</interfacename> for the defined
|
||||||
|
URL pattern/method combination. This should be a comma-separated list of the attributes (such as role names).
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
<section xml:id="nsa-requires-channel">
|
||||||
|
<title><literal>requires-channel</literal></title>
|
||||||
|
<para>
|
||||||
|
Can be "http" or "https" depending on whether a particular URL pattern should be accessed over HTTP or HTTPS respectively. Alternatively
|
||||||
|
the value "any" can be used when there is no preference. If this attribute is present on any <literal><intercept-url></literal>
|
||||||
|
element, then a <classname>ChannelProcessingFilter</classname> will be added to the filter stack and its additional dependencies added
|
||||||
|
to the application context. See the <link xlink:href="channel-security-config">chapter on channel security</link> for an
|
||||||
|
example configuration using traditional beans.
|
||||||
|
</para>
|
||||||
|
<para>
|
||||||
|
If a <literal><port-mappings></literal> configuration is added, this will be used to by the <classname>SecureChannelProcessor</classname>
|
||||||
|
and <classname>InsecureChannelProcessor</classname> beans to determine the ports used for redirecting to HTTP/HTTPS.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>The <literal><port-mappings></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
By default, an instance of <classname>PortMapperImpl</classname> will be added to the configuration for use in redirecting
|
||||||
|
to secure and insecure URLs. This element can optionally be used to override the default mappings which that class defines. Each
|
||||||
|
child <literal><port-mapping></literal> element defines a pair of HTTP:HTTPS ports. The default mappings are 80:443
|
||||||
|
and 8080:8443. An example of overriding these can be found in the <link xlink:href="#ns-requires-channel">namespace introduction</link>.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-form-login">
|
||||||
|
<title>The <literal><form-login></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
Used to add an <classname>AuthenticationProcessingFilter</classname> to the filter stack and an
|
||||||
|
<classname>AuthenticationProcessingFilterEntryPoint</classname> to the application context to provide authentication
|
||||||
|
on demand. This will always take precedence over other namespace-created entry points.
|
||||||
|
If no attributes are supplied, a login page will be generated automatically at the URL "/spring-security-login"
|
||||||
|
<footnote><para>This feature is really just provided for convenience and is not intended for production (where a
|
||||||
|
view technology will have been chosen and can be used to render a customized login page). The class
|
||||||
|
<classname>DefaultLoginPageGeneratingFilter</classname> is responsible for rendering the login
|
||||||
|
page and will provide login forms for both normal form login and/or OpenID if required.</para></footnote>
|
||||||
|
The behaviour can be customized using the following attributes.
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>login-page</literal></title>
|
||||||
|
<para>
|
||||||
|
The URL that should be used to render the login page. Maps to the <literal>loginFormUrl</literal>
|
||||||
|
property of the <classname>AuthenticationProcessingFilterEntryPoint</classname>. Defaults to
|
||||||
|
"/spring-security-login".
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>login-processing-url</literal></title>
|
||||||
|
<para>
|
||||||
|
Maps to the <literal>filterProcessesUrl</literal> property of <classname>AuthenticationProcessingFilter</classname>.
|
||||||
|
The default value is "/j_spring_security_check".
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>default-target-url</literal></title>
|
||||||
|
<para>Maps to the <literal>defaultTargetUrl</literal> property of <classname>AuthenticationProcessingFilter</classname>. If
|
||||||
|
not set, the default value is "/" (the application root). A user will be taken to this URL after logging in, provided they
|
||||||
|
were not asked to login while attempting to access a secured resource, when they will be taken to the originally requested URL.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>always-use-default-target</literal></title>
|
||||||
|
<para>
|
||||||
|
If set to "true", the user will always start at the value given by <literal>default-target-url</literal>, regardless of how
|
||||||
|
they arrived at the login page. Maps to the <literal>alwaysUseDefaultTargetUrl</literal> property of
|
||||||
|
<classname>AuthenticationProcessingFilter</classname>. Default value is "false".
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>authentication-failure-url</literal></title>
|
||||||
|
<para>
|
||||||
|
Maps to the <literal>authenticationFailureUrl</literal> property of <classname>AuthenticationProcessingFilter</classname>.
|
||||||
|
Defines the URL the browser will be redirected to on login failure. Defaults to "/spring_security_login?login_error", which will
|
||||||
|
be automatically handled by the automatic login page generator, re-rendering the login page with an error message.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-http-basic">
|
||||||
|
<title>The <literal><http-basic></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
Adds a <classname>BasicProcessingFilter</classname> and <classname>BasicProcessingFilterEntryPoint</classname> to the
|
||||||
|
configuration. The latter will only be used as the configuration entry point if form-based login is not enabled.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-remember-me">
|
||||||
|
<title>The <literal><remember-me></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
Adds the <classname>RememberMeProcessingFilter</classname> to the stack. This in turn will
|
||||||
|
be configured with either a <classname>TokenBasedRememberMeServices</classname>, a <classname>PersistentTokenBasedRememberMeServices</classname>
|
||||||
|
or a user-specified bean implementing <interfacename>RememberMeServices</interfacename> depending on the attribute settings.
|
||||||
|
</para>
|
||||||
|
<section>
|
||||||
|
<title><literal>data-source-ref</literal></title>
|
||||||
|
<para>
|
||||||
|
If this is set, <classname>PersistentTokenBasedRememberMeServices</classname> will be used and configured with
|
||||||
|
a <classname>JdbcTokenRepositoryImpl</classname> instance.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>token-repository-ref</literal></title>
|
||||||
|
<para>
|
||||||
|
Configures a <classname>PersistentTokenBasedRememberMeServices</classname> but allows the use of a custom
|
||||||
|
<interfacename>PersistentTokenRepository</interfacename> bean.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>services-ref</literal></title>
|
||||||
|
<para>
|
||||||
|
Allows complete control of the <interfacename>RememberMeServices</interfacename> implementation that will be used
|
||||||
|
by the filter. The value should be the Id of a bean in the application context which implements this interface.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>token-repository-ref</literal></title>
|
||||||
|
<para>
|
||||||
|
Configures a <classname>PersistentTokenBasedRememberMeServices</classname> but allows the use of a custom
|
||||||
|
<interfacename>PersistentTokenRepository</interfacename> bean.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title>The <literal>key</literal> Attribute</title>
|
||||||
|
<para>Maps to the "key" property of <classname>AbstractRememberMeServices</classname>. Should be set to a unique
|
||||||
|
value to ensure that remember-me cookies are only valid within the one application <footnote><para>This doesn't affect
|
||||||
|
the use of <classname>PersistentTokenBasedRememberMeServices</classname>, where the tokens are stored on the server side.</para></footnote>.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>token-validity-seconds</literal></title>
|
||||||
|
<para>
|
||||||
|
Maps to the <literal>tokenValiditySeconds</literal> property of <classname>AbstractRememberMeServices</classname>. Specifies the period
|
||||||
|
in seconds for which the remember-me cookie should be valid. By default it will be valid for 14 days.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<title><literal>user-service-ref</literal></title>
|
||||||
|
<para>
|
||||||
|
The remember-me services implementations require access to a <interfacename>UserDetailsService</interfacename>, so there has to be
|
||||||
|
one defined in the application context. If there is only one, it will be selected and used automatically by the namespace configuration.
|
||||||
|
If there are multiple instances, you can specify a bean Id explicitly using this attribute.
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-concurrent-session-control">
|
||||||
|
<title>The <literal><concurrent-session-control></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-anonymous">
|
||||||
|
<title>The <literal><anonymous></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-x509">
|
||||||
|
<title>The <literal><x509></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-openid-login">
|
||||||
|
<title>The <literal><openid-login></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section xml:id="nsa-logout">
|
||||||
|
<title>The <literal><logout></literal> Element</title>
|
||||||
|
<para>
|
||||||
|
</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue