From 2cb2657f5b5e6dfbd26bb0b21d9c3eacadd34c2f Mon Sep 17 00:00:00 2001 From: Rob Winch Date: Tue, 25 Nov 2014 12:27:29 -0600 Subject: [PATCH] SEC-2702: Clean WebSocket Namespace documentation --- .../security/config/spring-security-4.0.rnc | 10 ++-- .../security/config/spring-security-4.0.xsd | 26 ++++++++-- .../config/doc/XsdDocumentedTests.groovy | 2 +- docs/manual/src/asciidoc/index.adoc | 49 +++++++++++++++++++ 4 files changed, 76 insertions(+), 11 deletions(-) diff --git a/config/src/main/resources/org/springframework/security/config/spring-security-4.0.rnc b/config/src/main/resources/org/springframework/security/config/spring-security-4.0.rnc index 376fc42ae7..22a3ccb25e 100644 --- a/config/src/main/resources/org/springframework/security/config/spring-security-4.0.rnc +++ b/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 = diff --git a/config/src/main/resources/org/springframework/security/config/spring-security-4.0.xsd b/config/src/main/resources/org/springframework/security/config/spring-security-4.0.xsd index b9397e79a6..1e7b23d94a 100644 --- a/config/src/main/resources/org/springframework/security/config/spring-security-4.0.xsd +++ b/config/src/main/resources/org/springframework/security/config/spring-security-4.0.xsd @@ -855,7 +855,13 @@ - 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. @@ -868,14 +874,20 @@ - 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. - Message + Creates an authorization rule for a message. @@ -885,13 +897,17 @@ - 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. - 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'. diff --git a/config/src/test/groovy/org/springframework/security/config/doc/XsdDocumentedTests.groovy b/config/src/test/groovy/org/springframework/security/config/doc/XsdDocumentedTests.groovy index 468978d391..db4c02ceb6 100644 --- a/config/src/test/groovy/org/springframework/security/config/doc/XsdDocumentedTests.groovy +++ b/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') diff --git a/docs/manual/src/asciidoc/index.adoc b/docs/manual/src/asciidoc/index.adoc index f787c0f386..621689b42a 100644 --- a/docs/manual/src/asciidoc/index.adoc +++ b/docs/manual/src/asciidoc/index.adoc @@ -7735,7 +7735,56 @@ Enables the use of expressions in the 'access' attributes in ele * <> +[[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]] +==== + +The messages attribute has two different modes. If the <> 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]] +===== 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-children]] +===== Child Elements of + + +* <> + +[[nsa-message-interceptor]] +==== + +Defines an authorization rule for a message. + + +[[nsa-message-interceptor-parents]] +===== Parent Elements of + + +* <> + + +[[nsa-message-interceptor-attributes]] +===== 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