com.unboundid.directory.sdk.broker.api

Class PolicyInformationProvider

java.lang.Object

com.unboundid.directory.sdk.broker.api.PolicyInformationProvider

All Implemented Interfaces:

Configurable, ExampleUsageProvider, Reconfigurable<PolicyInformationProviderConfig>, UnboundIDExtension

@Extensible
 @BrokerExtension
 @ThreadSafety(level=INTERFACE_THREADSAFE)
public abstract class PolicyInformationProvider
extends java.lang.Object
implements UnboundIDExtension, Reconfigurable<PolicyInformationProviderConfig>, ExampleUsageProvider

This class defines an API that must be implemented by Broker extensions that retrieve XACML attributes as part of the Policy Information Point (PIP).

Configuring Policy Information Providers

In order to configure a policy information provider created using this API, use a command like:

      dsconfig create-policy-information-provider \
           --provider-name "{name}" \
           --type third-party \
           --set enabled:true \
           --set "extension-class:{class-name}" \
           --set "extension-argument:{name=value}" \
           --set "xacml-attribute-id:{attributeId} \
           --set "evaluation-order-index:{index}
 

where "{name}" is the name to use for the policy information provider instance, "{class-name}" is the fully-qualified name of the Java class that extends com.unboundid.directory.sdk.broker.api.PolicyInformationProvider, "{index}" is an integer from 1 to 9999 that is used to determine the position of this Policy Information Provider in the order of evaluation among all Policy Information Providers, "{attributeId}" identifies the XACML attribute(s) that this provider knows how to retrieve, and "{name=value}" represents name-value pairs for any additional arguments to provide to the Policy Information Provider. If multiple arguments should be provided to extension, then the "--set extension-argument:{name=value}" option should be provided multiple times. If the Policy Information Provider can retrieve more than one attribute type, then the "--set xacml-attribute-id:{attributeId}" option can also be provided multiple times.

Constructor Summary

Constructors

Constructor and Description
PolicyInformationProvider()

Method Summary

Modifier and Type	Method and Description
com.unboundid.ldap.sdk.ResultCode	applyConfiguration(PolicyInformationProviderConfig config, com.unboundid.util.args.ArgumentParser parser, java.util.List<java.lang.String> adminActionsRequired, java.util.List<java.lang.String> messages) Attempts to apply the configuration from the provided argument parser to this extension.
abstract boolean	canGetAttribute(java.lang.String categoryId, java.lang.String attributeId, RequestContext context) Determine whether this Policy Information Provider can retrieve the specified attribute from the specified attributes category.
abstract boolean	canGetJsonContent(java.lang.String categoryId, java.lang.String contextSelectorId, RequestContext context) Determine whether this Policy Information Provider can retrieve JSON content for the specified attributes category and optionally, ContextSelectorId.
void	defineConfigArguments(com.unboundid.util.args.ArgumentParser parser) Updates the provided argument parser to define any configuration arguments which may be used by this extension.
void	finalizePolicyInformationProvider() Performs any cleanup which may be necessary when this policy information provider is to be taken out of service.
abstract RequestAttribute	getAttribute(java.lang.String categoryId, java.lang.String attributeId, RequestContext context) Retrieve an attribute that has been requested by the policy engine in order to resolve a XACML AttributeDesignator element.
java.util.Map<java.util.List<java.lang.String>,java.lang.String>	getExamplesArgumentSets() Retrieves a map containing examples of configurations that may be used for this extension.
abstract java.lang.String[]	getExtensionDescription() Retrieves a human-readable description for this extension.
abstract java.lang.String	getExtensionName() Retrieves a human-readable name for this extension.
abstract java.lang.String	getJsonContent(java.lang.String categoryId, RequestContext context) Retrieve JSON content that has been requested by the policy engine in order to resolve a XACML AttributeSelector element.
java.lang.String	getJsonContent(java.lang.String categoryContent, java.lang.String contextSelectorId, RequestContext context) Retrieve additional or narrowed JSON content using the specified context selector.
void	initializePolicyInformationProvider(BrokerContext serverContext, PolicyInformationProviderConfig config, com.unboundid.util.args.ArgumentParser parser) Initializes this policy information provider.
boolean	isConfigurationAcceptable(PolicyInformationProviderConfig config, com.unboundid.util.args.ArgumentParser parser, java.util.List<java.lang.String> unacceptableReasons) Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension.

