/hazelcast-documentation/src/main/docbook/manual/content/security/ClientSecurity.xml
XML | 522 lines | 472 code | 25 blank | 25 comment | 0 complexity | a48971458823a6dd817299ce34cbbad4 MD5 | raw file
1<?xml version="1.0" encoding="UTF-8"?> 2<!-- 3 ~ Copyright (c) 2008-2013, Hazelcast, Inc. All Rights Reserved. 4 ~ 5 ~ Licensed under the Apache License, Version 2.0 (the "License"); 6 ~ you may not use this file except in compliance with the License. 7 ~ You may obtain a copy of the License at 8 ~ 9 ~ http://www.apache.org/licenses/LICENSE-2.0 10 ~ 11 ~ Unless required by applicable law or agreed to in writing, software 12 ~ distributed under the License is distributed on an "AS IS" BASIS, 13 ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 ~ See the License for the specific language governing permissions and 15 ~ limitations under the License. 16 --> 17 18<sect1 xml:id="ClientSecurity" version="5.0" 19 xmlns="http://docbook.org/ns/docbook" 20 xmlns:xi="http://www.w3.org/2001/XInclude" 21 xmlns:xlink="http://www.w3.org/1999/xlink" 22 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 23 xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd 24 http://www.w3.org/1999/xlink http://www.w3.org/1999/xlink.xsd"> 25 <title>Native Client Security</title> 26 <para>Hazelcast's Client security includes both authentication and authorization.</para> 27 28 <sect2> 29 <title>Authentication</title> 30 <para>Authentication mechanism just works the same as cluster member authentication. Implementation of client 31 authentication requires a 32 <literal>Credentials</literal> 33 and one or more 34 <literal>LoginModule</literal>(s). Client side does not have/need a factory object to 35 create 36 <literal>Credentials</literal> 37 objects like<literal>ICredentialsFactory</literal>. 38 <literal>Credentials</literal> 39 must be created at client side and sent to connected node 40 during connection process. 41 <programlisting language="xml"><![CDATA[ 42<security enabled="true"> 43 <client-login-modules> 44 <login-module class-name="com.hazelcast.examples.MyRequiredClientLoginModule" usage="required"> 45 <properties> 46 <property name="property3">value3</property> 47 </properties> 48 </login-module> 49 <login-module class-name="com.hazelcast.examples.MySufficientClientLoginModule" usage="sufficient"> 50 <properties> 51 <property name="property4">value4</property> 52 </properties> 53 </login-module> 54 <login-module class-name="com.hazelcast.examples.MyOptionalClientLoginModule" usage="optional"> 55 <properties> 56 <property name="property5">value5</property> 57 </properties> 58 </login-module> 59 </client-login-modules> 60 ... 61</security> 62]]></programlisting> 63 </para> 64 <para>You can define as many as<literal>LoginModule</literal>s you wanted in 65 configuration. Those are executed in given order. Usage attribute has 4 values; 'required', 66 'requisite', 'sufficient' and 'optional' as defined in 67 <code>javax.security.auth.login.AppConfigurationEntry.LoginModuleControlFlag</code>. 68 </para> 69 70 <para> 71 <programlisting language="java"><![CDATA[ 72final Credentials credentials = new UsernamePasswordCredentials("dev", "dev-pass"); 73HazelcastInstance client = HazelcastClient.newHazelcastClient(credentials, "localhost"); 74]]></programlisting> 75 </para> 76 </sect2> 77 78 <sect2> 79 <title>Authorization</title> 80 <para>Hazelcast client authorization is configured by a client permission policy. Hazelcast has a default 81 permission policy 82 implementation that uses permission configurations defined in Hazelcast security configuration. Default 83 policy permission checks are done 84 against instance types (map, queue...), instance names (map, queue etc. name), instance actions (put, get, 85 remove, add...), 86 client endpoint addresses and client principal defined by 87 <literal>Credentials</literal> 88 object. 89 <emphasis role="italic">Instance and principal names and endpoint addresses 90 can be defined as wildcards(*). Take a look at 91 <link xlink:href="#WildcardConfiguration">Wildcard Name Configuration</link> 92 and 93 <link xlink:href="#ConfigSpecifyInterfaces">Newtwork Configuration</link> 94 pages. 95 </emphasis> 96 </para> 97 98 <para> 99 <programlisting language="xml"><![CDATA[ 100<security enabled="true"> 101 <client-permissions> 102 <!-- Principal 'admin' from endpoint '127.0.0.1' has all permissions. --> 103 <all-permissions principal="admin"> 104 <endpoints> 105 <endpoint>127.0.0.1</endpoint> 106 </endpoints> 107 </all-permissions> 108 109 <!-- Principals named 'dev' from all endpoints have 'create', 'destroy', 110 'put', 'get' permissions for map named 'default'. --> 111 <map-permission name="default" principal="dev"> 112 <actions> 113 <action>create</action> 114 <action>destroy</action> 115 <action>put</action> 116 <action>get</action> 117 </actions> 118 </map-permission> 119 120 <!-- All principals from endpoints '127.0.0.1' or matching to '10.10.*.*' 121 have 'put', 'get', 'remove' permissions for map 122 whose name matches to 'com.foo.entity.*'. --> 123 <map-permission name="com.foo.entity.*"> 124 <endpoints> 125 <endpoint>10.10.*.*</endpoint> 126 <endpoint>127.0.0.1</endpoint> 127 </endpoints> 128 <actions> 129 <action>put</action> 130 <action>get</action> 131 <action>remove</action> 132 </actions> 133 </map-permission> 134 135 <!-- Principals named 'dev' from endpoints matching to either 136 '192.168.1.1-100' or '192.168.2.*' 137 have 'create', 'offer', 'poll' permissions for all queues. --> 138 <queue-permission name="*" principal="dev"> 139 <endpoints> 140 <endpoint>192.168.1.1-100</endpoint> 141 <endpoint>192.168.2.*</endpoint> 142 </endpoints> 143 <actions> 144 <action>create</action> 145 <action>offer</action> 146 <action>poll</action> 147 </actions> 148 </queue-permission> 149 150 <!-- All principals from all endpoints have transaction permission.--> 151 <transaction-permission /> 152 </client-permissions> 153</security> 154]]></programlisting> 155 </para> 156 157 <para>Users also can define their own policy by implementing<literal> 158 com.hazelcast.security.IPermissionPolicy</literal>. 159 <programlisting language="java"><![CDATA[ 160package com.hazelcast.security; 161/** 162 * IPermissionPolicy is used to determine any Subject's 163 * permissions to perform a security sensitive Hazelcast operation. 164 * 165 */ 166public interface IPermissionPolicy { 167 void configure(SecurityConfig securityConfig, Properties properties); 168 169 PermissionCollection getPermissions(Subject subject, Class<? extends Permission> type); 170 171 void destroy(); 172}]]></programlisting> 173 </para> 174 <para>Permission policy implementations can access 175 <code>client-permissions</code> 176 in 177 configuration by using 178 <code>SecurityConfig.getClientPermissionConfigs()</code> 179 during 180 <code>configure(SecurityConfig securityConfig, Properties properties)</code> 181 method 182 is called by Hazelcast. 183 <code>IPermissionPolicy.getPermissions(Subject subject, 184 Class<? extends Permission> type) 185 </code> 186 method is used to determine a client 187 request has been granted permission to do a security-sensitive operation. Permission 188 policy should return a 189 <literal>PermissionCollection</literal> 190 containing permissions of 191 given type for given<literal>Subject</literal>. Hazelcast access controller will call 192 <code>PermissionCollection.implies(Permission)</code> 193 on returning 194 <literal>PermissionCollection</literal> 195 and will decide if current 196 <literal>Subject</literal> 197 has permitted to access to requested resources or 198 not. 199 </para> 200 </sect2> 201 202 <sect2> 203 <title>Permissions</title> 204 <para> 205 <orderedlist> 206 <listitem> 207 <para> 208 <emphasis role="bold">All Permission</emphasis> 209 </para> 210 <para> 211 <programlisting language="xml"><![CDATA[ 212<all-permissions principal="principal"> 213 <endpoints> 214 ... 215 </endpoints> 216</all-permissions> 217]]></programlisting> 218 </para> 219 </listitem> 220 <listitem> 221 <para> 222 <emphasis role="bold">Map Permission</emphasis> 223 </para> 224 <para> 225 <programlisting language="xml"><![CDATA[ 226<map-permission name="name" principal="principal"> 227 <endpoints> 228 ... 229 </endpoints> 230 <actions> 231 ... 232 </actions> 233</map-permission> 234]]></programlisting> 235 </para> 236 <para> 237 <emphasis role="bold">Actions:</emphasis> 238 <emphasis role="italic">all, create, destroy, 239 put, get, remove, listen, lock, stats 240 </emphasis> 241 </para> 242 </listitem> 243 244 <listitem> 245 <para> 246 <emphasis role="bold">Queue Permission</emphasis> 247 </para> 248 <para> 249 <programlisting language="xml"><![CDATA[ 250<queue-permission name="name" principal="principal"> 251 <endpoints> 252 ... 253 </endpoints> 254 <actions> 255 ... 256 </actions> 257</queue-permission> 258]]></programlisting> 259 </para> 260 <para> 261 <emphasis role="bold">Actions:</emphasis> 262 <emphasis role="italic">all, create, destroy, 263 offer, poll, get, remove, listen, stats 264 </emphasis> 265 </para> 266 </listitem> 267 268 <listitem> 269 <para> 270 <emphasis role="bold">Multimap Permission</emphasis> 271 </para> 272 <para> 273 <programlisting language="xml"><![CDATA[ 274<multimap-permission name="name" principal="principal"> 275 <endpoints> 276 ... 277 </endpoints> 278 <actions> 279 ... 280 </actions> 281</multimap-permission> 282]]></programlisting> 283 </para> 284 <para> 285 <emphasis role="bold">Actions:</emphasis> 286 <emphasis role="italic">all, create, destroy, 287 put, get, remove, listen, lock, stats 288 </emphasis> 289 </para> 290 </listitem> 291 292 <listitem> 293 <para> 294 <emphasis role="bold">Topic Permission</emphasis> 295 </para> 296 <para> 297 <programlisting language="xml"><![CDATA[ 298<topic-permission name="name" principal="principal"> 299 <endpoints> 300 ... 301 </endpoints> 302 <actions> 303 ... 304 </actions> 305</topic-permission> 306]]></programlisting> 307 </para> 308 <para> 309 <emphasis role="bold">Actions:</emphasis> 310 <emphasis role="italic">create, destroy, 311 publish, listen, stats 312 </emphasis> 313 </para> 314 </listitem> 315 316 <listitem> 317 <para> 318 <emphasis role="bold">List Permission</emphasis> 319 </para> 320 <para> 321 <programlisting language="xml"><![CDATA[ 322<list-permission name="name" principal="principal"> 323 <endpoints> 324 ... 325 </endpoints> 326 <actions> 327 ... 328 </actions> 329</list-permission> 330]]></programlisting> 331 </para> 332 <para> 333 <emphasis role="bold">Actions:</emphasis> 334 <emphasis role="italic">all, create, destroy, 335 add, set, get, remove, listen 336 </emphasis> 337 </para> 338 </listitem> 339 340 <listitem> 341 <para> 342 <emphasis role="bold">Set Permission</emphasis> 343 </para> 344 <para> 345 <programlisting language="xml"><![CDATA[ 346<set-permission name="name" principal="principal"> 347 <endpoints> 348 ... 349 </endpoints> 350 <actions> 351 ... 352 </actions> 353</set-permission> 354]]></programlisting> 355 </para> 356 <para> 357 <emphasis role="bold">Actions:</emphasis> 358 <emphasis role="italic">all, create, destroy, 359 add, get, remove, listen 360 </emphasis> 361 </para> 362 </listitem> 363 364 <listitem> 365 <para> 366 <emphasis role="bold">Lock Permission</emphasis> 367 </para> 368 <para> 369 <programlisting language="xml"><![CDATA[ 370<lock-permission name="name" principal="principal"> 371 <endpoints> 372 ... 373 </endpoints> 374 <actions> 375 ... 376 </actions> 377</lock-permission> 378]]></programlisting> 379 </para> 380 <para> 381 <emphasis role="bold">Actions:</emphasis> 382 <emphasis role="italic">all, create, destroy, 383 lock, stats 384 </emphasis> 385 </para> 386 </listitem> 387 388 <listitem> 389 <para> 390 <emphasis role="bold">AtomicNumber Permission</emphasis> 391 </para> 392 <para> 393 <programlisting language="xml"><![CDATA[ 394<atomic-number-permission name="name" principal="principal"> 395 <endpoints> 396 ... 397 </endpoints> 398 <actions> 399 ... 400 </actions> 401</atomic-number-permission> 402]]></programlisting> 403 </para> 404 <para> 405 <emphasis role="bold">Actions:</emphasis> 406 <emphasis role="italic">all, create, destroy, 407 increment, decrement, get, set, add, stats 408 </emphasis> 409 </para> 410 </listitem> 411 412 <listitem> 413 <para> 414 <emphasis role="bold">CountDownLatch Permission</emphasis> 415 </para> 416 <para> 417 <programlisting language="xml"><![CDATA[ 418<countdown-latch-permission name="name" principal="principal"> 419 <endpoints> 420 ... 421 </endpoints> 422 <actions> 423 ... 424 </actions> 425</countdown-latch-permission> 426]]></programlisting> 427 </para> 428 <para> 429 <emphasis role="bold">Actions:</emphasis> 430 <emphasis role="italic">all, create, destroy, 431 countdown, set, stats 432 </emphasis> 433 </para> 434 </listitem> 435 436 <listitem> 437 <para> 438 <emphasis role="bold">Semaphore Permission</emphasis> 439 </para> 440 <para> 441 <programlisting language="xml"><![CDATA[ 442<semaphore-permission name="name" principal="principal"> 443 <endpoints> 444 ... 445 </endpoints> 446 <actions> 447 ... 448 </actions> 449</semaphore-permission> 450]]></programlisting> 451 </para> 452 <para> 453 <emphasis role="bold">Actions:</emphasis> 454 <emphasis role="italic">all, create, destroy, 455 acquire, release, drain, stats 456 </emphasis> 457 </para> 458 </listitem> 459 460 <listitem> 461 <para> 462 <emphasis role="bold">Executor Service Permission</emphasis> 463 </para> 464 <para> 465 <programlisting language="xml"><![CDATA[ 466<executor-service-permission name="name" principal="principal"> 467 <endpoints> 468 ... 469 </endpoints> 470 <actions> 471 ... 472 </actions> 473</executor-service-permission> 474]]></programlisting> 475 </para> 476 <para> 477 <emphasis role="bold">Actions:</emphasis> 478 <emphasis role="italic">all, create, destroy, 479 execute 480 </emphasis> 481 </para> 482 </listitem> 483 484 <listitem> 485 <para> 486 <emphasis role="bold">Listener Permission</emphasis> 487 </para> 488 <para> 489 <programlisting language="xml"><![CDATA[ 490<listener-permission name="name" principal="principal"> 491 <endpoints> 492 ... 493 </endpoints> 494</listener-permission> 495]]></programlisting> 496 </para> 497 <para> 498 <emphasis role="bold">Names:</emphasis> 499 <emphasis role="italic">all, instance, 500 member 501 </emphasis> 502 </para> 503 </listitem> 504 505 <listitem> 506 <para> 507 <emphasis role="bold">Transaction Permission</emphasis> 508 </para> 509 <para> 510 <programlisting language="xml"><![CDATA[ 511<transaction-permission principal="principal"> 512 <endpoints> 513 ... 514 </endpoints> 515</transaction-permission> 516]]></programlisting> 517 </para> 518 </listitem> 519 </orderedlist> 520 </para> 521 </sect2> 522</sect1>