org.apache.geode.security.templates

## Class XmlAuthorization

- java.lang.Object
- - org.apache.geode.security.templates.XmlAuthorization

- All Implemented Interfaces:
    CacheCallback, Declarable, AccessControl

      public class XmlAuthorization
      extends java.lang.Object
      implements AccessControl

  An implementation of the `AccessControl` interface that allows authorization using the permissions as specified in the given XML file. The format of the XML file is specified in . It implements a role-based authorization at the operation level for each region. Each principal name may be associated with a set of roles. The name of the principal is obtained using the `Principal.getName()` method and no other information of the principal is utilized. Each role can be provided permissions to execute operations for each region. The top-level element in the XML is "acl" tag that contains the "role" and "permission" tags. The "role" tag contains the list of users that have been given that role. The name of the role is specified in the "role" attribute and the users are contained in the "user" tags insided the "role" tag. The "permissions" tag contains the list of operations allowed for a particular region. The role name is specified as the "role" attribute, the list of comma separated region names as the optional "regions" attribute and the operation names are contained in the "operation" tags inside the "permissions" tag. The allowed operation names are: GET, PUT, PUTALL, DESTROY, REGISTER_INTEREST, UNREGISTER_INTEREST, CONTAINS_KEY, KEY_SET, QUERY, EXECUTE_CQ, STOP_CQ, CLOSE_CQ, REGION_CLEAR, REGION_CREATE, REGION_DESTROY. These correspond to the operations in the `OperationContext.OperationCode` enumeration with the same name. When no region name is specified then the operation is allowed for all regions in the cache. Any permissions specified for regions using the "regions" attribute override these permissions. This allows users to provide generic permissions without any region name, and override for specific regions specified using the "regions" attribute. A cache-level operation (e.g. `OperationContext.OperationCode.REGION_DESTROY`) specified for a particular region is ignored i.e. the cache-level operations are only applicable when no region name is specified. A `OperationContext.OperationCode.QUERY` operation is permitted when either the `QUERY` permission is provided at the cache-level for the user or when `QUERY` permission is provided for all the regions that are part of the query string. Any roles specified in the "user" tag that do not have a specified permission set using the "permission" tags are ignored. When no `Principal` is associated with the current connection, then empty user name is used to search for the roles so an empty user name can be used to specify roles of unauthenticated clients (i.e. `Everyone`). This sample implementation is useful only for pre-operation checks and should not be used for post-operation authorization since it does nothing useful for post-operation case.
  Since:
    GemFire 5.5

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `DOC_URI_PROP_NAME`
    `protected LogWriter` | `securityLogWriter`
    `protected LogWriter` | `systemLogWriter`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `authorizeOperation(java.lang.String regionName, OperationContext context)` Return true if the given operation is allowed for the cache/region.
    `static void` | `clear()` Clear all the statically cached information.
    `void` | `close()` Clears the cached information for this principal.
    `static AccessControl` | `create()` Public static factory method to create an instance of `XmlAuthorization`.
    `void` | `init(java.security.Principal principal, DistributedMember remoteMember, Cache cache)` Initialize the `XmlAuthorization` callback for a client having the given principal.
    `static java.lang.String` | `normalizeRegionName(java.lang.String regionName)` Change the region name to a standard format having single '/' as separator and starting with a '/' as in standard POSIX paths

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface org.apache.geode.security.AccessControl

      `init, init`

    - ### Methods inherited from interface org.apache.geode.cache.Declarable

      `init, initialize`

- - ### Field Detail

    - #### DOC_URI_PROP_NAME

          public static final java.lang.String DOC_URI_PROP_NAME

      See Also:
        Constant Field Values

    - #### systemLogWriter

          protected LogWriter systemLogWriter

    - #### securityLogWriter

          protected LogWriter securityLogWriter

  - ### Method Detail

    - #### create

          public static AccessControl create()

      Public static factory method to create an instance of `XmlAuthorization`. The fully qualified name of the class (`org.apache.geode.security.templates.XmlAuthorization.create`) should be mentioned as the `security-client-accessor` system property to enable pre-operation authorization checks as implemented in this class.
      Returns:
        an object of `XmlAuthorization` class

    - #### clear

          public static void clear()

      Clear all the statically cached information.

    - #### normalizeRegionName

          public static java.lang.String normalizeRegionName(java.lang.String regionName)

      Change the region name to a standard format having single '/' as separator and starting with a '/' as in standard POSIX paths

    - #### init

          public void init(java.security.Principal principal,
                           DistributedMember remoteMember,
                           Cache cache)
                    throws NotAuthorizedException

      Initialize the `XmlAuthorization` callback for a client having the given principal. This method caches the full XML authorization file the first time it is invoked and caches all the permissions for the provided `principal` to speed up lookup the `authorizeOperation` calls. The permissions for the principal are maintained as a `Map` of region name to the `HashSet` of operations allowed for that region. A global entry with region name as empty string is also made for permissions provided for all the regions.
      Specified by:
        `init` in interface `AccessControl`
      Parameters:
        `principal` - the principal associated with the authenticated client
        `cache` - reference to the cache object
        `remoteMember` - the `DistributedMember` object for the remote authenticated client
      Throws:
        `NotAuthorizedException` - if some exception condition happens during the initialization while reading the XML; in such a case all subsequent client operations will throw `NotAuthorizedException`

    - #### authorizeOperation

          public boolean authorizeOperation(java.lang.String regionName,
                                            OperationContext context)

      Return true if the given operation is allowed for the cache/region. This looks up the cached permissions of the principal in the map for the provided region name. If none are found then the global permissions with empty region name are looked up. The operation is allowed if it is found this permission list.
      Specified by:
        `authorizeOperation` in interface `AccessControl`
      Parameters:
        `regionName` - When null then it indicates a cache-level operation, else the name of the region for the operation.
        `context` - the data required by the operation
      Returns:
        true if the operation is authorized and false otherwise

    - #### close

          public void close()

      Clears the cached information for this principal.
      Specified by:
        `close` in interface `CacheCallback`
      See Also:
        `RegionService.close()`, `Region.close()`, `Region.localDestroyRegion()`, `Region.destroyRegion()`, `AttributesMutator`