org.example.azapi
Interface AzRequestContext


public interface AzRequestContext

The AzRequestContext is the structure used to collect all the information that is required to make one or more authorization requests.

The AzRequestContext is used as the input to a decision. It primarily consists of a group of collections of AzEntity objects, where each AzEntity contains a collection of AzAttributes describing that entity. From a XACML perspective, one may think of the AzEntity objects representing "actors" in a XACML decision request, where the actors consist of the entity making the request (Subject), the entity representing the request (Action), the entity representing that which access is being requested to (Resource) and an entity capturing general operating conditions under which the request is being made (Environment). one or more AzSubjects.

The official term XACML uses to distinguish these actors is "Category". The allowed Category identifiers are represented in AzApi by Enums that implement the AzCategoryId interface. The general rule is that a single authorization decision corresponds to a set of entities, where only one entity per Category is allowed.

The general mechanism by which multiple decisions can be requested in a single AzRequestContext object is by including multiple entities within the same category, then for each entity within a category, a separate decision will be made using each member of the specific category, against a fixed set of members, one each, of the other categories. The specifics of these mechanisms vary, with the most significant constraint being that AzResourceActionAssociations are created to indicate specific resource-action combinations against which a decision will be requested as opposed to simply requesting the cross-product of all resources and actions in an AzRequestContext.

Note: an AzRequestContext may be populated incrementally by several independent software components prior to the request actually being submitted to a PDP.
Note: there is no direct support for XACML Attribute Selectors, which are primarily xpaths used to access attributes in supplied xml content. All attributes from this AzAPI should be considered to be accessible using XACML Attribute Designators, which are based on using reference to the AttributeId(required), Issuer(optional), DataType(required), and Category(required, but generally implicit) associated with a XACML Attribute.

Author:
Rich

Method Summary
<T extends java.lang.Enum<T> & AzCategoryId>
boolean
addAzEntity(AzEntity<T> azEntity)
          Adds an AzEntity object to the request context, subject to the restrictions on the number of AzEntities of that type allowed.
 java.util.Set<AzResourceActionAssociation> addResourceActionAssociation(AzEntity<AzCategoryIdResource> resource, java.util.Set<AzEntity<AzCategoryIdAction>> actions)
          Add the cross-product of a single AzResource and a Set of AzActions to the AzRequestContext.
 java.util.Set<AzResourceActionAssociation> addResourceActionAssociation(java.util.Set<AzEntity<AzCategoryIdResource>> resources, AzEntity<AzCategoryIdAction> action)
          Add the cross-product of a Set of AzResources and a single AzAction to the AzRequestContext.
 java.util.Set<AzResourceActionAssociation> addResourceActionAssociation(java.util.Set<AzEntity<AzCategoryIdResource>> azResourceSet, java.util.Set<AzEntity<AzCategoryIdAction>> azActionSet)
          Add an AzResourceActionAssociation to the AzRequestContext for each possible AzResource-AzAction combination (cross-product (nxm)) of a Set of "n" AzResource entities and a Set of "m" AzAction entities.
 AzResourceActionAssociation createAndAddResourceActionAssociation(AzEntity<AzCategoryIdResource> azResource, AzEntity<AzCategoryIdAction> azAction)
          Add an AzResourceActionAssociation to the AzRequestContext by providing an AzResource entity and an AzAction entity, which the method will combine into the appropriate association object and add it to the Set of associations.
 AzEntity<AzCategoryIdAction> createAzEntity(AzCategoryIdAction t)
          Creates and returns an AzEntity object.
 AzEntity<AzCategoryIdEnvironment> createAzEntity(AzCategoryIdEnvironment t)
           
 AzEntity<AzCategoryIdResource> createAzEntity(AzCategoryIdResource t)
          Creates and returns an AzEntity object.
 AzEntity<AzCategoryIdSubjectAccess> createAzEntity(AzCategoryIdSubjectAccess t)
           
 AzEntity<AzCategoryIdSubjectCodebase> createAzEntity(AzCategoryIdSubjectCodebase t)
           
 AzEntity<AzCategoryIdSubjectIntermediary> createAzEntity(AzCategoryIdSubjectIntermediary t)
           
 AzEntity<AzCategoryIdSubjectRecipient> createAzEntity(AzCategoryIdSubjectRecipient t)
           
 AzEntity<AzCategoryIdSubjectRequestingMachine> createAzEntity(AzCategoryIdSubjectRequestingMachine t)
           
 java.util.Set<AzEntity<AzCategoryIdAction>> getActions()
          Get the Set> held by this AzRequestContext.
 java.util.Set<AzResourceActionAssociation> getAssociations()
          Return the set of tuples corresponding to the resource and action pairs that have been set in the resource context.
 AzEntity<AzCategoryIdAction> getAzEntity(AzCategoryIdAction t)
           
 AzEntity<AzCategoryIdEnvironment> getAzEntity(AzCategoryIdEnvironment t)
           
 AzEntity<AzCategoryIdResource> getAzEntity(AzCategoryIdResource t)
           
 AzEntity<AzCategoryIdSubjectAccess> getAzEntity(AzCategoryIdSubjectAccess t)
           
 AzEntity<AzCategoryIdSubjectCodebase> getAzEntity(AzCategoryIdSubjectCodebase t)
           
 AzEntity<AzCategoryIdSubjectIntermediary> getAzEntity(AzCategoryIdSubjectIntermediary t)
           
 AzEntity<AzCategoryIdSubjectRecipient> getAzEntity(AzCategoryIdSubjectRecipient t)
           
 AzEntity<AzCategoryIdSubjectRequestingMachine> getAzEntity(AzCategoryIdSubjectRequestingMachine t)
           
 AzEntity<AzCategoryIdEnvironment> getAzEnvironment()
          Return the AzEnvironment component of the AzRequestContext or null if it has not been added.
 java.util.Set<AzEntity<AzCategoryIdResource>> getResources()
          Get the Set of AzEntity's held by this AzRequestContext.
 void removeAllResourceActionAssociations()
          Remove all AzResourceActionAssociations from AzRequestContext.
 void removeResourceActionAssociation(AzEntity<AzCategoryIdResource> resource, AzEntity<AzCategoryIdAction> action)
          Delete the AzResource and AzAction association from the AzRequestContext collection of AzResourceActionAssociations.
 void removeResourceActionAssociations(java.util.Set<AzEntity<AzCategoryIdResource>> resources, java.util.Set<AzEntity<AzCategoryIdAction>> actions)
          delete the cross-product of the AzResource and AzAction sets from the AzRequestContext, should the association exist.
 