Methods inherited from class java.lang.Object

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

Constructor Detail

PolicyInformationProvider

public PolicyInformationProvider()

Method Detail

getExtensionName

public abstract java.lang.String getExtensionName()

Retrieves a human-readable name for this extension.

Specified by:

getExtensionName in interface UnboundIDExtension

Returns:

A human-readable name for this extension.

getExtensionDescription

public abstract java.lang.String[] getExtensionDescription()

Retrieves a human-readable description for this extension. Each element of the array that is returned will be considered a separate paragraph in generated documentation.

Specified by:

getExtensionDescription in interface UnboundIDExtension

Returns:

A human-readable description for this extension, or null or an empty array if no description should be available.

defineConfigArguments

public void defineConfigArguments(com.unboundid.util.args.ArgumentParser parser)
                           throws com.unboundid.util.args.ArgumentException

Updates the provided argument parser to define any configuration arguments which may be used by this extension. The argument parser may also be updated to define relationships between arguments (e.g., to specify required, exclusive, or dependent argument sets).

Specified by:

defineConfigArguments in interface Configurable

Parameters:

parser - The argument parser to be updated with the configuration arguments which may be used by this extension.

Throws:

com.unboundid.util.args.ArgumentException - If a problem is encountered while updating the provided argument parser.

initializePolicyInformationProvider

public void initializePolicyInformationProvider(BrokerContext serverContext,
                                                PolicyInformationProviderConfig config,
                                                com.unboundid.util.args.ArgumentParser parser)
                                         throws java.lang.Exception

Initializes this policy information provider.

Parameters:

serverContext - A handle to the server context for the server in which this extension is running.

config - The general configuration for this policy information provider.

parser - The argument parser which has been initialized from the configuration for this policy information provider.

Throws:

java.lang.Exception - If a problem occurs while initializing this policy information provider.

isConfigurationAcceptable

public boolean isConfigurationAcceptable(PolicyInformationProviderConfig config,
                                         com.unboundid.util.args.ArgumentParser parser,
                                         java.util.List<java.lang.String> unacceptableReasons)

Indicates whether the configuration represented by the provided argument parser is acceptable for use by this extension. The parser will have been used to parse any configuration available for this extension, and any automatic validation will have been performed. This method may be used to perform any more complex validation which cannot be performed automatically by the argument parser.

Specified by:

isConfigurationAcceptable in interface Reconfigurable<PolicyInformationProviderConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the proposed configuration for this extension.

unacceptableReasons - A list to which messages may be added to provide additional information about why the provided configuration is not acceptable.

Returns:

true if the configuration in the provided argument parser appears to be acceptable, or false if not.

applyConfiguration

public com.unboundid.ldap.sdk.ResultCode applyConfiguration(PolicyInformationProviderConfig config,
                                                            com.unboundid.util.args.ArgumentParser parser,
                                                            java.util.List<java.lang.String> adminActionsRequired,
                                                            java.util.List<java.lang.String> messages)

Attempts to apply the configuration from the provided argument parser to this extension.

Specified by:

applyConfiguration in interface Reconfigurable<PolicyInformationProviderConfig>

Parameters:

config - The general configuration for this extension.

parser - The argument parser that has been used to parse the new configuration for this extension.

adminActionsRequired - A list to which messages may be added to provide additional information about any additional administrative actions that may be required to apply some of the configuration changes.

messages - A list to which messages may be added to provide additional information about the processing performed by this method.

Returns:

A result code providing information about the result of applying the configuration change. A result of SUCCESS should be used to indicate that all processing completed successfully. Any other result will indicate that a problem occurred during processing.

