SEC-2702: Clean WebSocket Namespace documentation

config/src/main/resources/org/springframework/security/config/spring-security-4.0.rnc

@@ -276,22 +276,22 @@ protect-pointcut.attlist &=
     attribute access {xsd:token}
 
 messages =
-    ## Messages
+    ## Allows securing a Message Broker. There are two modes. If no id is specified: ensures that any SimpAnnotationMethodMessageHandler has the AuthenticationPrincipalArgumentResolver registered as a custom argument resolver; ensures that the SecurityContextChannelInterceptor is automatically registered for the clientInboundChannel; and that a ChannelSecurityInterceptor is registered with the clientInboundChannel. If the id is specified, creates a ChannelSecurityInterceptor that can be manually registered with the clientInboundChannel.
     element messages { messages.attrlist, (message-interceptor*) }
 
 messages.attrlist &=
-    ## the id
+    ## A bean identifier, used for referring to the bean elsewhere in the context. If specified, explicit configuration within clientInboundChannel is required. If not specified, ensures that any SimpAnnotationMethodMessageHandler has the AuthenticationPrincipalArgumentResolver registered as a custom argument resolver; ensures that the SecurityContextChannelInterceptor is automatically registered for the clientInboundChannel; and that a ChannelSecurityInterceptor is registered with the clientInboundChannel.
     attribute id {xsd:token}?
 
 message-interceptor =
-    ## Message
+    ## Creates an authorization rule for a message.
     element message-interceptor {message-interceptor.attrlist}
 
 message-interceptor.attrlist &=
-    ## pattern
+    ## The destination ant pattern which will be mapped to the access attribute. For example, /** matches any message with a destination, /admin/** matches any message that has a destination that starts with admin.
     attribute pattern {xsd:token}?
 message-interceptor.attrlist &=
-    ## access
+     ## The access configuration attributes that apply for the configured message. For example, permitAll grants access to anyone, hasRole('ROLE_ADMIN') requires the user have the role 'ROLE_ADMIN'.
     attribute access {xsd:token}?
 
 http-firewall =

config/src/main/resources/org/springframework/security/config/spring-security-4.0.xsd

@@ -855,7 +855,13 @@
   </xs:attributeGroup>
   <xs:element name="messages">
       <xs:annotation>
-         <xs:documentation>Messages
+         <xs:documentation>Allows securing a Message Broker. There are two modes. If no id is specified: ensures that
+                any SimpAnnotationMethodMessageHandler has the AuthenticationPrincipalArgumentResolver
+                registered as a custom argument resolver; ensures that the
+                SecurityContextChannelInterceptor is automatically registered for the
+                clientInboundChannel; and that a ChannelSecurityInterceptor is registered with the
+                clientInboundChannel. If the id is specified, creates a ChannelSecurityInterceptor that
+                can be manually registered with the clientInboundChannel.
                 </xs:documentation>
       </xs:annotation>
       <xs:complexType>
@@ -868,14 +874,20 @@
   <xs:attributeGroup name="messages.attrlist">
       <xs:attribute name="id" type="xs:token">
          <xs:annotation>
-            <xs:documentation>the id
+            <xs:documentation>A bean identifier, used for referring to the bean elsewhere in the context. If specified,
+                explicit configuration within clientInboundChannel is required. If not specified, ensures
+                that any SimpAnnotationMethodMessageHandler has the
+                AuthenticationPrincipalArgumentResolver registered as a custom argument resolver; ensures
+                that the SecurityContextChannelInterceptor is automatically registered for the
+                clientInboundChannel; and that a ChannelSecurityInterceptor is registered with the
+                clientInboundChannel.
                 </xs:documentation>
          </xs:annotation>
       </xs:attribute>
   </xs:attributeGroup>
   <xs:element name="message-interceptor">
       <xs:annotation>
-         <xs:documentation>Message
+         <xs:documentation>Creates an authorization rule for a message.
                 </xs:documentation>
       </xs:annotation>
       <xs:complexType>
@@ -885,13 +897,17 @@
   <xs:attributeGroup name="message-interceptor.attrlist">
       <xs:attribute name="pattern" type="xs:token">
          <xs:annotation>
-            <xs:documentation>pattern
+            <xs:documentation>The destination ant pattern which will be mapped to the access attribute. For example, /**
+                matches any message with a destination, /admin/** matches any message that has a
+                destination that starts with admin.
                 </xs:documentation>
          </xs:annotation>
       </xs:attribute>
       <xs:attribute name="access" type="xs:token">
          <xs:annotation>
-            <xs:documentation>access
+            <xs:documentation>The access configuration attributes that apply for the configured message. For example,
+                permitAll grants access to anyone, hasRole('ROLE_ADMIN') requires the user have the role
+                'ROLE_ADMIN'.
                 </xs:documentation>
          </xs:annotation>
       </xs:attribute>

config/src/test/groovy/org/springframework/security/config/doc/XsdDocumentedTests.groovy

@@ -29,7 +29,7 @@ import spock.lang.*
  */
 class XsdDocumentedTests extends Specification {
 
-    def ignoredIds = ['nsa-any-user-service','nsa-any-user-service-parents','nsa-authentication','nsa-ldap','nsa-method-security','nsa-web']
+    def ignoredIds = ['nsa-any-user-service','nsa-any-user-service-parents','nsa-authentication','nsa-message-security','nsa-ldap','nsa-method-security','nsa-web']
     @Shared def reference = new File('../docs/manual/src/asciidoc/index.adoc')
 
     @Shared File schema31xDocument = new File('src/main/resources/org/springframework/security/config/spring-security-3.1.xsd')

docs/manual/src/asciidoc/index.adoc

@@ -7735,7 +7735,56 @@ Enables the use of expressions in the 'access' attributes in <intercept-url> ele
 
 * <<nsa-intercept-url,intercept-url>>
 
+[[nsa-message-security]]
+=== Message/WebSocket Security
 
+Spring Security 4.0+ provides support for authorizing messages. One concrete example of where this is useful is to provide authorization in WebSocket based applications.
+
+[[nsa-messages]]
+==== <messages>
+
+The messages attribute has two different modes. If the <<nsa-messages-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 ChannelSecurityInterceptor is registered with the clientInboundChannel. This allows authorization rules to be specified for a message.
+
+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-messages-attributes]]
+===== <messages> Attributes
+
+[[nsa-messages-id]]
+* **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 will automatically integrate with the messaging infrastructure as described in <<nsa-messages>>
+
+[[nsa-messages-children]]
+===== Child Elements of <messages>
+
+
+* <<nsa-message-interceptor,message-interceptor>>
+
+[[nsa-message-interceptor]]
+==== <message-interceptor>
+
+Defines an authorization rule for a message.
+
+
+[[nsa-message-interceptor-parents]]
+===== Parent Elements of <message-interceptor>
+
+
+* <<nsa-messages,messages>>
+
+
+[[nsa-message-interceptor-attributes]]
+===== <message-interceptor> Attributes
+
+[[nsa-message-interceptor-pattern]]
+* **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-message-interceptor-access]]
+* **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('ROLE_ADMIN') requires the current user to have the role 'ROLE_ADMIN' for the matching Messages.
 
 [[nsa-authentication]]
 === Authentication Services