8 Adjudication Providers

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.

The following sections describe Adjudication provider concepts and functionality, and provide step-by-step instructions for developing a custom Adjudication provider:

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. For more information about configuring the WebLogic Adjudication provider, see "Configuring the WebLogic Adjudication Provider" in Oracle Fusion Middleware Securing 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:

  1. Create Runtime Classes Using the Appropriate SSPIs, or, optionally, use the Bulk Adjudication Providers

  2. Generate an MBean Type Using the WebLogic MBeanMaker

  3. Configure the Custom Adjudication Provider Using the Administration Console

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.

For more information about the AdjudicationProviderV2 SSPI and the getAdjudicator method, see the WebLogic Server API Reference Javadoc.

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 Chapter 7, "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.

For more information about the Adjudicator SSPI and the initialize and adjudicate methods, see the WebLogic Server API Reference Javadoc.

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.

Generate an MBean Type Using the WebLogic MBeanMaker

Before you start generating an MBean type for your custom security provider, you should first:

When you understand this information and have made your design decisions, create the MBean type for your custom Adjudication provider by following these steps:

  1. Create an MBean Definition File (MDF)

  2. Use the WebLogic MBeanMaker to Generate the MBean Type

  3. Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

  4. Install the MBean Type Into the WebLogic Server Environment

    Note:

    All instructions provided in this section assume that you are working in a Windows environment.

Create an MBean Definition File (MDF)

To create an MBean Definition File (MDF), follow these steps:

  1. Copy the MDF for the sample Authentication provider to a text file.

    Note:

    The MDF for the sample Authentication provider is called SampleAuthenticator.xml. (There is currently no sample Adjudication provider.)
  2. Modify the content of the <MBeanType> and <MBeanAttribute> elements in your MDF so that they are appropriate for your custom Adjudication provider.

  3. Add any custom attributes and operations (that is, additional <MBeanAttribute> and <MBeanOperation> elements) to your MDF.

  4. Save the file.

    Note:

    A complete reference of MDF element syntax is available in Appendix A, "MBean Definition File (MDF) Element Syntax."

Use the WebLogic MBeanMaker to Generate the MBean Type

Once you create your MDF, you are ready to run it through the WebLogic MBeanMaker. The WebLogic MBeanMaker is currently a command-line utility that takes as its input an MDF, and outputs some intermediate Java files, including an MBean interface, an MBean implementation, and an associated MBean information file. Together, these intermediate files form the MBean type for your custom security provider.

The instructions for generating an MBean type differ based on the design of your custom Adjudication provider. Follow the instructions that are appropriate to your situation:

No Custom Operations

If the MDF for your custom Adjudication provider does not include any custom operations, follow these steps:

  1. Create a new DOS shell.

  2. Type the following command:

    java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true
    weblogic.management.commo.WebLogicMBeanMaker
    

    where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

    Whenever xmlfile is provided, a new set of output files is generated.

    Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

    Note:

    The WebLogic MBeanMaker processes one MDF at a time. Therefore, you may have to repeat this process if you have multiple MDFs (in other words, multiple Adjudication providers).
  3. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

Custom Operations

If the MDF for your custom Adjudication provider does include custom operations, consider the following:

Are you creating an MBean type for the first time? If so, follow these steps:

  1. Create a new DOS shell.

  2. Type the following command:

    java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true
    weblogic.management.commo.WebLogicMBeanMaker
    

    where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

    Whenever xmlfile is provided, a new set of output files is generated.

    Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

    Note:

    As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDF's by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs (in other words, multiple Adjudication providers).
  3. For any custom operations in your MDF, implement the methods using the method stubs.

  4. Save the file.

  5. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

Are you updating an existing MBean type? If so, follow these steps:

  1. Copy your existing MBean implementation file to a temporary directory so that your current method implementations are not overwritten by the WebLogic MBeanMaker.

  2. Create a new DOS shell.

  3. Type the following command:

    java -DMDF=xmlfile -Dfiles=filesdir -DcreateStubs=true
    weblogic.management.commo.WebLogicMBeanMaker
    

    where the -DMDF flag indicates that the WebLogic MBeanMaker should translate the MDF into code, xmlFile is the MDF (the XML MBean Description File) and filesdir is the location where the WebLogic MBeanMaker will place the intermediate files for the MBean type.

    Whenever xmlfile is provided, a new set of output files is generated.

    Each time you use the -DcreateStubs=true flag, it overwrites any existing MBean implementation file.

    Note:

    As of version 9.0 of WebLogic Server, you can also provide a directory that contains multiple MDF's by using the -DMDFDIR <MDF directory name> option. In prior versions of WebLogic Server, the WebLogic MBeanMaker processed only one MDF at a time. Therefore, you had to repeat this process if you had multiple MDFs (in other words, multiple Adjudication providers).
  4. If you modified the MDF to include any custom operations that were not in the original MDF, implement the methods using the method stubs.

  5. Save the version of the MBean implementation file that is complete (that is, has all methods implemented).

  6. Copy this MBean implementation file into the directory where the WebLogic MBeanMaker placed the intermediate files for the MBean type. You specified this as filesdir in step 3. (You will be overriding the MBean implementation file generated by the WebLogic MBeanMaker as a result of step 3.)

  7. Proceed to Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF).

