Adjudication Providers

7 Adjudication Providers

This chapter describes adjudication provider concepts and functionality, and provides step-by-step instructions for developing a custom adjudication provider.

Adjudication involves resolving any authorization conflicts that may occur when more than one authorization provider is configured, by weighing the result of each authorization provider's Access Decision. In WebLogic Server, an adjudication provider is used to tally the results that multiple Access Decisions return, and determines the final PERMIT or DENY decision. An adjudication provider may also specify what should be done when an answer of ABSTAIN is returned from a single authorization provider's Access Decision.

This chapter includes the following sections:

The Adjudication Process

The use of adjudication providers is part of the authorization process, and is described in The Authorization Process.

Do You Need to Develop a Custom Adjudication Provider?

The default (that is, active) security realm for WebLogic Server includes a WebLogic Adjudication provider. The WebLogic Adjudication provider is responsible for adjudicating between potentially differing results rendered by multiple authorization providers' Access Decisions, and rendering a final verdict on whether or not access will be granted to a WebLogic resource.

The WebLogic Adjudication provider has an attribute called Require Unanimous Permit that governs its behavior. By default, the Require Unanimous Permit attribute is set to TRUE, which causes the WebLogic Adjudication provider to act as follows:

If all the authorization providers' Access Decisions return PERMIT, then return a final verdict of TRUE (that is, permit access to the WebLogic resource).
If some authorization providers' Access Decisions return PERMIT and others return ABSTAIN, then return a final verdict of FALSE (that is, deny access to the WebLogic resource).
If any of the authorization providers' Access Decisions return ABSTAIN or DENY, then return a final verdict of FALSE (that is, deny access to the WebLogic resource).

If you change the Require Unanimous Permit attribute to FALSE, the WebLogic Adjudication provider acts as follows:

If all the authorization providers' Access Decisions return PERMIT, then return a final verdict of TRUE (that is, permit access to the WebLogic resource).
If some authorization providers' Access Decisions return PERMIT and others return ABSTAIN, then return a final verdict of TRUE (that is, permit access to the WebLogic resource).
If any of the authorization providers' Access Decisions return DENY, then return a final verdict of FALSE (that is, deny access to the WebLogic resource).

Note:

You set the Require Unanimous Permit attributes when you configure the WebLogic Adjudication provider. See Configuring the WebLogic Adjudication Provider in Administering Security for Oracle WebLogic Server.

If you want an adjudication provider that behaves in a way that is different from what is described above, then you need to develop a custom adjudication provider. (Keep in mind that an adjudication provider may also specify what should be done when an answer of ABSTAIN is returned from a single authorization provider's Access Decision, based on your specific security requirements.)

How to Develop a Custom Adjudication Provider

If the WebLogic Adjudication provider does not meet your needs, you can develop a custom adjudication provider by following these steps:

Create Runtime Classes Using the Appropriate SSPIs, or, optionally, use the Bulk Adjudication Providers
Generate an MBean type for your custom adjudication provider by completing the steps described in Generate an MBean Type Using the WebLogic MBeanMaker.
Configure the Custom Adjudication Provider

Create Runtime Classes Using the Appropriate SSPIs

Before you start creating runtime classes, you should first:

When you understand this information and have made your design decisions, create the runtime classes for your custom adjudication provider by following these steps:

Implement the AdjudicationProviderV2 SSPI

To implement the AdjudicationProviderV2 SSPI, provide implementations for the methods described in Understand the Purpose of the Provider SSPIs and the following method:

getAdjudicator
```
public AdjudicatorV2 getAdjudicator()
```
The getAdjudicator method obtains the implementation of the AdjudicatorV2 SSPI. For a single runtime class called MyAdjudicationProviderImpl.java, the implementation of the getAdjudicator method would be:
```
return this;
```
If there are two runtime classes, then the implementation of the getAdjudicator method could be:
```
return new MyAdjudicatorImpl;
```
This is because the runtime class that implements the AdjudicationProviderV2 SSPI is used as a factory to obtain classes that implement the AdjudicatorV2 SSPI.

See Java API Reference for Oracle WebLogic Server for the AdjudicationProviderV2 SSPI.

Implement the AdjudicatorV2 SSPI

To implement the AdjudicatorV2 SSPI, provide implementations for the following methods:

initialize
```
public void initialize(AuthorizerMBean[] accessDecisionClassNames)
```
The initialize method initializes the names of all the configured authorization providers' Access Decisions that will be called to supply a result for the "is access allowed?" question. The accessDecisionClassNames parameter may also be used by an adjudication provider in its adjudicate method to favor a result from a particular Access Decision. For more information about authorization providers and Access Decisions, see Authorization Providers.
adjudicate
```
public boolean adjudicate(Result[] results, Resource resource,
                            ContextHandler handler)
```
The adjudicate method determines the answer to the "is access allowed?" question, given all the results from the configured authorization providers' Access Decisions.

See Java API Reference for Oracle WebLogic Server for the AdjudicatorV2 SSPI.

Bulk Adjudication Providers

This release of WebLogic Server includes bulk access versions of the following adjudication provider SSPI interfaces:

BulkAdjudicationProvider
BulkAdjudicator

The bulk access SSPI interfaces allow adjudication providers to receive multiple decision requests in one call rather than through multiple calls, typically in a 'for' loop. The intent of the bulk SSPI variants is to allow provider implementations to take advantage of internal performance optimizations, such as detecting that many of the passed-in Resource objects are protected by the same policy and will generate the same decision result.

There are subtle differences in how the non-bulk and bulk versions of the SSPI interfaces are used.

The BulkAdjudicator.adjudicate() method takes a List of Map (Resource, Result) instances, as passed in by the WebLogic Server Authorization Manager, which contain the results of each bulk access decision. The order of results is the same as the order of the Access Decision class names that were passed in the BulkAdjudicator.initialize() method.

Note too that the BulkAdjudicator.adjudicate() method returns a Set of Resource objects. If a Resource object is present in the set, access has been granted for that object; otherwise, access has been denied.

Configure the Custom Adjudication Provider

Configuring a custom adjudication provider means that you are adding the custom adjudication provider to your security realm, where it can be accessed by applications requiring adjudication services.

Configuring custom security providers is an administrative task, but it is a task that may also be performed by developers of custom security providers. The steps for configuring a custom adjudication provider are described in Configuring WebLogic Security Providers in Administering Security for Oracle WebLogic Server.