PageRenderTime 69ms CodeModel.GetById 38ms RepoModel.GetById 1ms app.codeStats 0ms

/docs/components/modules/others/pages/shiro.adoc

https://github.com/apache/camel
AsciiDoc | 309 lines | 249 code | 60 blank | 0 comment | 0 complexity | a5e903188598a7e16343effb5e0da137 MD5 | raw file
Possible License(s): Apache-2.0
  1. = Shiro Component
  2. :doctitle: Shiro
  3. :shortname: shiro
  4. :artifactid: camel-shiro
  5. :description: Security using Shiro
  6. :since: 2.5
  7. :supportlevel: Stable
  8. //Manually maintained attributes
  9. :camel-spring-boot-name: shiro
  10. *Since Camel {since}*
  11. The Shiro Security component in Camel is a security focused component,
  12. based on the Apache Shiro security project.
  13. Apache Shiro is a powerful and flexible open-source security framework
  14. that cleanly handles authentication, authorization, enterprise session
  15. management and cryptography. The objective of the Apache Shiro project
  16. is to provide the most robust and comprehensive application security
  17. framework available while also being very easy to understand and
  18. extremely simple to use.
  19. This camel shiro-security component allows authentication and
  20. authorization support to be applied to different segments of a camel
  21. route.
  22. Shiro security is applied on a route using a Camel Policy. A Policy in
  23. Camel utilizes a strategy pattern for applying interceptors on Camel
  24. Processors. It offering the ability to apply cross-cutting concerns (for
  25. example. security, transactions etc) on sections/segments of a camel
  26. route.
  27. Maven users will need to add the following dependency to their `pom.xml`
  28. for this component:
  29. [source,xml]
  30. ------------------------------------------------------------
  31. <dependency>
  32. <groupId>org.apache.camel</groupId>
  33. <artifactId>camel-shiro</artifactId>
  34. <version>x.x.x</version>
  35. <!-- use the same version as your Camel core version -->
  36. </dependency>
  37. ------------------------------------------------------------
  38. [[ShiroSecurity-ShiroSecurityBasics]]
  39. == Shiro Security Basics
  40. To employ Shiro security on a camel route, a ShiroSecurityPolicy object
  41. must be instantiated with security configuration details (including
  42. users, passwords, roles etc). This object must then be applied to a
  43. camel route. This ShiroSecurityPolicy Object may also be registered in
  44. the Camel registry (JNDI or ApplicationContextRegistry) and then
  45. utilized on other routes in the Camel Context.
  46. Configuration details are provided to the ShiroSecurityPolicy using an
  47. Ini file (properties file) or an Ini object. The Ini file is a standard
  48. Shiro configuration file containing user/role details as shown below
  49. [source,java]
  50. ------------------------------------------------------------------
  51. [users]
  52. # user 'ringo' with password 'starr' and the 'sec-level1' role
  53. ringo = starr, sec-level1
  54. george = harrison, sec-level2
  55. john = lennon, sec-level3
  56. paul = mccartney, sec-level3
  57. [roles]
  58. # 'sec-level3' role has all permissions, indicated by the
  59. # wildcard '*'
  60. sec-level3 = *
  61. # The 'sec-level2' role can do anything with access of permission
  62. # readonly (*) to help
  63. sec-level2 = zone1:*
  64. # The 'sec-level1' role can do anything with access of permission
  65. # readonly
  66. sec-level1 = zone1:readonly:*
  67. ------------------------------------------------------------------
  68. [[ShiroSecurity-InstantiatingaShiroSecurityPolicyObject]]
  69. == Instantiating a ShiroSecurityPolicy Object
  70. A ShiroSecurityPolicy object is instantiated as follows
  71. [source,java]
  72. ----------------------------------------------------------------------------------------
  73. private final String iniResourcePath = "classpath:shiro.ini";
  74. private final byte[] passPhrase = {
  75. (byte) 0x08, (byte) 0x09, (byte) 0x0A, (byte) 0x0B,
  76. (byte) 0x0C, (byte) 0x0D, (byte) 0x0E, (byte) 0x0F,
  77. (byte) 0x10, (byte) 0x11, (byte) 0x12, (byte) 0x13,
  78. (byte) 0x14, (byte) 0x15, (byte) 0x16, (byte) 0x17};
  79. List<permission> permissionsList = new ArrayList<permission>();
  80. Permission permission = new WildcardPermission("zone1:readwrite:*");
  81. permissionsList.add(permission);
  82. final ShiroSecurityPolicy securityPolicy =
  83. new ShiroSecurityPolicy(iniResourcePath, passPhrase, true, permissionsList);
  84. ----------------------------------------------------------------------------------------
  85. [[ShiroSecurity-ShiroSecurityPolicyOptions]]
  86. == ShiroSecurityPolicy Options
  87. [width="100%",cols="10%,10%,10%,90%",options="header",]
  88. |=======================================================================
  89. |Name |Default Value |Type |Description
  90. |`iniResourcePath or ini` |`none` |Resource String or Ini Object |A mandatory Resource String for the iniResourcePath or an instance of an
  91. Ini object must be passed to the security policy. Resources can be
  92. acquired from the file system, classpath, or URLs when prefixed with
  93. "file:, classpath:, or url:" respectively. For e.g "classpath:shiro.ini"
  94. |`passPhrase` |`An AES 128 based key` |byte[] |A passPhrase to decrypt ShiroSecurityToken(s) sent along with Message
  95. Exchanges
  96. |`alwaysReauthenticate` |`true` |boolean |Setting to ensure re-authentication on every individual request. If set
  97. to false, the user is authenticated and locked such than only requests
  98. from the same user going forward are authenticated.
  99. |`permissionsList` |`none` |List<Permission> |A List of permissions required in order for an authenticated user to be
  100. authorized to perform further action i.e continue further on the route.
  101. If no Permissions list or Roles List (see below) is provided to the
  102. ShiroSecurityPolicy object, then authorization is deemed as not
  103. required. Note that the default is that authorization is granted if any
  104. of the Permission Objects in the list are applicable.
  105. |`rolesList` |`none` |List<String> |A List of roles required in order for an authenticated
  106. user to be authorized to perform further action i.e continue further on
  107. the route. If no roles list or permissions list (see above) is provided
  108. to the ShiroSecurityPolicy object, then authorization is deemed as not
  109. required. Note that the default is that authorization is granted if any
  110. of the roles in the list are applicable.
  111. |`cipherService` |`AES` |org.apache.shiro.crypto.CipherService |Shiro ships with AES & Blowfish based CipherServices. You may use one
  112. these or pass in your own Cipher implementation
  113. |`base64` |`false` |`boolean` |To use base64 encoding for the security token header,
  114. which allows transferring the header over xref:ROOT:jms-component.adoc[JMS] etc. This
  115. option must also be set on `ShiroSecurityTokenInjector` as well.
  116. |`allPermissionsRequired` |`false` |`boolean` |The default is that authorization is granted if any of the
  117. Permission Objects in the permissionsList parameter are applicable. Set
  118. this to true to require all of the Permissions to be met.
  119. |`allRolesRequired` |`false` |`boolean` |The default is that authorization is granted if any of the
  120. roles in the rolesList parameter are applicable. Set this to true to
  121. require all of the roles to be met.
  122. |=======================================================================
  123. [[ShiroSecurity-ApplyingShiroAuthenticationonaCamelRoute]]
  124. == Applying Shiro Authentication on a Camel Route
  125. The ShiroSecurityPolicy, tests and permits incoming message exchanges
  126. containing a encrypted SecurityToken in the Message Header to proceed
  127. further following proper authentication. The SecurityToken object
  128. contains a Username/Password details that are used to determine where
  129. the user is a valid user.
  130. [source,java]
  131. -----------------------------------------------------------------------
  132. protected RouteBuilder createRouteBuilder() throws Exception {
  133. final ShiroSecurityPolicy securityPolicy =
  134. new ShiroSecurityPolicy("classpath:shiro.ini", passPhrase);
  135. return new RouteBuilder() {
  136. public void configure() {
  137. onException(UnknownAccountException.class).
  138. to("mock:authenticationException");
  139. onException(IncorrectCredentialsException.class).
  140. to("mock:authenticationException");
  141. onException(LockedAccountException.class).
  142. to("mock:authenticationException");
  143. onException(AuthenticationException.class).
  144. to("mock:authenticationException");
  145. from("direct:secureEndpoint").
  146. to("log:incoming payload").
  147. policy(securityPolicy).
  148. to("mock:success");
  149. }
  150. };
  151. }
  152. -----------------------------------------------------------------------
  153. [[ShiroSecurity-ApplyingShiroAuthorizationonaCamelRoute]]
  154. === Applying Shiro Authorization on a Camel Route
  155. Authorization can be applied on a camel route by associating a
  156. Permissions List with the ShiroSecurityPolicy. The Permissions List
  157. specifies the permissions necessary for the user to proceed with the
  158. execution of the route segment. If the user does not have the proper
  159. permission set, the request is not authorized to continue any further.
  160. [source,java]
  161. -------------------------------------------------------------------------------------------
  162. protected RouteBuilder createRouteBuilder() throws Exception {
  163. final ShiroSecurityPolicy securityPolicy =
  164. new ShiroSecurityPolicy("./src/test/resources/securityconfig.ini", passPhrase);
  165. return new RouteBuilder() {
  166. public void configure() {
  167. onException(UnknownAccountException.class).
  168. to("mock:authenticationException");
  169. onException(IncorrectCredentialsException.class).
  170. to("mock:authenticationException");
  171. onException(LockedAccountException.class).
  172. to("mock:authenticationException");
  173. onException(AuthenticationException.class).
  174. to("mock:authenticationException");
  175. from("direct:secureEndpoint").
  176. to("log:incoming payload").
  177. policy(securityPolicy).
  178. to("mock:success");
  179. }
  180. };
  181. }
  182. -------------------------------------------------------------------------------------------
  183. [[ShiroSecurity-CreatingaShiroSecurityTokenandinjectingitintoaMessageExchange]]
  184. == Creating a ShiroSecurityToken and injecting it into a Message Exchange
  185. A ShiroSecurityToken object may be created and injected into a Message
  186. Exchange using a Shiro Processor called ShiroSecurityTokenInjector. An
  187. example of injecting a ShiroSecurityToken using a
  188. ShiroSecurityTokenInjector in the client is shown below
  189. [source,java]
  190. -------------------------------------------------------------------------------------
  191. ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo", "starr");
  192. ShiroSecurityTokenInjector shiroSecurityTokenInjector =
  193. new ShiroSecurityTokenInjector(shiroSecurityToken, passPhrase);
  194. from("direct:client").
  195. process(shiroSecurityTokenInjector).
  196. to("direct:secureEndpoint");
  197. -------------------------------------------------------------------------------------
  198. [[ShiroSecurity-SendingMessagestoroutessecuredbyaShiroSecurityPolicy]]
  199. == Sending Messages to routes secured by a ShiroSecurityPolicy
  200. Messages and Message Exchanges sent along the camel route where the
  201. security policy is applied need to be accompanied by a SecurityToken in
  202. the Exchange Header. The SecurityToken is an encrypted object that holds
  203. a Username and Password. The SecurityToken is encrypted using AES 128
  204. bit security by default and can be changed to any cipher of your choice.
  205. Given below is an example of how a request may be sent using a
  206. ProducerTemplate in Camel along with a SecurityToken
  207. [source,java]
  208. -------------------------------------------------------------------------------------------------
  209. @Test
  210. public void testSuccessfulShiroAuthenticationWithNoAuthorization() throws Exception {
  211. //Incorrect password
  212. ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo", "stirr");
  213. // TestShiroSecurityTokenInjector extends ShiroSecurityTokenInjector
  214. TestShiroSecurityTokenInjector shiroSecurityTokenInjector =
  215. new TestShiroSecurityTokenInjector(shiroSecurityToken, passPhrase);
  216. successEndpoint.expectedMessageCount(1);
  217. failureEndpoint.expectedMessageCount(0);
  218. template.send("direct:secureEndpoint", shiroSecurityTokenInjector);
  219. successEndpoint.assertIsSatisfied();
  220. failureEndpoint.assertIsSatisfied();
  221. }
  222. -------------------------------------------------------------------------------------------------
  223. [[ShiroSecurity-UsingShiroSecurityToken]]
  224. == Using ShiroSecurityToken
  225. You can send a message to a Camel route with a header of key
  226. `ShiroSecurityConstants.SHIRO_SECURITY_TOKEN` of the type
  227. `org.apache.camel.component.shiro.security.ShiroSecurityToken` that
  228. contains the username and password. For example:
  229. [source,java]
  230. ---------------------------------------------------------------------------------------------------------------------------------------------
  231. ShiroSecurityToken shiroSecurityToken = new ShiroSecurityToken("ringo", "starr");
  232. template.sendBodyAndHeader("direct:secureEndpoint", "Beatle Mania", ShiroSecurityConstants.SHIRO_SECURITY_TOKEN, shiroSecurityToken);
  233. ---------------------------------------------------------------------------------------------------------------------------------------------
  234. You can also provide the username and password in two different headers
  235. as shown below:
  236. [source,java]
  237. --------------------------------------------------------------------------------------
  238. Map<String, Object> headers = new HashMap<String, Object>();
  239. headers.put(ShiroSecurityConstants.SHIRO_SECURITY_USERNAME, "ringo");
  240. headers.put(ShiroSecurityConstants.SHIRO_SECURITY_PASSWORD, "starr");
  241. template.sendBodyAndHeaders("direct:secureEndpoint", "Beatle Mania", headers);
  242. --------------------------------------------------------------------------------------
  243. When you use the username and password headers, then the
  244. ShiroSecurityPolicy in the Camel route will automatically transform those
  245. into a single header with key
  246. ShiroSecurityConstants.SHIRO_SECURITY_TOKEN with the token. Then token
  247. is either a `ShiroSecurityToken` instance, or a base64 representation as
  248. a String (the latter is when you have set base64=true).
  249. include::spring-boot:partial$starter.adoc[]