About the Generated MBean Interface File

The MBean interface file is the client-side API to the MBean that your runtime class or your MBean implementation will use to obtain configuration data. It is typically used in the initialize method as described in Understand the Purpose of the "Provider" SSPIs.

Because the WebLogic MBeanMaker generates MBean types from the MDF you created, the generated MBean interface file will have the name of the MDF, plus the text "MBean" appended to it. For example, the result of running the MyAdjudicator MDF through the WebLogic MBeanMaker will yield an MBean interface file called MyAdjudicatorMBean.java.

Use the WebLogic MBeanMaker to Create the MBean JAR File (MJF)

Once your have run your MDF through the WebLogic MBeanMaker to generate your intermediate files, and you have edited the MBean implementation file to supply implementations for the appropriate methods within it, you need to package the MBean files and the runtime classes for the custom Adjudication provider into an MBean JAR File (MJF). The WebLogic MBeanMaker also automates this process.

To create an MJF for your custom Adjudication provider, follow these steps:

  1. Create a new DOS shell.

  2. Type the following command:

    java -DMJF=jarfile -Dfiles=filesdir weblogic.management.commo.WebLogicMBeanMaker
    

    where the -DMJF flag indicates that the WebLogic MBeanMaker should build a JAR file containing the new MBean types, jarfile is the name for the MJF and filesdir is the location where the WebLogic MBeanMaker looks for the files to JAR into the MJF.

    Compilation occurs at this point, so errors are possible. If jarfile is provided, and no errors occur, an MJF is created with the specified name.

    Note:

    When you create a JAR file for a custom security provider, a set of XML binding classes and a schema are also generated. You can choose a namespace to associate with that schema. Doing so avoids the possibility that your custom classes will conflict with those provided by Oracle. The default for the namespace is vendor. You can change this default by passing the -targetNameSpace argument to the WebLogicMBeanMaker or the associated WLMBeanMaker ant task.

    If you want to update an existing MJF, simply delete the MJF and regenerate it. The WebLogic MBeanMaker also has a -DIncludeSource option, which controls whether source files are included into the resulting MJF. Source files include both the generated source and the MDF itself. The default is false. This option is ignored when -DMJF is not used.

The resulting MJF can be installed into your WebLogic Server environment, or distributed to your customers for installation into their WebLogic Server environments.

Install the MBean Type Into the WebLogic Server Environment

To install an MBean type into the WebLogic Server environment, copy the MJF into the WL_HOME\server\lib\mbeantypes directory, where WL_HOME is the top-level installation directory for WebLogic Server. This "deploys" your custom Adjudication provider—that is, it makes the custom Adjudication provider manageable from the WebLogic Server Administration Console.

Note:

WL_HOME\server\lib\mbeantypes is the default directory for installing MBean types. (Beginning with 9.0, security providers can be loaded from ...\domaindir\lib\mbeantypes as well.) However, if you want WebLogic Server to look for MBean types in additional directories, use the -Dweblogic.alternateTypesDirectory=<dir> command-line flag when starting your server, where <dir> is a comma-separated list of directory names. When you use this flag, WebLogic Server will always load MBean types from WL_HOME\server\lib\mbeantypes first, then will look in the additional directories and load all valid archives present in those directories (regardless of their extension). For example, if -Dweblogic.alternateTypesDirectory = dirX,dirY, WebLogic Server will first load MBean types from WL_HOME\server\lib\mbeantypes, then any valid archives present in dirX and dirY. If you instruct WebLogic Server to look in additional directories for MBean types and are using the Java Security Manager, you must also update the weblogic.policy file to grant appropriate permissions for the MBean type (and thus, the custom security provider). For more information, see "Using Java Security to Protect WebLogic Resources" in Oracle Fusion Middleware Programming Security for Oracle WebLogic Server.

You can create instances of the MBean type by configuring your custom Adjudication provider (see Configure the Custom Adjudication Provider Using the Administration Console), and then use those MBean instances from a GUI, from other Java code, or from APIs. For example, you can use the WebLogic Server Administration Console to get and set attributes and invoke operations, or you can develop other Java objects that instantiate MBeans and automatically respond to information that the MBeans supply. We recommend that you back up these MBean instances.

Configure the Custom Adjudication Provider Using the Administration Console

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 using the WebLogic Server Administration Console are described under "Configuring WebLogic Security Providers" in Oracle Fusion Middleware Securing Oracle WebLogic Server.