camel-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject [2/3] camel git commit: Added camel-spring-security docs to Gitbook
Date Wed, 08 Jun 2016 11:38:17 GMT
Added camel-spring-security docs to Gitbook


Branch: refs/heads/master
Commit: 48f129cfd6786e2eb50395f7e75edd9b6e1e556c
Parents: 438273d
Author: Andrea Cosentino <>
Authored: Wed Jun 8 13:22:38 2016 +0200
Committer: Andrea Cosentino <>
Committed: Wed Jun 8 13:38:00 2016 +0200

 .../src/main/docs/spring-security.adoc          | 217 +++++++++++++++++++
 docs/user-manual/en/                  |   1 +
 2 files changed, 218 insertions(+)
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 @@
+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
+Security] (formerly Acegi Security) and adds a declarative, role-based
+policy system to control whether a route can be executed by a given
+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.
+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
+The `<authorizationPolicy>` element may contain the following
+|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
+|`accessDecisionManager` |`accessDecisionManager` |The name of the Spring Security `AccessDecisionManager`
object in the
+|`authenticationAdapter` |DefaultAuthenticationAdapter |*Camel 2.4* The name of a *camel-spring-security*
+`AuthenticationAdapter` object in the context that is used to convert a
+`` into a Spring Security `Authentication`
+|`useThreadSecurityContext` |`true` |If a `` 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.
+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
+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`.
+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:
+import org.apache.camel.*;
+import org.apache.commons.codec.binary.Base64;
+public class MyAuthService implements Processor {
+    public void process(Exchange exchange) throws Exception {
+        // get the username and password from the HTTP header
+        //
+        String userpass = new String(Base64.decodeBase64(exchange.getIn().getHeader("Authorization",
+        String[] tokens = userpass.split(":");
+        // create an Authentication object
+        UsernamePasswordAuthenticationToken authToken = new UsernamePasswordAuthenticationToken(tokens[0],
+        // 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
+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
+``. You can customize
+the mapping of `Subject` to `Authentication` object by providing an
+implementation of the
+`` 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.
+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:
+  <exception></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>
+Maven users will need to add the following dependency to their `pom.xml`
+for this component:
+  <groupId>org.apache.camel</groupId> 
+  <artifactId>camel-spring-security</artifactId> 
+  <version>2.4.0</version> 
+This dependency will also pull in
+`` and
+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]
diff --git a/docs/user-manual/en/ b/docs/user-manual/en/
index 7639688..d698754 100644
--- a/docs/user-manual/en/
+++ b/docs/user-manual/en/
@@ -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)

View raw message