finalizePolicyInformationProvider

public void finalizePolicyInformationProvider()

Performs any cleanup which may be necessary when this policy information provider is to be taken out of service.

getAttribute

public abstract RequestAttribute getAttribute(java.lang.String categoryId,
                                              java.lang.String attributeId,
                                              RequestContext context)
                                       throws java.lang.Exception

Retrieve an attribute that has been requested by the policy engine in order to resolve a XACML AttributeDesignator element.

Parameters:

categoryId - XACML category identifier. This is the category Id specified by the AttributeDesignator element in the policy that is requesting this attribute.

attributeId - XACML attribute identifier. This will be one of the identifiers specified by the xacml-attribute-id property of the configuration for this Policy Information Provider.

context - request context, can be used to retrieve other attributes from the request that may be needed in order to evaluate the requested attribute

Returns:

RequestAttribute object containing the requested attribute, never null.

Throws:

java.lang.Exception - if an error occurs retrieving the attribute

getJsonContent

public abstract java.lang.String getJsonContent(java.lang.String categoryId,
                                                RequestContext context)
                                         throws java.lang.Exception

Retrieve JSON content that has been requested by the policy engine in order to resolve a XACML AttributeSelector element.

Parameters:

categoryId - XACML category identifier. This is the category Id specified by the AttributeSelector element in the policy that is requesting this attribute.

context - request context, can be used to retrieve other attributes from the request that may be needed in order to retrieve the requested content

Returns:

a JSON-formatted object string, or null if no content is available.

Throws:

java.lang.Exception - if an error occurs retrieving the content

getJsonContent

public java.lang.String getJsonContent(java.lang.String categoryContent,
                                       java.lang.String contextSelectorId,
                                       RequestContext context)
                                throws java.lang.Exception

Retrieve additional or narrowed JSON content using the specified context selector.

Parameters:

categoryContent - Previously retrieved content for the Attributes category.

contextSelectorId - optional ContextSelectorId. This is the context selector string specified in the AttributeSelector.

context - request context, can be used to retrieve other attributes from the request that may be needed in order to retrieve the requested content

Returns:

a JSON-formatted object string, or null if no content is available.

Throws:

java.lang.Exception - if an error occurs retrieving the content

canGetAttribute

public abstract boolean canGetAttribute(java.lang.String categoryId,
                                        java.lang.String attributeId,
                                        RequestContext context)

Determine whether this Policy Information Provider can retrieve the specified attribute from the specified attributes category.

Parameters:

categoryId - XACML category identifier. This is the category Id specified by the AttributeDesignator element in the policy that is requesting this attribute.

attributeId - XACML attribute identifier as specified in the AttributeDesignator element in the policy that is requesting the attribute.

context - request context

Returns:

true if this PolicyInformationProvider is able to retrieve the specified attribute.

canGetJsonContent

public abstract boolean canGetJsonContent(java.lang.String categoryId,
                                          java.lang.String contextSelectorId,
                                          RequestContext context)

Determine whether this Policy Information Provider can retrieve JSON content for the specified attributes category and optionally, ContextSelectorId.

Parameters:

categoryId - XACML category identifier. This is the category Id specified by the AttributeSelector element in the policy that is requesting this attribute.

contextSelectorId - optional ContextSelectorId. This is the context selector string specified in the AttributeSelector.

context - request context

Returns:

true if this PolicyInformationProvider is able to retrieve the specified content.

getExamplesArgumentSets

public java.util.Map<java.util.List<java.lang.String>,java.lang.String> getExamplesArgumentSets()

Retrieves a map containing examples of configurations that may be used for this extension. The map key should be a list of sample arguments, and the corresponding value should be a description of the behavior that will be exhibited by the extension when used with that configuration.

Specified by:

getExamplesArgumentSets in interface ExampleUsageProvider

Returns:

A map containing examples of configurations that may be used for this extension. It may be null or empty if there should not be any example argument sets.