Cwikius-Spring
/
spring-security
mirror of https://github.com/spring-projects/spring-security.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Fix xsd tests

This commit is contained in:
Rob Winch 2021-12-13 17:38:22 -06:00
parent 2fb056b5c1
commit 2471e3296d
6 changed files with 1027 additions and 981 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

194
docs/modules/ROOT/pages/servlet/appendix/namespace/authentication-manager.adoc
View File

@ -1,43 +1,42 @@
[[nsa-authentication]]
= Authentication Services
Before Spring Security 3.0, an `AuthenticationManager` was automatically registered internally.
Now you must register one explicitly by using the `<authentication-manager>` element.
Doing so creates an instance of Spring Security's `ProviderManager` class, which needs to be configured with a list of one or more `AuthenticationProvider` instances.
You can create these instances either by using syntax elements provided by the namespace or by using standard bean definitions, marked for addition to the list by using the `authentication-provider` element.
Now you must register one explicitly using the `<authentication-manager>` element.
This creates an instance of Spring Security's `ProviderManager` class, which needs to be configured with a list of one or more `AuthenticationProvider` instances.
These can either be created using syntax elements provided by the namespace, or they can be standard bean definitions, marked for addition to the list using the `authentication-provider` element.
[[nsa-authentication-manager]]
== <authentication-manager>
Every Spring Security application that uses the namespace must include the `<authentication-manager>` element somewhere.
It is responsible for registering the `AuthenticationManager`, which provides authentication services to the application.
All elements that create `AuthenticationProvider` instances should be children of this element.
Every Spring Security application which uses the namespace must have include this element somewhere.
It is responsible for registering the `AuthenticationManager` which provides authentication services to the application.
All elements which create `AuthenticationProvider` instances should be children of this element.
[[nsa-authentication-manager-attributes]]
=== <authentication-manager> Attributes
The `<authentication-manager>` element has the following attributes:
[[nsa-authentication-manager-alias]]
`alias`::
This attribute lets you define an alias name for the internal instance to use in your own configuration.
* **alias**
This attribute allows you to define an alias name for the internal instance for use in your own configuration.
[[nsa-authentication-manager-erase-credentials]]
`erase-credentials`::
If set to `true`, the `AuthenticationManager` tries to clear any credentials data in the returned `Authentication` object, once the user has been authenticated.
Literally, it maps to the `eraseCredentialsAfterAuthentication` property of the xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
* **erase-credentials**
If set to true, the AuthenticationManager will attempt to clear any credentials data in the returned Authentication object, once the user has been authenticated.
Literally it maps to the `eraseCredentialsAfterAuthentication` property of the xref:servlet/authentication/architecture.adoc#servlet-authentication-providermanager[`ProviderManager`].
[[nsa-authentication-manager-id]]
`id`::
This attribute lets you define an ID for the internal instance to use in your own configuration.
It is the same as the `alias` element but provides a more consistent experience with elements that use the `id` attribute.
* **id**
This attribute allows you to define an id for the internal instance for use in your own configuration.
It is the same as the alias element, but provides a more consistent experience with elements that use the id attribute.
[[nsa-authentication-manager-children]]
=== Child Elements of <authentication-manager>
The `<authentication-manager>` element has the following child elements:
* <<nsa-authentication-provider,authentication-provider>>
* xref:servlet/appendix/namespace/ldap.adoc#nsa-ldap-authentication-provider[ldap-authentication-provider]
@ -46,9 +45,9 @@ The `<authentication-manager>` element has the following child elements:
[[nsa-authentication-provider]]
== <authentication-provider>
Unless used with a `ref` attribute, the `<authentication-provider>` element is shorthand for configuring a `DaoAuthenticationProvider`.
A `DaoAuthenticationProvider` loads user information from a `UserDetailsService` and compares the username and password combination with the values supplied at login.
You can define the `UserDetailsService` instance either by using an available namespace element (`jdbc-user-service`) or by using the `user-service-ref` attribute to point to a bean defined elsewhere in the application context.
Unless used with a `ref` attribute, this element is shorthand for configuring a `DaoAuthenticationProvider`.
`DaoAuthenticationProvider` loads user information from a `UserDetailsService` and compares the username/password combination with the values supplied at login.
The `UserDetailsService` instance can be defined either by using an available namespace element (`jdbc-user-service` or by using the `user-service-ref` attribute to point to a bean defined elsewhere in the application context).
@ -56,43 +55,41 @@ You can define the `UserDetailsService` instance either by using an available na
=== Parent Elements of <authentication-provider>
The parent element of the `<authentication-provider>` element is the <<nsa-authentication-manager,authentication-manager>> element.
* <<nsa-authentication-manager,authentication-manager>>
[[nsa-authentication-provider-attributes]]
=== <authentication-provider> Attributes
The `<authentication-provider>` element has the following attributes:
[[nsa-authentication-provider-ref]]
ref::
* **ref**
Defines a reference to a Spring bean that implements `AuthenticationProvider`.
+
If you have written your own `AuthenticationProvider` implementation (or want to configure one of Spring Security's implementations as a traditional bean for some reason), you can use the following syntax to add it to the internal list of `ProviderManager`:
+
====
If you have written your own `AuthenticationProvider` implementation (or want to configure one of Spring Security's own implementations as a traditional bean for some reason, then you can use the following syntax to add it to the internal list of `ProviderManager`:
[source,xml]
----
<security:authentication-manager>
<security:authentication-provider ref="myAuthenticationProvider" />
</security:authentication-manager>
<bean id="myAuthenticationProvider" class="com.something.MyAuthenticationProvider"/>
----
====
[[nsa-authentication-provider-user-service-ref]]
`user-service-ref`::
A reference to a bean that implements `UserDetailsService`, which may be created by using the standard bean element or the custom user-service element.
* **user-service-ref**
A reference to a bean that implements UserDetailsService that may be created using the standard bean element or the custom user-service element.
[[nsa-authentication-provider-children]]
=== Child Elements of <authentication-provider>
The `<authentication-provider>` element has the following child elements:
* <<nsa-jdbc-user-service,jdbc-user-service>>
* xref:servlet/appendix/namespace/ldap.adoc#nsa-ldap-user-service[ldap-user-service]
@ -100,44 +97,47 @@ The `<authentication-provider>` element has the following child elements:
* <<nsa-user-service,user-service>>
[[nsa-jdbc-user-service]]
== <jdbc-user-service>
The `<jdbc-user-service>` element causes the creation of a JDBC-based `UserDetailsService`.
Causes creation of a JDBC-based UserDetailsService.
[[nsa-jdbc-user-service-attributes]]
=== <jdbc-user-service> Attributes
The `<jdbc-user-service>` element has the following attributes:
[[nsa-jdbc-user-service-authorities-by-username-query]]
`authorities-by-username-query`::
* **authorities-by-username-query**
An SQL statement to query for a user's granted authorities given a username.
+
The default is as follows:
====
The default is
[source]
----
select username, authority from authorities where username = ?
----
====
[[nsa-jdbc-user-service-cache-ref]]
`cache-ref`::
Defines a reference to a cache for use with a `UserDetailsService`.
* **cache-ref**
Defines a reference to a cache for use with a UserDetailsService.
[[nsa-jdbc-user-service-data-source-ref]]
`data-source-ref`::
The bean ID of the DataSource that provides the required tables.
* **data-source-ref**
The bean ID of the DataSource which provides the required tables.
[[nsa-jdbc-user-service-group-authorities-by-username-query]]
`group-authorities-by-username-query`::
An SQL statement to query user's group authorities, given a username.
The default is as follows:
* **group-authorities-by-username-query**
An SQL statement to query user's group authorities given a username.
The default is
+
====
[source]
----
select
@ -147,43 +147,45 @@ groups g, group_members gm, group_authorities ga
where
gm.username = ? and g.id = ga.group_id and g.id = gm.group_id
----
====
[[nsa-jdbc-user-service-id]]
`id`::
A bean identifier, which is used for referring to the bean elsewhere in the context.
* **id**
A bean identifier, used for referring to the bean elsewhere in the context.
[[nsa-jdbc-user-service-role-prefix]]
`role-prefix`::
A non-empty string prefix that is added to role strings loaded from persistent storage.
Default: `ROLE_`
Use a value of `none` for no prefix in cases where the default should be non-empty.
* **role-prefix**
A non-empty string prefix that will be added to role strings loaded from persistent storage (default is "ROLE_").
Use the value "none" for no prefix in cases where the default is non-empty.
[[nsa-jdbc-user-service-users-by-username-query]]
`users-by-username-query`::
An SQL statement to query a username, password, and enabled status, given a username.
The default is as follows:
* **users-by-username-query**
An SQL statement to query a username, password, and enabled status given a username.
The default is
+
====
[source]
----
select username, password, enabled from users where username = ?
----
====
[[nsa-password-encoder]]
== <password-encoder>
Injects a bean with the appropriate `PasswordEncoder` instance.
Authentication providers can optionally be configured to use a password encoder, as described in the xref:features/authentication/password-storage.adoc#authentication-password-storage[Password Storage].
Authentication providers can optionally be configured to use a password encoder as described in the xref:features/authentication/password-storage.adoc#authentication-password-storage[Password Storage].
This will result in the bean being injected with the appropriate `PasswordEncoder` instance.
[[nsa-password-encoder-parents]]
=== Parent Elements of <password-encoder>
The `<password-encoder>` element has the following parent elements:
* <<nsa-authentication-provider,authentication-provider>>
* xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-password-compare[password-compare]
@ -193,94 +195,98 @@ The `<password-encoder>` element has the following parent elements:
[[nsa-password-encoder-attributes]]
=== <password-encoder> Attributes
The `<password-encoder>` element has the following attributes:
[[nsa-password-encoder-hash]]
`hash`::
Defines the hashing algorithm for user passwords.
[IMPORTANT]
====
* **hash**
Defines the hashing algorithm used on user passwords.
We recommend strongly against using MD4, as it is a very weak hashing algorithm.
====
[[nsa-password-encoder-ref]]
`ref`::
* **ref**
Defines a reference to a Spring bean that implements `PasswordEncoder`.
[[nsa-user-service]]
== <user-service>
The `<user-service>` element creates an in-memory `UserDetailsService` from a properties file or a list of `<user>` child elements.
Usernames are converted to lower case internally, to allow for case-insensitive lookups, so do not use this element if you need case-sensitivity.
Creates an in-memory UserDetailsService from a properties file or a list of "user" child elements.
Usernames are converted to lower-case internally to allow for case-insensitive lookups, so this should not be used if case-sensitivity is required.
[[nsa-user-service-attributes]]
=== <user-service> Attributes
The `<user-service>` element has the following attributes:
[[nsa-user-service-id]]
`id`::
A bean identifier, used to refer to the bean elsewhere in the context.
* **id**
A bean identifier, used for referring to the bean elsewhere in the context.
[[nsa-user-service-properties]]
`properties`::
The location of a properties file, in which each line is in the format of
* **properties**
The location of a Properties file where each line is in the format of
+
====
[source]
----
username=password,grantedAuthority[,grantedAuthority][,enabled|disabled]
----
====
[[nsa-user-service-children]]
=== Child Elements of <user-service>
The `<user-service>` element has a single child element: <<nsa-user,user>>.
Multiple `<user>` elements can be present.
* <<nsa-user,user>>
[[nsa-user]]
== <user>
The `<user>` represents a user in the application.
Represents a user in the application.
[[nsa-user-parents]]
=== Parent Elements of <user>
The parent element of the `<user>` element is the <<nsa-user-service,user-service>> element.
* <<nsa-user-service,user-service>>
[[nsa-user-attributes]]
=== <user> Attributes
[[nsa-user-authorities]]
`authorities`::
One of more authorities to be granted to the user.
Separate authorities with a comma (but no space) -- for example, `ROLE_USER,ROLE_ADMINISTRATOR`.
* **authorities**
One of more authorities granted to the user.
Separate authorities with a comma (but no space).
For example, "ROLE_USER,ROLE_ADMINISTRATOR"
[[nsa-user-disabled]]
`disabled`::
Set to `true` to mark an account as disabled and unusable.
* **disabled**
Can be set to "true" to mark an account as disabled and unusable.
[[nsa-user-locked]]
`locked`::
Set to `true` to mark an account as locked and unusable.
* **locked**
Can be set to "true" to mark an account as locked and unusable.
[[nsa-user-name]]
`name`::
* **name**
The username assigned to the user.
[[nsa-user-password]]
`password`::
This value may be hashed if the corresponding authentication provider supports hashing (remember to set the `hash` attribute of the `user-service` element).
You can omit this attribute when the data is not used for authentication but only for accessing authorities.
If omitted, the namespace generates a random value, preventing its accidental use for authentication.
This attribute cannot be empty.
* **password**
The password assigned to the user.
This may be hashed if the corresponding authentication provider supports hashing (remember to set the "hash" attribute of the "user-service" element).
This attribute be omitted in the case where the data will not be used for authentication, but only for accessing authorities.
If omitted, the namespace will generate a random value, preventing its accidental use for authentication.
Cannot be empty.

1329
docs/modules/ROOT/pages/servlet/appendix/namespace/http.adoc
View File

File diff suppressed because it is too large Load Diff

10
docs/modules/ROOT/pages/servlet/appendix/namespace/index.adoc
View File

@ -2,8 +2,8 @@
= The Security Namespace
:page-section-summary-toc: 1
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 -- you can find more information in the project Javadoc and elsewhere in this document).
If you have not used the namespace before, please read the xref:servlet/configuration/xml-namespace.adoc#ns-config[introductory chapter] on namespace configuration, as this appendix is intended as a supplement to the information there.
We recommend using a good XML editor while editing a configuration based on the schema is recommended, as doing so provides contextual information on which elements and attributes are available as well as comments explaining their purpose.
The namespace is written in https://relaxng.org/[RELAX NG] Compact format and then converted into an XSD schema.
If you are familiar with this format, you may wish to examine the https://raw.githubusercontent.com/spring-projects/spring-security/main/config/src/main/resources/org/springframework/security/config/spring-security-5.7.rnc[schema file] directly.
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 - 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 xref:servlet/configuration/xml-namespace.adoc#ns-config[introductory chapter] on namespace configuration, as this is intended as a supplement to the information there.
Using a good quality XML editor while editing a 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.
The namespace is written in https://relaxng.org/[RELAX NG] Compact format and later converted into an XSD schema.
If you are familiar with this format, you may wish to examine the https://raw.githubusercontent.com/spring-projects/spring-security/main/config/src/main/resources/org/springframework/security/config/spring-security-5.6.rnc[schema file] directly.

223
docs/modules/ROOT/pages/servlet/appendix/namespace/ldap.adoc
View File

@ -1,282 +1,291 @@
[[nsa-ldap]]
= LDAP Namespace Options
LDAP is covered in some detail in xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[its own chapter].
We expand on that here with some explanation of how the namespace options map to Spring beans.
LDAP is covered in some details in xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[its own chapter].
We will expand on that here with some explanation of how the namespace options map to Spring beans.
The LDAP implementation uses Spring LDAP extensively, so some familiarity with that project's API may be useful.
[[nsa-ldap-server]]
== Defining the LDAP Server using the
The `<ldap-server>` element sets up a Spring LDAP `ContextSource` for use by the other LDAP beans, defining the location of the LDAP server and other information (such as a username and password, if it does not allow anonymous access) for connecting to it.
You can also use it to create an embedded server for testing.
`<ldap-server>` Element
This element sets up a Spring LDAP `ContextSource` for use by the other LDAP beans, defining the location of the LDAP server and other information (such as a username and password, if it doesn't allow anonymous access) for connecting to it.
It can also be used to create an embedded server for testing.
Details of the syntax for both options are covered in the xref:servlet/authentication/passwords/ldap.adoc#servlet-authentication-ldap[LDAP chapter].
The actual `ContextSource` implementation is `DefaultSpringSecurityContextSource`, which extends Spring LDAP's `LdapContextSource` class.
The actual `ContextSource` implementation is `DefaultSpringSecurityContextSource` which extends Spring LDAP's `LdapContextSource` class.
The `manager-dn` and `manager-password` attributes map to the latter's `userDn` and `password` properties respectively.
If you have only one server defined in your application context, the other LDAP namespace-defined beans use it automatically.
Otherwise, you can give the element an `id` attribute and refer to it from other namespace beans by using the `server-ref` attribute.
If you only have one server defined in your application context, the other LDAP namespace-defined beans will use it automatically.
Otherwise, you can give the element an "id" attribute and refer to it from other namespace beans using the `server-ref` attribute.
This is actually the bean `id` of the `ContextSource` instance, if you want to use it in other traditional Spring beans.
[[nsa-ldap-server-attributes]]
=== <ldap-server> Attributes
The `<ldap-server>` element has the following attributes:
[[nsa-ldap-server-mode]]
`mode`::
Explicitly specifies which embedded LDAP server to use. Valid values are `apacheds` and `unboundid`. By default, it depends on whether the library is available in the classpath.
* **mode**
Explicitly specifies which embedded ldap server should use. Values are `apacheds` and `unboundid`. By default, it will depends if the library is available in the classpath.
[[nsa-ldap-server-id]]
`id`::
* **id**
A bean identifier, used for referring to the bean elsewhere in the context.
[[nsa-ldap-server-ldif]]
`ldif`::
* **ldif**
Explicitly specifies an ldif file resource to load into an embedded LDAP server.
The ldif file should be a Spring resource pattern (such as `classpath:init.ldif`).
Default: `classpath*:*.ldif`
The ldif should be a Spring resource pattern (i.e. classpath:init.ldif).
The default is classpath*:*.ldif
[[nsa-ldap-server-manager-dn]]
`manager-dn`::
Username (DN) of the "`manager`" user identity, which is used to authenticate to a (non-embedded) LDAP server.
If omitted, anonymous access is used.
* **manager-dn**
Username (DN) of the "manager" user identity which will be used to authenticate to a (non-embedded) LDAP server.
If omitted, anonymous access will be used.
[[nsa-ldap-server-manager-password]]
`manager-password`::
* **manager-password**
The password for the manager DN.
This is required if the `manager-dn` is specified.
This is required if the manager-dn is specified.
[[nsa-ldap-server-port]]
`port`::
* **port**
Specifies an IP port number.
You can use use it to configure an embedded LDAP server, for example.
The default value is `33389`.
Used to configure an embedded LDAP server, for example.
The default value is 33389.
[[nsa-ldap-server-root]]
`root`::
* **root**
Optional root suffix for the embedded LDAP server.
Default: `dc=springframework,dc=org`
Default is "dc=springframework,dc=org"
[[nsa-ldap-server-url]]
`url`::
Specifies the LDAP server URL when not using the embedded LDAP server.
* **url**
Specifies the ldap server URL when not using the embedded LDAP server.
[[nsa-ldap-authentication-provider]]
== <ldap-authentication-provider>
This element is shorthand for the creation of an `LdapAuthenticationProvider` instance.
By default, this is configured with a `BindAuthenticator` instance and a `DefaultAuthoritiesPopulator`.
By default this will be configured with a `BindAuthenticator` instance and a `DefaultAuthoritiesPopulator`.
As with all namespace authentication providers, it must be included as a child of the `authentication-provider` element.
[[nsa-ldap-authentication-provider-parents]]
=== Parent Elements of <ldap-authentication-provider>
The parent element of the `<ldap-authentication-provider>` is the xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-authentication-manager[authentication-manager]
* xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-authentication-manager[authentication-manager]
[[nsa-ldap-authentication-provider-attributes]]
=== <ldap-authentication-provider> Attributes
The `<ldap-authentication-provider>` element has the following attributes:
[[nsa-ldap-authentication-provider-group-role-attribute]]
`group-role-attribute`::
The LDAP attribute name, which contains the role name that is used within Spring Security.
Maps to the `groupRoleAttribute` property of the `DefaultLdapAuthoritiesPopulator`.
Default: `cn`
* **group-role-attribute**
The LDAP attribute name which contains the role name which will be used within Spring Security.
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `groupRoleAttribute` property.
Defaults to "cn".
[[nsa-ldap-authentication-provider-group-search-base]]
`group-search-base`::
* **group-search-base**
Search base for group membership searches.
Maps to the `groupSearchBase` constructor argument of `DefaultLdapAuthoritiesPopulator`.
Default: `""` (searching from the root)
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `groupSearchBase` constructor argument.
Defaults to "" (searching from the root).
[[nsa-ldap-authentication-provider-group-search-filter]]
`group-search-filter`::
* **group-search-filter**
Group search filter.
Maps to the `groupSearchFilter` property of `DefaultLdapAuthoritiesPopulator`.
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `groupSearchFilter` property.
Defaults to `+(uniqueMember={0})+`.
The substituted parameter is the DN of the user.
Default: `+(uniqueMember={0})+`
[[nsa-ldap-authentication-provider-role-prefix]]
`role-prefix`::
A non-empty string prefix that is added to role strings loaded from persistent storage.
Maps to the `rolePrefix` property of `DefaultLdapAuthoritiesPopulator`.
Use a value of `none` for no prefix in cases where the default is non-empty.
Default: `ROLE_`
* **role-prefix**
A non-empty string prefix that will be added to role strings loaded from persistent.
Maps to the ``DefaultLdapAuthoritiesPopulator``'s `rolePrefix` property.
Defaults to "ROLE_".
Use the value "none" for no prefix in cases where the default is non-empty.
[[nsa-ldap-authentication-provider-server-ref]]
`server-ref`::
* **server-ref**
The optional server to use.
If omitted, and a default LDAP server is registered (by using `<ldap-server>` with no ID), that server is used.
If omitted, and a default LDAP server is registered (using <ldap-server> with no Id), that server will be used.
[[nsa-ldap-authentication-provider-user-context-mapper-ref]]
`user-context-mapper-ref`::
Allows explicit customization of the loaded user object by specifying a `UserDetailsContextMapper` bean, which is called with the context information from the user's directory entry.
* **user-context-mapper-ref**
Allows explicit customization of the loaded user object by specifying a UserDetailsContextMapper bean which will be called with the context information from the user's directory entry
[[nsa-ldap-authentication-provider-user-details-class]]
`user-details-class`::
Lets the `objectClass` of the user entry be specified.
If set, the framework tries to load standard attributes for the defined class into the returned `UserDetails` object
* **user-details-class**
Allows the objectClass of the user entry to be specified.
If set, the framework will attempt to load standard attributes for the defined class into the returned UserDetails object
[[nsa-ldap-authentication-provider-user-dn-pattern]]
user-dn-pattern::
If your users are at a fixed location in the directory (that is, you can work out the DN directly from the username without doing a directory search), you can use this attribute to map directly to the DN.
* **user-dn-pattern**
If your users are at a fixed location in the directory (i.e. you can work out the DN directly from the username without doing a directory search), you can use this attribute to map directly to the DN.
It maps directly to the `userDnPatterns` property of `AbstractLdapAuthenticator`.
The value is a specific pattern used to build the user's DN -- for example, `+uid={0},ou=people+`.
The `+{0}+` key must be present and is substituted with the username.
The value is a specific pattern used to build the user's DN, for example `+uid={0},ou=people+`.
The key `+{0}+` must be present and will be substituted with the username.
[[nsa-ldap-authentication-provider-user-search-base]]
`user-search-base`::
* **user-search-base**
Search base for user searches.
Only used with a `user-search-filter`.
Default `""`
Defaults to "".
Only used with a 'user-search-filter'.
+
If you need to perform a search to locate the user in the directory, you can set these attributes to control the search.
The `BindAuthenticator` is configured with a `FilterBasedLdapUserSearch`, and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes are not set and no `user-dn-pattern` has been supplied as an alternative, the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` are used.
If you need to perform a search to locate the user in the directory, then you can set these attributes to control the search.
The `BindAuthenticator` will be configured with a `FilterBasedLdapUserSearch` and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` will be used.
[[nsa-ldap-authentication-provider-user-search-filter]]
`user-search-filter`::
The LDAP filter used to search for users (optional) -- for example, `+(uid={0})+`.
* **user-search-filter**
The LDAP filter used to search for users (optional).
For example `+(uid={0})+`.
The substituted parameter is the user's login name.
+
If you need to perform a search to locate the user in the directory, you can set these attributes to control the search.
The `BindAuthenticator` is configured with a `FilterBasedLdapUserSearch`, and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes are not set and no `user-dn-pattern` has been supplied as an alternative, the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` is used.
If you need to perform a search to locate the user in the directory, then you can set these attributes to control the search.
The `BindAuthenticator` will be configured with a `FilterBasedLdapUserSearch` and the attribute values map directly to the first two arguments of that bean's constructor.
If these attributes aren't set and no `user-dn-pattern` has been supplied as an alternative, then the default search values of `+user-search-filter="(uid={0})"+` and `user-search-base=""` will be used.
[[nsa-ldap-authentication-provider-children]]
=== Child Elements of <ldap-authentication-provider>
The `<ldap-authentication-provider>` has a single child element: <<nsa-password-compare,password-compare>>.
* <<nsa-password-compare,password-compare>>
[[nsa-password-compare]]
== <password-compare>
The `<password-compare>` element is used as a child element to `<ldap-provider>` and switches the authentication strategy from `BindAuthenticator` to `PasswordComparisonAuthenticator`.
This is used as child element to `<ldap-provider>` and switches the authentication strategy from `BindAuthenticator` to `PasswordComparisonAuthenticator`.
[[nsa-password-compare-parents]]
=== Parent Elements of <password-compare>
The parent element of the `<password-compare>` element is the <<nsa-ldap-authentication-provider,ldap-authentication-provider>> element.
* <<nsa-ldap-authentication-provider,ldap-authentication-provider>>
[[nsa-password-compare-attributes]]
=== <password-compare> Attributes
The `<password-compare>` has the following attributes:
[[nsa-password-compare-hash]]
`hash`::
* **hash**
Defines the hashing algorithm used on user passwords.
We recommend strongly against using MD4, as it is a very weak hashing algorithm.
[[nsa-password-compare-password-attribute]]
`password-attribute`::
The attribute in the directory that contains the user password.
Default: `userPassword`
* **password-attribute**
The attribute in the directory which contains the user password.
Defaults to "userPassword".
[[nsa-password-compare-children]]
=== Child Elements of <password-compare>
The `<password-compare>` element has a single child element: xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-password-encoder[password-encoder]
* xref:servlet/appendix/namespace/authentication-manager.adoc#nsa-password-encoder[password-encoder]
[[nsa-ldap-user-service]]
== <ldap-user-service>
The `<ldap-user-service>` element configures an LDAP `UserDetailsService`.
It uses `LdapUserDetailsService`, which is a combination of a `FilterBasedLdapUserSearch` and a `DefaultLdapAuthoritiesPopulator`.
The attributes it supports have the same usage as `<ldap-provider>`.
This element configures an LDAP `UserDetailsService`.
The class used is `LdapUserDetailsService` which is a combination of a `FilterBasedLdapUserSearch` and a `DefaultLdapAuthoritiesPopulator`.
The attributes it supports have the same usage as in `<ldap-provider>`.
[[nsa-ldap-user-service-attributes]]
=== <ldap-user-service> Attributes
The `<ldap-user-service>` element has the following attributes:
[[nsa-ldap-user-service-cache-ref]]
`cache-ref`::
Defines a reference to a cache for use with a `UserDetailsService`.
* **cache-ref**
Defines a reference to a cache for use with a UserDetailsService.
[[nsa-ldap-user-service-group-role-attribute]]
`group-role-attribute`::
The LDAP attribute name that contains the role name to be used within Spring Security.
Default: `cn`
* **group-role-attribute**
The LDAP attribute name which contains the role name which will be used within Spring Security.
Defaults to "cn".
[[nsa-ldap-user-service-group-search-base]]
`group-search-base`::
* **group-search-base**
Search base for group membership searches.
Default: `""` (searching from the root)
Defaults to "" (searching from the root).
[[nsa-ldap-user-service-group-search-filter]]
`group-search-filter`::
* **group-search-filter**
Group search filter.
Defaults to `+(uniqueMember={0})+`.
The substituted parameter is the DN of the user.
Default: `+(uniqueMember={0})+`
[[nsa-ldap-user-service-id]]
`id`::
* **id**
A bean identifier, used for referring to the bean elsewhere in the context.
[[nsa-ldap-user-service-role-prefix]]
`role-prefix`::
A non-empty string prefix that is added to role strings loaded from persistent storage (for example,
`ROLE_`).
Use a value of `none` for no prefix in cases where the default is non-empty.
* **role-prefix**
A non-empty string prefix that will be added to role strings loaded from persistent storage (e.g.
"ROLE_").
Use the value "none" for no prefix in cases where the default is non-empty.
[[nsa-ldap-user-service-server-ref]]
`server-ref`::
* **server-ref**
The optional server to use.
If omitted and a default LDAP server is registered (by using `<ldap-server>` with no ID), that server is used.
If omitted, and a default LDAP server is registered (using <ldap-server> with no Id), that server will be used.
[[nsa-ldap-user-service-user-context-mapper-ref]]
`user-context-mapper-ref`::
Allows explicit customization of the loaded user object by specifying a `UserDetailsContextMapper` bean, which is called with the context information from the user's directory entry.
* **user-context-mapper-ref**
Allows explicit customization of the loaded user object by specifying a UserDetailsContextMapper bean which will be called with the context information from the user's directory entry
[[nsa-ldap-user-service-user-details-class]]
`user-details-class`::
Lets the `objectClass` of the user entry be specified.
If set, the framework tries to load standard attributes for the defined class into the returned `UserDetails` object.
* **user-details-class**
Allows the objectClass of the user entry to be specified.
If set, the framework will attempt to load standard attributes for the defined class into the returned UserDetails object
[[nsa-ldap-user-service-user-search-base]]
`user-search-base`::
* **user-search-base**
Search base for user searches.
It is used only with a <<nsa-ldap-user-service-user-search-filter,user-search-filter>> element.
Default: `""`
Defaults to "".
Only used with a 'user-search-filter'.
[[nsa-ldap-user-service-user-search-filter]]
`user-search-filter`::
The LDAP filter used to search for users (optional) -- for example, `+(uid={0})+`.
* **user-search-filter**
The LDAP filter used to search for users (optional).
For example `+(uid={0})+`.
The substituted parameter is the user's login name.

189
docs/modules/ROOT/pages/servlet/appendix/namespace/method-security.adoc
View File

@ -35,81 +35,77 @@ Defaults to "false".
[[nsa-global-method-security]]
== <global-method-security>
The `<global-method-security>` element is the primary means of adding support for securing methods on Spring Security beans.
You can secure methods by using annotations (defined at the interface or class level) or by defining a set of pointcuts as child elements with AspectJ syntax.
This element is the primary means of adding support for securing methods on Spring Security beans.
Methods can be secured by the use of annotations (defined at the interface or class level) or by defining a set of pointcuts as child elements, using AspectJ syntax.
[[nsa-global-method-security-attributes]]
=== <global-method-security> Attributes
The `<global-method-security>` element has the following attributes:
[[nsa-global-method-security-access-decision-manager-ref]]
`access-decision-manager-ref`::
Method security uses the same `AccessDecisionManager` configuration as web security, but using this attribute can override this arrangement.
By default, an `AffirmativeBased` implementation is used with a `RoleVoter` and an `AuthenticatedVoter`.
* **access-decision-manager-ref**
Method security uses the same `AccessDecisionManager` configuration as web security, but this can be overridden using this attribute.
By default an AffirmativeBased implementation is used for with a RoleVoter and an AuthenticatedVoter.
[[nsa-global-method-security-authentication-manager-ref]]
`authentication-manager-ref`::
A reference to the `AuthenticationManager` that should be used for method security.
* **authentication-manager-ref**
A reference to an `AuthenticationManager` that should be used for method security.
[[nsa-global-method-security-jsr250-annotations]]
`jsr250-annotations`::
Specifies whether JSR-250 style attributes are to be used (for example, `RolesAllowed`).
Doing so requires the `javax.annotation.security` classes to be on the classpath.
Setting this to `true` also adds a `Jsr250Voter` to the `AccessDecisionManager`, so you need to make sure that you do so if you use a custom implementation and want to use these annotations.
* **jsr250-annotations**
Specifies whether JSR-250 style attributes are to be used (for example "RolesAllowed").
This will require the javax.annotation.security classes on the classpath.
Setting this to true also adds a `Jsr250Voter` to the `AccessDecisionManager`, so you need to make sure you do this if you are using a custom implementation and want to use these annotations.
[[nsa-global-method-security-metadata-source-ref]]
`metadata-source-ref`::
You can supply an external `MethodSecurityMetadataSource` instance, which will take priority over other sources (such as the default annotations).
* **metadata-source-ref**
An external `MethodSecurityMetadataSource` instance can be supplied which will take priority over other sources (such as the default annotations).
[[nsa-global-method-security-mode]]
`mode`::
You can set this attribute to `aspectj` to specify that AspectJ should be used instead of the default Spring AOP.
You must weave secured methods with the `AnnotationSecurityAspect` from the `spring-security-aspects` module.
+
[NOTE]
====
AspectJ follows Java's rule that annotations on interfaces are not inherited.
This means that methods that define the Security annotations on the interface are not secured.
Instead, you must place the Security annotation on the class when you use AspectJ.
====
* **mode**
This attribute can be set to "aspectj" to specify that AspectJ should be used instead of the default Spring AOP.
Secured methods must be woven with the `AnnotationSecurityAspect` from the `spring-security-aspects` module.
It is important to note that AspectJ follows Java's rule that annotations on interfaces are not inherited.
This means that methods that define the Security annotations on the interface will not be secured.
Instead, you must place the Security annotation on the class when using AspectJ.
[[nsa-global-method-security-order]]
`order`::
Lets the `order` advice be set for the method security interceptor.
* **order**
Allows the advice "order" to be set for the method security interceptor.
[[nsa-global-method-security-pre-post-annotations]]
`pre-post-annotations`::
Specifies whether the use of Spring Security's pre- and post-invocation annotations (`@PreFilter`, `@PreAuthorize`, `@PostFilter`, and `@PostAuthorize`) should be enabled for this application context.
Default: `disabled`
* **pre-post-annotations**
Specifies whether the use of Spring Security's pre and post invocation annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) should be enabled for this application context.
Defaults to "disabled".
[[nsa-global-method-security-proxy-target-class]]
`proxy-target-class`::
If `true`, class-based proxying is used instead of interface-based proxying.
* **proxy-target-class**
If true, class based proxying will be used instead of interface based proxying.
[[nsa-global-method-security-run-as-manager-ref]]
`run-as-manager-ref`::
A reference to an optional `RunAsManager` implementation, which is used by the configured `MethodSecurityInterceptor`.
* **run-as-manager-ref**
A reference to an optional `RunAsManager` implementation which will be used by the configured `MethodSecurityInterceptor`
[[nsa-global-method-security-secured-annotations]]
`secured-annotations`::
Specifies whether the use of Spring Security's `@Secured` annotations should be enabled for this application context.
Default: `disabled`
* **secured-annotations**
Specifies whether the use of Spring Security's @Secured annotations should be enabled for this application context.
Defaults to "disabled".
[[nsa-global-method-security-children]]
=== Child Elements of <global-method-security>
The `<global-method-security>` has the following child elements:
* <<nsa-after-invocation-provider,after-invocation-provider>>
* xref:servlet/appendix/namespace/http.adoc#nsa-expression-handler[expression-handler]
@ -120,41 +116,44 @@ The `<global-method-security>` has the following child elements:
[[nsa-after-invocation-provider]]
== <after-invocation-provider>
You can use the `<after-invocation-provider>` element to decorate an `AfterInvocationProvider` for use by the security interceptor that is maintained by the `<global-method-security>` namespace.
You can define zero or more of these elements within the `global-method-security` element, each with a `ref` attribute that points to an `AfterInvocationProvider` bean instance within your application context.
This element can be used to decorate an `AfterInvocationProvider` for use by the security interceptor maintained by the `<global-method-security>` namespace.
You can define zero or more of these within the `global-method-security` element, each with a `ref` attribute pointing to an `AfterInvocationProvider` bean instance within your application context.
[[nsa-after-invocation-provider-parents]]
=== Parent Elements of <after-invocation-provider>
The parent element of the `<after-invocation-provider>` is the <<nsa-global-method-security,global-method-security>> element.
* <<nsa-global-method-security,global-method-security>>
[[nsa-after-invocation-provider-attributes]]
=== <after-invocation-provider> Attributes
The `<after-invocation-provider>` element has a single attribute:
[[nsa-after-invocation-provider-ref]]
`ref`::
* **ref**
Defines a reference to a Spring bean that implements `AfterInvocationProvider`.
[[nsa-pre-post-annotation-handling]]
== <pre-post-annotation-handling>
The `<pre-post-annotation-handling>` lets us entirely replace the default expression-based mechanism for handling Spring Security's pre- and post-invocation annotations (`@PreFilter`, `@PreAuthorize`, `@PostFilter`, `@PostAuthorize`).
It applies only if these annotations are enabled.
Allows the default expression-based mechanism for handling Spring Security's pre and post invocation annotations (@PreFilter, @PreAuthorize, @PostFilter, @PostAuthorize) to be replaced entirely.
Only applies if these annotations are enabled.
[[nsa-pre-post-annotation-handling-parents]]
=== Parent Elements of <pre-post-annotation-handling>
The parent element of the `<pre-post-annotation-handling>` element is the <<nsa-global-method-security,global-method-security>> element.
* <<nsa-global-method-security,global-method-security>>
[[nsa-pre-post-annotation-handling-children]]
=== Child Elements of <pre-post-annotation-handling>
The `<pre-post-annotation-handling>` element has the following children:
* <<nsa-invocation-attribute-factory,invocation-attribute-factory>>
* <<nsa-post-invocation-advice,post-invocation-advice>>
@ -164,140 +163,150 @@ The `<pre-post-annotation-handling>` element has the following children:
[[nsa-invocation-attribute-factory]]
== <invocation-attribute-factory>
The `<invocation-attribute-factory>` element defines the `PrePostInvocationAttributeFactory` instance to use to generate pre- and post-invocation metadata from the annotated methods.
Defines the PrePostInvocationAttributeFactory instance which is used to generate pre and post invocation metadata from the annotated methods.
[[nsa-invocation-attribute-factory-parents]]
=== Parent Elements of <invocation-attribute-factory>
The parent element of the `<invocation-attribute-factory>` element is the <<nsa-pre-post-annotation-handling,`pre-post-annotation-handling`>> element.
* <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>>
[[nsa-invocation-attribute-factory-attributes]]
=== <invocation-attribute-factory> Attributes
The `<invocation-attribute-factory>` has a single attribute:
[[nsa-invocation-attribute-factory-ref]]
`ref`::
Defines a reference to a Spring bean ID.
* **ref**
Defines a reference to a Spring bean Id.
[[nsa-post-invocation-advice]]
== <post-invocation-advice>
The `<post-invocation-advice>` element customizes the `PostInvocationAdviceProvider` with the value of the `ref` attribute as the `PostInvocationAuthorizationAdvice` for the `<pre-post-annotation-handling>` element.
Customizes the `PostInvocationAdviceProvider` with the ref as the `PostInvocationAuthorizationAdvice` for the <pre-post-annotation-handling> element.
[[nsa-post-invocation-advice-parents]]
=== Parent Elements of <post-invocation-advice>
The parent element of the `<post-invocation-advice>` element is the <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>> element.
* <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>>
[[nsa-post-invocation-advice-attributes]]
=== <post-invocation-advice> Attributes
The `<post-invocation-advice>` has a single attribute:
[[nsa-post-invocation-advice-ref]]
`ref`::
Defines a reference to a Spring bean ID.
* **ref**
Defines a reference to a Spring bean Id.
[[nsa-pre-invocation-advice]]
== <pre-invocation-advice>
The `<pre-invocation-advice>` element customizes the `PreInvocationAuthorizationAdviceVoter` with the value of the `ref` attribute as the `PreInvocationAuthorizationAdviceVoter` for the `<pre-post-annotation-handling>` element.
Customizes the `PreInvocationAuthorizationAdviceVoter` with the ref as the `PreInvocationAuthorizationAdviceVoter` for the <pre-post-annotation-handling> element.
[[nsa-pre-invocation-advice-parents]]
=== Parent Elements of <pre-invocation-advice>
The parent element of the `<pre-invocation-advice>` is the <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>> element.
* <<nsa-pre-post-annotation-handling,pre-post-annotation-handling>>
[[nsa-pre-invocation-advice-attributes]]
=== <pre-invocation-advice> Attributes
The `<pre-invocation-advice>` element has a single attribute:
[[nsa-pre-invocation-advice-ref]]
ref::
Defines a reference to a Spring bean ID.
* **ref**
Defines a reference to a Spring bean Id.
[[nsa-protect-pointcut]]
== Securing Methods using <protect-pointcut>
Rather than defining security attributes on an individual method or class basis by using the `@Secured` annotation, you can define cross-cutting security constraints across whole sets of methods and interfaces in your service layer by using the `<protect-pointcut>` element.
== Securing Methods using
`<protect-pointcut>`
Rather than defining security attributes on an individual method or class basis using the `@Secured` annotation, you can define cross-cutting security constraints across whole sets of methods and interfaces in your service layer using the `<protect-pointcut>` element.
You can find an example in the xref:servlet/authorization/method-security.adoc#ns-protect-pointcut[namespace introduction].
[[nsa-protect-pointcut-parents]]
=== Parent Elements of <protect-pointcut>
The parent element of the `<protect-pointcut>` element is the <<nsa-global-method-security,global-method-security>> element.
* <<nsa-global-method-security,global-method-security>>
[[nsa-protect-pointcut-attributes]]
=== <protect-pointcut> Attributes
The `<protect-pointcut>` has the following attributes:
[[nsa-protect-pointcut-access]]
`access`::
Access configuration attributes list that applies to all methods that match the pointcut -- for example,
`ROLE_A,ROLE_B`.
* **access**
Access configuration attributes list that applies to all methods matching the pointcut, e.g.
"ROLE_A,ROLE_B"
[[nsa-protect-pointcut-expression]]
`expression`::
An AspectJ expression, including the `execution` keyword -- for example, `execution(int com.foo.TargetObject.countLength(String))`.
* **expression**
An AspectJ expression, including the `execution` keyword.
For example, `execution(int com.foo.TargetObject.countLength(String))`.
[[nsa-intercept-methods]]
== <intercept-methods>
You can use the `<intercept-methods>` element inside a bean definition to add a security interceptor to the bean and set up access configuration attributes for the bean's methods
Can be used inside a bean definition to add a security interceptor to the bean and set up access configuration attributes for the bean's methods
[[nsa-intercept-methods-attributes]]
=== <intercept-methods> Attributes
The `<intercept-methods>` element has a single attribute:
[[nsa-intercept-methods-access-decision-manager-ref]]
`access-decision-manager-ref`::
Optional `AccessDecisionManager` bean ID to be used by the created method security interceptor.
* **access-decision-manager-ref**
Optional AccessDecisionManager bean ID to be used by the created method security interceptor.
[[nsa-intercept-methods-children]]
=== Child Elements of <intercept-methods>
The child element of the `<intercept-methods>` is the <<nsa-protect,protect>> element.
* <<nsa-protect,protect>>
[[nsa-method-security-metadata-source]]
== <method-security-metadata-source>
The `<method-security-metadata-source>` element creates a `MethodSecurityMetadataSource` instance.
Creates a MethodSecurityMetadataSource instance
[[nsa-method-security-metadata-source-attributes]]
=== <method-security-metadata-source> Attributes
The `<method-security-metadata-source>` element has the following attributes:
[[nsa-method-security-metadata-source-id]]
`id`::
* **id**
A bean identifier, used for referring to the bean elsewhere in the context.
[[nsa-method-security-metadata-source-use-expressions]]
`use-expressions`::
Enables the use of expressions in the `access` attributes of `<intercept-url>` elements rather than the traditional list of configuration attributes.
Default: `false`
* **use-expressions**
Enables the use of expressions in the 'access' attributes in <intercept-url> elements rather than the traditional list of configuration attributes.
Defaults to 'false'.
If enabled, each attribute should contain a single Boolean expression.
If the expression evaluates to `true`, access is granted.
If the expression evaluates to 'true', access will be granted.
[[nsa-method-security-metadata-source-children]]
=== Child Elements of <method-security-metadata-source>
The `<method-security-metadata-source>` element has a single child element: <<nsa-protect,protect>>.
* <<nsa-protect,protect>>
@ -310,22 +319,22 @@ We strongly advise you NOT to mix "protect" declarations with any services provi
[[nsa-protect-parents]]
=== Parent Elements of <protect>
The `<protect>` element has two parent elements:
* <<nsa-intercept-methods,intercept-methods>>
* <<nsa-method-security-metadata-source,method-security-metadata-source>>
[[nsa-protect-attributes]]
=== <protect> Attributes
The `<protect>` element has the following attributes:
[[nsa-protect-access]]
`access`::
Access configuration attributes list that applies to the method -- for example,
`ROLE_A,ROLE_B`.
* **access**
Access configuration attributes list that applies to the method, e.g.
"ROLE_A,ROLE_B".
[[nsa-protect-method]]
`method`::
A method name.
* **method**
A method name

63
docs/modules/ROOT/pages/servlet/appendix/namespace/websocket.adoc
View File

@ -7,46 +7,40 @@ One concrete example of where this is useful is to provide authorization in WebS
[[nsa-websocket-message-broker]]
== <websocket-message-broker>
The `<websocket-message-broker>` element has two different modes.
If the <<nsa-websocket-message-broker-id,`websocket-message-broker@id`>> is not specified, it does the following things:
The websocket-message-broker element has two different modes.
If the <<nsa-websocket-message-broker-id,websocket-message-broker@id>> is not specified, then it will do the following things:
* Ensure that any `SimpAnnotationMethodMessageHandler` has the `AuthenticationPrincipalArgumentResolver` registered as a custom argument resolver.
This allows the use of `@AuthenticationPrincipal` to resolve the principal of the current `Authentication`.
* Ensures that the `SecurityContextChannelInterceptor` is automatically registered for the `clientInboundChannel`.
This populates the `SecurityContextHolder` with the user that is found in the message.
* Ensures that a `CsrfChannelInterceptor` is registered with the `clientInboundChannel`.
* Ensure that any SimpAnnotationMethodMessageHandler has the AuthenticationPrincipalArgumentResolver registered as a custom argument resolver.
This allows the use of `@AuthenticationPrincipal` to resolve the principal of the current `Authentication`
* Ensures that the SecurityContextChannelInterceptor is automatically registered for the clientInboundChannel.
This populates the SecurityContextHolder with the user that is found in the Message
* Ensures that a ChannelSecurityInterceptor is registered with the clientInboundChannel.
This allows authorization rules to be specified for a message.
* Ensures that a CsrfChannelInterceptor is registered with the clientInboundChannel.
This ensures that only requests from the original domain are enabled.
* Ensures that a `CsrfTokenHandshakeInterceptor` is registered with a `WebSocketHttpRequestHandler`, a `TransportHandlingSockJsService`, or a `DefaultSockJsService`.
This ensures that the expected `CsrfToken` from the `HttpServletRequest` is copied into the WebSocket Session attributes.
* Ensures that a CsrfTokenHandshakeInterceptor is registered with WebSocketHttpRequestHandler, TransportHandlingSockJsService, or DefaultSockJsService.
This ensures that the expected CsrfToken from the HttpServletRequest is copied into the WebSocket Session attributes.
If additional control is necessary, you can specify the ID, and a `ChannelSecurityInterceptor` is assigned to the specified ID.
You can then manually wire Spring's messaging infrastructure.
This is more cumbersome, but doing so provides greater control over the configuration.
If additional control is necessary, the id can be specified and a ChannelSecurityInterceptor will be assigned to the specified id.
All the wiring with Spring's messaging infrastructure can then be done manually.
This is more cumbersome, but provides greater control over the configuration.
[[nsa-websocket-message-broker-attributes]]
=== <websocket-message-broker> Attributes
The `<websocket-message-broker>` element has the following attributes:
[[nsa-websocket-message-broker-id]]
`id`::
A bean identifier, used to refer to the `ChannelSecurityInterceptor` bean elsewhere in the context.
* **id** A bean identifier, used for referring to the ChannelSecurityInterceptor bean elsewhere in the context.
If specified, Spring Security requires explicit configuration within Spring Messaging.
If not specified, Spring Security automatically integrates with the messaging infrastructure, as described in <<nsa-websocket-message-broker>>
If not specified, Spring Security will automatically integrate with the messaging infrastructure as described in <<nsa-websocket-message-broker>>
[[nsa-websocket-message-broker-same-origin-disabled]]
`same-origin-disabled`::
Disables the requirement for a CSRF token to be present in the Stomp headers.
Default: `false`
Changing the default lets other origins make SockJS connections.
* **same-origin-disabled** Disables the requirement for CSRF token to be present in the Stomp headers (default false).
Changing the default is useful if it is necessary to allow other origins to make SockJS connections.
[[nsa-websocket-message-broker-children]]
=== Child Elements of <websocket-message-broker>
The `<websocket-message-broker>` element has the following child elements:
* xref:servlet/appendix/namespace/http.adoc#nsa-expression-handler[expression-handler]
* <<nsa-intercept-message,intercept-message>>
@ -54,36 +48,27 @@ The `<websocket-message-broker>` element has the following child elements:
[[nsa-intercept-message]]
== <intercept-message>
The `<intercept-message>` defines an authorization rule for a message.
Defines an authorization rule for a message.
[[nsa-intercept-message-parents]]
=== Parent Elements of <intercept-message>
The parent element of the `<intercept-message>` element is the <<nsa-websocket-message-broker,`websocket-message-broker`>> element.
* <<nsa-websocket-message-broker,websocket-message-broker>>
[[nsa-intercept-message-attributes]]
=== <intercept-message> Attributes
The `<intercept-message>` element has the following attributes:
[[nsa-intercept-message-pattern]]
`pattern`::
An Ant-based pattern that matches on the message destination.
For example, `/**` matches any message with a destination, while `/admin/**` matches any message that has a destination that starts with `/admin/`.
* **pattern** An ant based pattern that matches on the Message destination.
For example, "/**" matches any Message with a destination; "/admin/**" matches any Message that has a destination that starts with "/admin/**".
[[nsa-intercept-message-type]]
`type`::
The type of message to match on.
SimpMessageType defines the valid values: `CONNECT`, `CONNECT_ACK`, `HEARTBEAT`, `MESSAGE`, `SUBSCRIBE`, `UNSUBSCRIBE`, `DISCONNECT`, `DISCONNECT_ACK`, and `OTHER`).
* **type** The type of message to match on.
Valid values are defined in SimpMessageType (i.e. CONNECT, CONNECT_ACK, HEARTBEAT, MESSAGE, SUBSCRIBE, UNSUBSCRIBE, DISCONNECT, DISCONNECT_ACK, OTHER).
[[nsa-intercept-message-access]]
`access`::
The expression used to secure the message.
Here are some examples:
+
* `denyAll`: Denies access to all of the matching messages.
* `permitAll`: Grants access to all of the matching Messages.
* `hasRole('ADMIN')`: Requires the current user to have a role of `ROLE_ADMIN` for the matching messages.
* **access** The expression used to secure the Message.
For example, "denyAll" will deny access to all of the matching Messages; "permitAll" will grant access to all of the matching Messages; "hasRole('ADMIN') requires the current user to have the role 'ROLE_ADMIN' for the matching Messages.