PageRenderTime 55ms CodeModel.GetById 22ms RepoModel.GetById 1ms app.codeStats 0ms

/components/camel-shiro/src/main/docs/shiro.adoc

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