PageRenderTime 16ms CodeModel.GetById 8ms app.highlight 3ms RepoModel.GetById 2ms app.codeStats 0ms

/hazelcast-documentation/src/main/docbook/manual/content/security/ClientSecurity.xml

https://bitbucket.org/gabral6_gmailcom/hazelcast
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&lt;? extends Permission&gt; 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>