org.example.azapi
Interface AzService


public interface AzService

The AzService interface is the main entry point and service module for this package, which is generally referred to as the "AzAPI" or "AzApi" (Authorization Application Programming Interface).

An instance of an implementation of the AzService is obtained from the AzServiceFactory .

The AzService interface provides a factory interface from which instances of an AzRequestContext object can be created. The AzRequestContext object is the baseline object within the AzAPI that enables all the information to be assembled that is required to construct either a single authorization request or a collection that may include multiple authorization requests.

The AzRequestContext object that is created to submit an authorization decision request and the AzResponseContext object that is returned from that authorization decision request are compatible with the XACML 2.0 Core Specification:
http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-core-spec-os.pdf
as well as with the "multiple elements" option of the XACML 2.0 Multiple Resource Profile:
http://docs.oasis-open.org/xacml/2.0/access_control-xacml-2.0-mult-profile-spec-os.pdf

AzService also provides the main methods decide() and query() that process the AzRequestContext object, generally using enterprise infrastructure services (Policy Decision Points (PDPs) and Policy Information Points (PIPs)), and upon receiving results from the infrastructure services, the AzService prepares and returns the results in the AzResponseContext object. It is generally assumed that this AzAPI will be utilized by enterprise infrastructure Policy Enforcement Points (PEPs) to obtain the decision which enables the PEP to apply the appropriate enforcement actions.

Note: Being an "API", the "user" of this AzAPI is generally a program that calls the methods available in the AzAPI. That program will be referred to as the "AzAPI caller". The AzAPI may generally be considered to be making authorization requests on behalf of the Subject(s) represented within the AzRequestContext, and generally not on behalf of the "AzAPI caller", except in the case where Subject codebase may represent the AzAPI caller as part of some specific authorization request.

Note: Phonetically, the documentation in this package uses the consonant-sounding dialect of XACML, as in "a XACML Attribute", where the "X" is pronounced like a "Z".

Author:
Rich

Method Summary
 AzRequestContext createAzRequestContext()
          Returns a new AzRequestContext object that the AzAPI caller may use to populate with all the necessary information required (in the form of AzAttributes) for one or more XACML Authorization requests.
 AzResponseContext decide(AzRequestContext azRequestContext)
          Returns the authorization decision(s) in an AzResponseContext object.
 java.util.Set<AzResourceActionAssociation> query(java.lang.String scope, AzRequestContext azRequestContext, boolean allowedNotAllowed)
          Returns the set of AzResourceActionAssociations that are allowed (or not allowed, depending on boolean below) for the specified "scope", where "scope" is a String expression representing a set of target resources.
 AzResponseContext queryVerbose(java.lang.String scope, AzRequestContext azRequestContext)
          Returns an AzResponseContext that contains all the results for queries that are within the specified "scope", where "scope" is a String expression representing a set of target resources.
 

Method Detail

createAzRequestContext

AzRequestContext createAzRequestContext()
Returns a new AzRequestContext object that the AzAPI caller may use to populate with all the necessary information required (in the form of AzAttributes) for one or more XACML Authorization requests.

Returns:
an unpopulated azRequestContext object

decide

AzResponseContext decide(AzRequestContext azRequestContext)
Returns the authorization decision(s) in an AzResponseContext object.

There will be one AzDecision contained in an AzResult object in the AzResponseContext object, where one AzResult/AzDecision corresponds to one AzResourceActionAssociation contained in the submitted AzRequestContext object.

Parameters:
azRequestContext - an azRequestContext that has been prepared to contain the request information needed for one or more authorization decisions
Returns:
an azResponseContext that contains all the authorization decisions corresponding to the one or more requests that were provided in the azRequestContext

query

java.util.Set<AzResourceActionAssociation> query(java.lang.String scope,
                                                 AzRequestContext azRequestContext,
                                                 boolean allowedNotAllowed)
Returns the set of AzResourceActionAssociations that are allowed (or not allowed, depending on boolean below) for the specified "scope", where "scope" is a String expression representing a set of target resources.
The specific format of "scope" is based on how the resources and actions are represented within the Policy definitions on the PDP.

Parameters:
scope - PDP policy-specific resource representation
azRequestContext - only the AzEnvironment and AzSubject entities will be considered in the evaluation
allowedNotAllowed - true: return allowed results; false: return the not-allowed results.
Returns:
a set of azResourceActionAssociations representing the allowed (or not-allowed)resource-actions within the requested scope.

queryVerbose

AzResponseContext queryVerbose(java.lang.String scope,
                               AzRequestContext azRequestContext)
Returns an AzResponseContext that contains all the results for queries that are within the specified "scope", where "scope" is a String expression representing a set of target resources.

The AzResponseContext will contain full information including Obligations for each request within the scope.

Parameters:
scope - PDP policy-specific resource representation
azRequestContext - only the AzEnvironment and AzSubject entities will be considered in the evaluation
Returns:
azResponseContext with AzDecision and all info for resource-actions within the requested scope.