Method Detail

createAzEntity

AzEntity<AzCategoryIdResource> createAzEntity(AzCategoryIdResource t)
Creates and returns an AzEntity object.

The created AzEntity entity is added to the internal collection.

Note: The term "AzResource" may be used in discussion as a synonym for AzEntity

Note: adding an AzEntity object to internal collection does not guarantee the Resource will be used in a decision. In order to make that guarantee, the Resource needs to be added to an AzResourceActionAssociation object.

Parameters:
t - an AzCategoryIdResource Enum
Returns:
a new AzEntity object that is also added to the internal collection.

createAzEntity

AzEntity<AzCategoryIdAction> createAzEntity(AzCategoryIdAction t)
Creates and returns an AzEntity object.

The created AzEntity entity is added to the internal collection.

Note: The term "AzAction" may be used in discussion as a synonym for AzEntity

Note: adding an AzEntity object to internal collection does not guarantee the Action will be used in a decision. In order to make that guarantee, the Action needs to be added to an AzResourceActionAssociation object.

Parameters:
t - an AzCategoryIdAction Enum
Returns:
a new AzEntity object that is also added to the internal collection.

createAzEntity

AzEntity<AzCategoryIdEnvironment> createAzEntity(AzCategoryIdEnvironment t)

createAzEntity

AzEntity<AzCategoryIdSubjectAccess> createAzEntity(AzCategoryIdSubjectAccess t)

createAzEntity

AzEntity<AzCategoryIdSubjectCodebase> createAzEntity(AzCategoryIdSubjectCodebase t)

createAzEntity

AzEntity<AzCategoryIdSubjectIntermediary> createAzEntity(AzCategoryIdSubjectIntermediary t)

createAzEntity

AzEntity<AzCategoryIdSubjectRecipient> createAzEntity(AzCategoryIdSubjectRecipient t)

createAzEntity

