Added camel-spring-security docs to Gitbook
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/48f129cf Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/48f129cf Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/48f129cf Branch: refs/heads/master Commit: 48f129cfd6786e2eb50395f7e75edd9b6e1e556c Parents: 438273d Author: Andrea Cosentino <anco...@gmail.com> Authored: Wed Jun 8 13:22:38 2016 +0200 Committer: Andrea Cosentino <anco...@gmail.com> Committed: Wed Jun 8 13:38:00 2016 +0200 ---------------------------------------------------------------------- .../src/main/docs/spring-security.adoc | 217 +++++++++++++++++++ docs/user-manual/en/SUMMARY.md | 1 + 2 files changed, 218 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/48f129cf/components/camel-spring-security/src/main/docs/spring-security.adoc ---------------------------------------------------------------------- diff --git a/components/camel-spring-security/src/main/docs/spring-security.adoc b/components/camel-spring-security/src/main/docs/spring-security.adoc new file mode 100644 index 0000000..f3f3e8f --- /dev/null +++ b/components/camel-spring-security/src/main/docs/spring-security.adoc @@ -0,0 +1,217 @@ +[[SpringSecurity-SpringSecurity]] +Spring Security +~~~~~~~~~~~~~~~ + +*Available as of Camel 2.3* + +The *camel-spring-security* component provides role-based authorization +for Camel routes. It leverages the authentication and user services +provided by +http://static.springsource.org/spring-security/site/index.html[Spring +Security] (formerly Acegi Security) and adds a declarative, role-based +policy system to control whether a route can be executed by a given +principal. + +If you are not familiar with the Spring Security authentication and +authorization system, please review the current reference documentation +on the SpringSource web site linked above. + +[[SpringSecurity-Creatingauthorizationpolicies]] +Creating authorization policies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Access to a route is controlled by an instance of a +`SpringSecurityAuthorizationPolicy` object. A policy object contains the +name of the Spring Security authority (role) required to run a set of +endpoints and references to Spring Security `AuthenticationManager` and +`AccessDecisionManager` objects used to determine whether the current +principal has been assigned that role. Policy objects may be configured +as Spring beans or by using an `<authorizationPolicy>` element in Spring +XML. + +The `<authorizationPolicy>` element may contain the following +attributes: + +[width="100%",cols="10%,10%,80%",options="header",] +|======================================================================= +|Name |Default Value |Description + +|`id` |`null` |The unique Spring bean identifier which is used to reference the policy +in routes (required) + +|`access` |`null` |The Spring Security authority name that is passed to the access decision +manager (required) + +|`authenticationManager` |`authenticationManager` |The name of the Spring Security `AuthenticationManager` object in the +context + +|`accessDecisionManager` |`accessDecisionManager` |The name of the Spring Security `AccessDecisionManager` object in the +context + +|`authenticationAdapter` |DefaultAuthenticationAdapter |*Camel 2.4* The name of a *camel-spring-security* +`AuthenticationAdapter` object in the context that is used to convert a +`javax.security.auth.Subject` into a Spring Security `Authentication` +instance. + +|`useThreadSecurityContext` |`true` |If a `javax.security.auth.Subject` cannot be found in the In message +header under Exchange.AUTHENTICATION, check the Spring Security +`SecurityContextHolder` for an `Authentication` object. + +|`alwaysReauthenticate` |`false` |If set to true, the `SpringSecurityAuthorizationPolicy` will always call +`AuthenticationManager.authenticate()` each time the policy is accessed. +|======================================================================= + +[[SpringSecurity-ControllingaccesstoCamelroutes]] +Controlling access to Camel routes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A Spring Security `AuthenticationManager` and `AccessDecisionManager` +are required to use this component. Here is an example of how to +configure these objects in Spring XML using the Spring Security +namespace: + +Now that the underlying security objects are set up, we can use them to +configure an authorization policy and use that policy to control access +to a route: + +In this example, the endpoint `mock:end` will not be executed unless a +Spring Security `Authentication` object that has been or can be +authenticated and contains the `ROLE_ADMIN` authority can be located by +the _admin_ `SpringSecurityAuthorizationPolicy`. + +[[SpringSecurity-Authentication]] +Authentication +^^^^^^^^^^^^^^ + +The process of obtaining security credentials that are used for +authorization is not specified by this component. You can write your own +processors or components which get authentication information from the +exchange depending on your needs. For example, you might create a +processor that gets credentials from an HTTP request header originating +in the link:jetty.html[Jetty] component. No matter how the credentials +are collected, they need to be placed in the In message or the +`SecurityContextHolder` so the Camel link:spring-security.html[Spring +Security] component can access them: + +[source,java] +---------------------------------------------------------------------------------------------------------------------- +import javax.security.auth.Subject; +import org.apache.camel.*; +import org.apache.commons.codec.binary.Base64; +import org.springframework.security.authentication.*; + + +public class MyAuthService implements Processor { + public void process(Exchange exchange) throws Exception { + // get the username and password from the HTTP header + // http://en.wikipedia.org/wiki/Basic_access_authentication + String userpass = new String(Base64.decodeBase64(exchange.getIn().getHeader("Authorization", String.class))); + String[] tokens = userpass.split(":"); + + // create an Authentication object + UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(tokens[0], tokens[1]); + + // wrap it in a Subject + Subject subject = new Subject(); + subject.getPrincipals().add(authToken); + + // place the Subject in the In message + exchange.getIn().setHeader(Exchange.AUTHENTICATION, subject); + + // you could also do this if useThreadSecurityContext is set to true + // SecurityContextHolder.getContext().setAuthentication(authToken); + } +} +---------------------------------------------------------------------------------------------------------------------- + +The `SpringSecurityAuthorizationPolicy` will automatically authenticate +the `Authentication` object if necessary. + +There are two issues to be aware of when using the +`SecurityContextHolder` instead of or in addition to the +`Exchange.AUTHENTICATION` header. First, the context holder uses a +thread-local variable to hold the `Authentication` object. Any routes +that cross thread boundaries, like *seda* or *jms*, will lose the +`Authentication` object. Second, the Spring Security system appears to +expect that an `Authentication` object in the context is already +authenticated and has roles (see the Technical Overview +http://static.springsource.org/spring-security/site/docs/3.0.x/reference/technical-overview.html#tech-intro-authentication[section +5.3.1] for more details). + +The default behavior of *camel-spring-security* is to look for a +`Subject` in the `Exchange.AUTHENTICATION` header. This `Subject` must +contain at least one principal, which must be a subclass of +`org.springframework.security.core.Authentication`. You can customize +the mapping of `Subject` to `Authentication` object by providing an +implementation of the +`org.apache.camel.component.spring.security.AuthenticationAdapter` to +your `<authorizationPolicy>` bean. This can be useful if you are working +with components that do not use Spring Security but do provide a +`Subject`. At this time, only the link:cxf.html[CXF] component populates +the `Exchange.AUTHENTICATION` header. + +[[SpringSecurity-Handlingauthenticationandauthorizationerrors]] +Handling authentication and authorization errors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If authentication or authorization fails in the +`SpringSecurityAuthorizationPolicy`, a `CamelAuthorizationException` +will be thrown. This can be handled using Camel's standard exception +handling methods, like the link:exception-clause.html[Exception Clause]. +The `CamelAuthorizationException` will have a reference to the ID of the +policy which threw the exception so you can handle errors based on the +policy as well as the type of exception: + +[source,xml] +------------------------------------------------------------------------------------------ +<onException> + <exception>org.springframework.security.authentication.AccessDeniedException</exception> + <choice> + <when> + <simple>${exception.policyId} == 'user'</simple> + <transform> + <constant>You do not have ROLE_USER access!</constant> + </transform> + </when> + <when> + <simple>${exception.policyId} == 'admin'</simple> + <transform> + <constant>You do not have ROLE_ADMIN access!</constant> + </transform> + </when> + </choice> +</onException> +------------------------------------------------------------------------------------------ + +[[SpringSecurity-Dependencies]] +Dependencies +^^^^^^^^^^^^ + +Maven users will need to add the following dependency to their `pom.xml` +for this component: + +[source,xml] +------------------------------------------------- + +<dependency> + <groupId>org.apache.camel</groupId> + <artifactId>camel-spring-security</artifactId> + <version>2.4.0</version> +</dependency> +------------------------------------------------- + +This dependency will also pull in +`org.springframework.security:spring-security-core:3.0.3.RELEASE` and +`org.springframework.security:spring-security-config:3.0.3.RELEASE`. + +[[SpringSecurity-SeeAlso]] +See Also +^^^^^^^^ + +* link:configuring-camel.html[Configuring Camel] +* link:component.html[Component] +* link:endpoint.html[Endpoint] +* link:getting-started.html[Getting Started] + +* link:components.html[Components] + http://git-wip-us.apache.org/repos/asf/camel/blob/48f129cf/docs/user-manual/en/SUMMARY.md ---------------------------------------------------------------------- diff --git a/docs/user-manual/en/SUMMARY.md b/docs/user-manual/en/SUMMARY.md index 7639688..d698754 100644 --- a/docs/user-manual/en/SUMMARY.md +++ b/docs/user-manual/en/SUMMARY.md @@ -253,6 +253,7 @@ * [Spring-Javaconfig](spring-java-config.adoc) * [Spring-Ldap](spring-ldap.adoc) * [Spring-Redis](spring-redis.adoc) + * [Spring-Security](spring-security.adoc) * [Telegram](telegram.adoc) * [Twitter](twitter.adoc) * [Websocket](websocket.adoc)