AzEntity<AzCategoryIdSubjectRequestingMachine> createAzEntity(AzCategoryIdSubjectRequestingMachine t)

addAzEntity

<T extends java.lang.Enum<T> & AzCategoryId> boolean addAzEntity(AzEntity<T> azEntity)
Adds an AzEntity object to the request context, subject to the restrictions on the number of AzEntities of that type allowed.

Type Parameters:
T -
Parameters:
azEntity -
Returns:
boolean true if add was successful, otherwise false

getAzEntity

AzEntity<AzCategoryIdAction> getAzEntity(AzCategoryIdAction t)

getAzEntity

AzEntity<AzCategoryIdEnvironment> getAzEntity(AzCategoryIdEnvironment t)

getAzEntity

AzEntity<AzCategoryIdResource> getAzEntity(AzCategoryIdResource t)

getAzEntity

AzEntity<AzCategoryIdSubjectAccess> getAzEntity(AzCategoryIdSubjectAccess t)

getAzEntity

AzEntity<AzCategoryIdSubjectCodebase> getAzEntity(AzCategoryIdSubjectCodebase t)

getAzEntity

AzEntity<AzCategoryIdSubjectIntermediary> getAzEntity(AzCategoryIdSubjectIntermediary t)

getAzEntity

AzEntity<AzCategoryIdSubjectRecipient> getAzEntity(AzCategoryIdSubjectRecipient t)

getAzEntity

AzEntity<AzCategoryIdSubjectRequestingMachine> getAzEntity(AzCategoryIdSubjectRequestingMachine t)

createAndAddResourceActionAssociation

AzResourceActionAssociation createAndAddResourceActionAssociation(AzEntity<AzCategoryIdResource> azResource,
                                                                  AzEntity<AzCategoryIdAction> azAction)
Add an AzResourceActionAssociation to the AzRequestContext by providing an AzResource entity and an AzAction entity, which the method will combine into the appropriate association object and add it to the Set of associations.

Note that the association is based on associating the AzResource and AzAction objects, independent of the sets of attributes that the objects contain.
Therefore, the association can be established independently of the presence of resource-id and action-id attributes within the objects.

TBD: do we need to require the presence of resource-id and action-id attributes and thence a relate Exception? These are not required by XACML 2.0 (for resource-id see sections 6.3 (MAY contain one or more resource-id attributes), section 6.10 (lines 3080-3083), section B.6 )
(for action-id see section B.7, section 6.1 (lines 2896-2898), section 6.5

Parameters:
azResource -
azAction -
Returns:
a reference to the newly created azResourceActionAssociation, which may be used to correlate with a specific returned azResult.
See Also:
AzResourceActionAssociation, AzResult

getAssociations

java.util.Set<AzResourceActionAssociation> getAssociations()
Return the set of tuples corresponding to the resource and action pairs that have been set in the resource context.

Returns:
the Set currently active for this AzRequestContext

addResourceActionAssociation

java.util.Set<AzResourceActionAssociation> addResourceActionAssociation(java.util.Set<AzEntity<AzCategoryIdResource>> azResourceSet,
                                                                        java.util.Set<AzEntity<AzCategoryIdAction>> azActionSet)
Add an AzResourceActionAssociation to the AzRequestContext for each possible AzResource-AzAction combination (cross-product (nxm)) of a Set of "n" AzResource entities and a Set of "m" AzAction entities.
Note that as in the single entity parameters version of this method, that all the associations are established based on object pairs. This means that if multiple AzResource objects have the same resource-id attribute, that they will be treated as distinct resources for the purpose of making decisions.
Note also, that if another addResourceActionAssociation call is made with some of the same AzResource and AzAction objects, that any identical AzResource-AzAction pairs will degenerate to a single association. In general, after all the addResourceActionAssociation calls have been made there is conceptually an NxM matrix of N AzResources and M AzActions, where N is the sum of all the distinct AzResources in the individual calls and similarly for the M distinct AzActions.

For concreteness consider N AzResource rows and M AzAction columns, where a single AzResource is a single row and each cell in that row represents one of the M actions that potentially could be performed on that resource.

Similarly the removeResourceActionAssociation calls will remove any resource-action object pairs that have been added that are identical to any of the resource-action object pairs in the current remove call.
At the end of all the add and remove calls there will remain N' AzResource objects and M' AzAction objects participating in a maximum of N'xM' associations or a minimum of the larger of (N',M') associations, or any combination in between.

TBD: there has been some discussion that if the resource-id and action-id could be guaranteed to be present, singular, and unique in every AzResource and AzAction object, then resource-id<->action-id pairings would effectively be isomorphic (the same) as the pairings of the objects described above.
some of the considerations for not doing things this way include
that it is not required by XACML 2.0 or 3.0
that it is not possible to anticipate in advance the how or why that users will want to batch the requests,
that there is the possibility of two requests having AzResource entities for the same resource-id (or action-id), but with a different set of attributes,
and finally, it would seem a fairly straight-forward extension to this conceptualization to subclass the AzResource and AzAction entities and the AzRequestContext to apply filtering to achieve this effect.

Note: use of a MissingRequestIdException/MissingActionIdException, might be the mechanism to signal this condition, if necessary.

Parameters:
azResourceSet -
azActionSet -
Returns:
the Set objects that were just added to the collection
See Also:
createAndAddResourceActionAssociation(AzEntity, AzEntity)

addResourceActionAssociation

java.util.Set<AzResourceActionAssociation> addResourceActionAssociation(AzEntity<AzCategoryIdResource> resource,
                                                                        java.util.Set<AzEntity<AzCategoryIdAction>> actions)
Add the cross-product of a single AzResource and a Set of AzActions to the AzRequestContext.

Parameters:
resource -
actions -
Returns:
the Set objects that were just added to the collection

addResourceActionAssociation

java.util.Set<AzResourceActionAssociation> addResourceActionAssociation(java.util.Set<AzEntity<AzCategoryIdResource>> resources,
                                                                        AzEntity<AzCategoryIdAction> action)
Add the cross-product of a Set of AzResources and a single AzAction to the AzRequestContext.

Parameters:
resources -
action -
Returns:
a reference to the Set just added to AzRequestContext

removeResourceActionAssociation

void removeResourceActionAssociation(AzEntity<AzCategoryIdResource> resource,
                                     AzEntity<AzCategoryIdAction> action)
Delete the AzResource and AzAction association from the AzRequestContext collection of AzResourceActionAssociations.

It is only the association that is deleted. If the AzResource entity and/or the AzAction entity belong to other AzResourceActionAssociations, then the AzResource and/or AzAction object will be kept in its respective collection. If an AzAction or AzResource object entity no longer is part of any association, then no reference to the object will be kept by the AzRequestContext and it will be considered deleted from the AzRequestContext.

Parameters:
resource -
action -

removeResourceActionAssociations

void removeResourceActionAssociations(java.util.Set<AzEntity<AzCategoryIdResource>> resources,
                                      java.util.Set<AzEntity<AzCategoryIdAction>> actions)
delete the cross-product of the AzResource and AzAction sets from the AzRequestContext, should the association exist.

Parameters:
resources -
actions -

removeAllResourceActionAssociations

void removeAllResourceActionAssociations()
Remove all AzResourceActionAssociations from AzRequestContext. Helper method to safely reset collection of AzResourceActionAssociations.


getAzEnvironment

AzEntity<AzCategoryIdEnvironment> getAzEnvironment()
Return the AzEnvironment component of the AzRequestContext or null if it has not been added.

If null, then empty XACML Environment element will be sent when AzService.decide() call is issued. TBD: determine whether to support multiple AzEnvironment entities

Returns:
the AzEntity object

getResources

java.util.Set<AzEntity<AzCategoryIdResource>> getResources()
Get the Set of AzEntity's held by this AzRequestContext.

If no AzResources have been added an empty Set will be returned.

Only AzResources that have been identified by AzResourceActionAssociations will be included in authorization requests.

Returns:
the Set> that have been added to this AzRequestContext

getActions

java.util.Set<AzEntity<AzCategoryIdAction>> getActions()
Get the Set> held by this AzRequestContext.

If no Action entities have been added an empty Set will be returned.

Note: This Set may contain AzEntity objects that will not be included in decisions, unless they have been identified in the set of AzResourceActionAssociations that control for which resource-action pairs decisions are being requested.

Returns:
a Set> containing the actions that have been provided.